Merge pull request #7237 from esengine/release-notes/v1.19.3

docs(release): prepare v1.19.3 notes
2026-11-07 10:45:59 -10:00 · 2026-08-03 02:05:59 +08:00 · 2026-08-02 18:03:23 +00:00 · 2026-08-03 01:52:13 +08:00 · 2026-08-03 01:27:16 +08:00 · 2026-08-03 01:14:37 +08:00
883 changed files with 121376 additions and 14966 deletions
@@ -1,3 +1,14 @@
 # Every pull request requests review from the maintainers below.
 # Either maintainer can review and merge any change.
 * @SivanCola @esengine
+
+# Keep the provider-side signing policy and its GitHub control plane under the
+# same explicit review boundary as the machine-readable contract.
+/.signpath/ @SivanCola @esengine
+/.github/workflows/release-stable.yml @SivanCola @esengine
+/.github/workflows/release-stable-trigger.yml @SivanCola @esengine
+/.github/workflows/release-desktop.yml @SivanCola @esengine
+/scripts/complete-signpath-request.ps1 @SivanCola @esengine
+/scripts/package-windows-desktop.sh @SivanCola @esengine
+/scripts/verify-windows-authenticode.ps1 @SivanCola @esengine
+/cmd/signpath-contract/ @SivanCola @esengine
@@ -2,6 +2,15 @@

 -

+## Issues
+
+<!--
+If this resolves a report, put `Fixes #123` on its own line — GitHub only
+auto-closes from a bare line, so `- Fixes #123` in a list does nothing and the
+report stays open. If it only relates to one, use `Refs #123` instead: the
+release workflow then asks that reporter to verify once the fix ships.
+-->
+
 ## Verification

 -
@@ -4,6 +4,18 @@ on:
  pull_request_target:
    branches: [main-v2]
    types: [opened, synchronize, reopened, edited, ready_for_review]
+    # The guard only cares about the prompt/tool surfaces listed in
+    # scripts/check-cache-impact.sh; PRs confined to clearly unrelated paths
+    # can never trip it, so skip the run entirely. Keep the ignore list
+    # conservative: when in doubt, run.
+    paths-ignore:
+      - 'docs/**'
+      - 'site/**'
+      - 'release-notes/**'
+      - 'workers/**'
+      - 'benchmarks/**'
+      - 'npm/**'
+      - '*.md'

 permissions:
  contents: read
@@ -14,22 +14,78 @@ concurrency:
  cancel-in-progress: true

 jobs:
+  # Cheap path gate for pull requests. PRs confined to docs/site/release-notes
+  # (or top-level Markdown) skip the heavy Go jobs, and PRs that cannot affect
+  # the desktop module skip the desktop jobs. Job-level `if` reports skipped,
+  # which satisfies the required status checks (lint, race, test) — a
+  # workflow-level paths-ignore would leave required checks pending and block
+  # merges. Gated jobs skip only on an explicit `false` output: wrapped in
+  # `always()`, a failed `changes` job (or a missing output) makes them run
+  # the full matrix instead of silently passing required checks as skipped.
+  # Pushes to main-v2 always run everything.
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+      desktop: ${{ steps.filter.outputs.desktop }}
+      site: ${{ steps.filter.outputs.site }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: filter
+        run: |
+          code=true; desktop=true; site=true
+          base=""
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            base="${{ github.event.pull_request.base.sha }}"
+          elif [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ]; then
+            base="${{ github.event.before }}"
+          fi
+          if [ -n "$base" ] && git cat-file -e "$base^{commit}" 2>/dev/null; then
+            files=$(git diff --name-only "$base" HEAD)
+            if [ -n "$files" ]; then
+              code=false; desktop=false; site=false
+              # Root-module CI: desktop/ is a separate module, so only the
+              # clearly unrelated paths below can skip it.
+              if echo "$files" | grep -qvE '^(docs/|site/|release-notes/|desktop/|workers/|[^/]+\.md$)'; then code=true; fi
+              # desktop/ imports the root kernel via `replace reasonix => ../`,
+              # so only this clearly-unrelated set is safe to skip.
+              if echo "$files" | grep -qvE '^(docs/|site/|release-notes/|workers/|benchmarks/|npm/|[^/]+\.md$)'; then desktop=true; fi
+              if echo "$files" | grep -q '^site/'; then site=true; fi
+            fi
+          fi
+          { echo "code=$code"; echo "desktop=$desktop"; echo "site=$site"; } >> "$GITHUB_OUTPUT"
+
+  # The ruleset requires the per-OS check names (test (ubuntu-latest) etc.).
+  # A matrix job skipped at job level reports no per-leg checks at all, so
+  # those required checks would stay "Expected" and block merging. The job
+  # therefore always runs and the steps do the gating: when the changes
+  # detector reports the diff is unrelated, every step skips and each leg
+  # reports success in seconds. `always()` also keeps the legs alive when
+  # the changes job itself fails (fail-open: an empty output != 'false').
  test:
+    needs: changes
+    if: always()
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
+    env:
+      RUN_STEPS: ${{ github.event_name != 'pull_request' || needs.changes.outputs.code != 'false' }}
    steps:
-      - uses: actions/checkout@v7
+      - if: env.RUN_STEPS == 'true'
+        uses: actions/checkout@v7

-      - uses: actions/setup-go@v6
+      - if: env.RUN_STEPS == 'true'
+        uses: actions/setup-go@v6
        with:
          go-version-file: go.mod
          cache: true

      - name: Install and verify Linux sandbox backend
-        if: runner.os == 'Linux'
+        if: env.RUN_STEPS == 'true' && runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y bubblewrap
@@ -45,7 +101,7 @@ jobs:
      # Skipped on Windows: the runner checks out CRLF, so gofmt -l flags every
      # file. gofmt output is OS-independent, so the Unix legs already cover it.
      - name: gofmt
-        if: runner.os != 'Windows'
+        if: env.RUN_STEPS == 'true' && runner.os != 'Windows'
        run: |
          # Root module only — desktop/ is a separate module with its own tooling.
          unformatted=$(gofmt -l . | grep -v '^desktop/' || true)
@@ -56,13 +112,15 @@ jobs:
          fi

      - name: vet
+        if: env.RUN_STEPS == 'true'
        run: go vet ./...

      - name: build
+        if: env.RUN_STEPS == 'true'
        run: go build ./...

      - name: test
-        if: runner.os != 'Windows'
+        if: env.RUN_STEPS == 'true' && runner.os != 'Windows'
        env:
          # Run the prompt-cache prefix-stability guard (TestCacheHit*) in CI: a
          # regression there silently tanks the cache hit rate the project is
@@ -70,8 +128,19 @@ jobs:
          REASONIX_RELEASE_CACHE_GUARD: "1"
        run: go test ./...

-      - name: test
-        if: runner.os == 'Windows'
+      # Pull requests run a Windows smoke suite: the packages that actually
+      # carry *_windows.go code, plus cmd/. The full ./... sweep stays on
+      # pushes to main-v2; the Unix legs always run the full suite.
+      - name: test (Windows smoke)
+        if: env.RUN_STEPS == 'true' && runner.os == 'Windows' && github.event_name == 'pull_request'
+        timeout-minutes: 10
+        env:
+          REASONIX_RELEASE_CACHE_GUARD: "1"
+          WINDOWS_SANDBOX_WAIT_MS: "20000"
+        run: go test -p 4 -timeout=3m ./internal/agent/... ./internal/cli/... ./internal/control/... ./internal/filelock/... ./internal/fileutil/... ./internal/hook/... ./internal/instruction/... ./internal/mcplaunch/... ./internal/notify/... ./internal/proc/... ./internal/remote/... ./internal/repair/... ./internal/sandbox/... ./internal/sysproxy/... ./internal/workspacelease/... ./cmd/...
+
+      - name: test (full)
+        if: env.RUN_STEPS == 'true' && runner.os == 'Windows' && github.event_name != 'pull_request'
        timeout-minutes: 10
        env:
          # Run the prompt-cache prefix-stability guard (TestCacheHit*) in CI: a
@@ -84,6 +153,8 @@ jobs:
        run: go test -p 4 -timeout=3m ./...

  race:
+    needs: changes
+    if: always() && (github.event_name != 'pull_request' || needs.changes.outputs.code != 'false')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
@@ -108,13 +179,24 @@ jobs:

      # The matrix never runs -race (it needs cgo); the project's concurrency
      # (plugin fan-out, background phase B, jobs Kill/Wait) would otherwise
-      # ship without race coverage.
-      - name: test -race
+      # ship without race coverage. Pull requests sweep only the
+      # concurrency-heavy packages so this required check stays fast; pushes
+      # to main-v2 keep the full ./... sweep as the safety net.
+      - name: test -race (concurrency packages)
+        if: github.event_name == 'pull_request'
+        env:
+          REASONIX_RELEASE_CACHE_GUARD: "1"
+        run: go test -race ./internal/agent/... ./internal/plugin/... ./internal/jobs/... ./internal/proc/... ./internal/sandbox/... ./internal/filelock/... ./internal/eventwire/... ./internal/remote/...
+
+      - name: test -race (full)
+        if: github.event_name != 'pull_request'
        env:
          REASONIX_RELEASE_CACHE_GUARD: "1"
        run: go test -race ./...

  desktop:
+    needs: changes
+    if: always() && (github.event_name != 'pull_request' || needs.changes.outputs.desktop != 'false')
    runs-on: ubuntu-22.04
    defaults:
      run:
@@ -174,6 +256,9 @@ jobs:
          pnpm --dir frontend install --frozen-lockfile
          pnpm --dir frontend build

+      - name: Test integrated terminal frontend
+        run: pnpm --dir frontend test:terminal
+
      - name: vet
        run: go vet ./...

@@ -190,11 +275,34 @@ jobs:
      - name: test
        run: go test ./...

+  # desktop/ is a separate module, so the root macOS matrix above does not
+  # compile or exercise the native PTY implementation.
+  desktop-macos:
+    needs: changes
+    if: always() && (github.event_name != 'pull_request' || needs.changes.outputs.desktop != 'false')
+    runs-on: macos-latest
+    defaults:
+      run:
+        working-directory: desktop
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: desktop/go.mod
+          cache: true
+          cache-dependency-path: desktop/go.sum
+
+      - name: Test integrated terminal and PTY lifecycle
+        run: go test -race -run 'Test(ResolveTerminal|Terminal|EmptyTerminal|UnixTerminalProcess)' .
+
  # Desktop project-root matching is case-insensitive only on Windows
  # (sameDesktopPath folds case when os.PathSeparator is '\'), so the
  # regression tests for that contract are named *OnWindows and can never
  # run on the ubuntu leg above.
  desktop-windows:
+    needs: changes
+    if: always() && (github.event_name != 'pull_request' || needs.changes.outputs.desktop != 'false')
    runs-on: windows-latest
    defaults:
      run:
@@ -237,14 +345,21 @@ jobs:
        timeout-minutes: 15
        run: go test ./...

+      # Installer packaging is packaging validation, not a code gate: run it
+      # on pushes to main-v2 (the release pipeline builds installers again
+      # anyway), but let pull requests stop after the test step.
      - name: Install NSIS
+        if: github.event_name != 'pull_request'
        run: pwsh -NoProfile -File ../scripts/install-nsis.ps1

      - name: Build Windows installer and portable archive
+        if: github.event_name != 'pull_request'
        timeout-minutes: 20
        run: ../scripts/desktop-build.sh windows/amd64 v0.0.0-ci canary

  lint:
+    needs: changes
+    if: always() && (github.event_name != 'pull_request' || needs.changes.outputs.code != 'false')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
@@ -260,21 +375,45 @@ jobs:
          version: v2.12.2
          args: --timeout=5m

+      # Report-only complexity monitor for internal/agent. Does not duplicate the
+      # main lint/test/race gates; funlen+cyclop run with issues-exit-code=0 so
+      # the baseline is visible as a CI summary/artifact without blocking merges.
+      - name: agent complexity report
+        if: always()
+        run: |
+          # Reuse the golangci-lint binary installed by the previous step.
+          bash scripts/agent-complexity-report.sh
+
+      - name: upload agent complexity report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: agent-complexity-report
+          path: agent-complexity-report.txt
+          if-no-files-found: ignore
+          retention-days: 14
+
      - name: release workflow contracts
        run: |
          go run github.com/rhysd/actionlint/cmd/[email protected] \
            -ignore 'label "windows-11-arm" is unknown' \
            .github/workflows/release-stable.yml \
+            .github/workflows/prepare-release-notes.yml \
+            .github/workflows/release-stable-trigger.yml \
            .github/workflows/release.yml \
            .github/workflows/release-npm.yml \
-            .github/workflows/release-desktop.yml
+            .github/workflows/release-desktop.yml \
+            .github/workflows/release-verify-issues.yml
          bash scripts/release-workflows.test.sh
+          node scripts/check-single-release-public-contract.mjs

  # The site/ auth client has security-sensitive redirect-validation logic
  # (safeNext) covered by node:test unit tests. Those tests use only Node
  # builtins, so no `npm install` is needed — run them directly on every PR so
  # a regression in redirect validation fails the build instead of shipping.
  site:
+    needs: changes
+    if: always() && (github.event_name != 'pull_request' || needs.changes.outputs.site != 'false')
    runs-on: ubuntu-latest
    defaults:
      run:
@@ -290,6 +429,8 @@ jobs:
        run: npm test

  govulncheck:
+    needs: changes
+    if: always() && (github.event_name != 'pull_request' || needs.changes.outputs.code != 'false')
    runs-on: ubuntu-latest
    continue-on-error: true # informational — stdlib vulns need a Go patch release
    steps:
@@ -307,6 +448,8 @@ jobs:
        run: govulncheck ./...

  coverage:
+    needs: changes
+    if: always() && (github.event_name != 'pull_request' || needs.changes.outputs.code != 'false')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
@@ -1,10 +1,20 @@
 name: CodeQL

 on:
+  # Docs/release-notes/root-Markdown changes carry no analyzable code; the
+  # weekly cron keeps the full scan cadence regardless.
  push:
    branches: ["main-v2"]
+    paths-ignore:
+      - 'docs/**'
+      - 'release-notes/**'
+      - '*.md'
  pull_request:
    branches: ["main-v2"]
+    paths-ignore:
+      - 'docs/**'
+      - 'release-notes/**'
+      - '*.md'
  schedule:
    - cron: "27 3 * * 1"

@@ -1,16 +1,12 @@
-name: Prepare release notes
+name: Prepare release

 on:
  workflow_dispatch:
    inputs:
      version:
-        description: "Release version without a tag prefix (for example 1.18.0)"
+        description: "Official version without a tag prefix (for example 1.20.0)"
        required: true
        type: string
-      from_tag:
-        description: "Previous release tag (defaults to the newest catalog entry)"
-        required: false
-        type: string

 permissions:
  contents: write
@@ -29,16 +25,23 @@ jobs:
        with:
          node-version: "22"

-      - name: Prepare the release-notes branch
+      - name: Select the review branch
        env:
+          GH_TOKEN: ${{ github.token }}
          VERSION: ${{ inputs.version }}
        run: |
          set -euo pipefail
-          branch="release-notes/v${VERSION#v}"
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin main-v2
+
+          if [[ ! "$VERSION" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
+            echo "::error::version must be MAJOR.MINOR.PATCH"
+            exit 1
+          fi
+          branch="release-notes/v${VERSION}"
          if git ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
-            git fetch origin "refs/heads/$branch:refs/remotes/origin/$branch" main-v2
+            git fetch origin "refs/heads/$branch:refs/remotes/origin/$branch"
            git checkout -b "$branch" --track "origin/$branch"
            git merge --no-edit origin/main-v2
          else
@@ -52,15 +55,17 @@ jobs:
          DEEPSEEK_MODEL: deepseek-v4-pro
          GH_TOKEN: ${{ github.token }}
          VERSION: ${{ inputs.version }}
-          FROM_TAG: ${{ inputs.from_tag }}
        run: |
          set -euo pipefail
-          args=(--version "$VERSION")
-          if [ -n "$FROM_TAG" ]; then args+=(--from "$FROM_TAG"); fi
-          node scripts/generate-release-notes.mjs "${args[@]}"
+          node scripts/generate-release-notes.mjs --version "$VERSION"
          node scripts/release-notes.mjs validate
          node --test scripts/release-notes.test.mjs
          node scripts/release-notes.mjs render --version "$VERSION" --output /tmp/release-notes.md
+          {
+            echo "## Review draft for v${VERSION#v}"
+            echo
+            cat /tmp/release-notes.md
+          } >> "$GITHUB_STEP_SUMMARY"

      - name: Open or update the review PR
        env:
@@ -71,13 +76,26 @@ jobs:
          git add release-notes/releases.json
          if ! git diff --cached --quiet; then
            git commit -m "docs(release): prepare v${VERSION#v} notes" \
-              -m "Generate a bilingual, product-focused draft from merged pull request metadata. The reviewed catalog will drive the website, desktop app, and GitHub releases."
+              -m "Summary:
+          Generate a bilingual, product-focused draft from merged pull request metadata. Reuse the selected release-bound PR when one is available.
+
+          Verification:
+          Validate the catalog, citations, bilingual fields, and rendered GitHub release notes before committing."
          fi
          git push -u origin "$RELEASE_NOTES_BRANCH"
          if ! gh pr list --head "$RELEASE_NOTES_BRANCH" --state open --json number --jq 'length > 0' | grep -q true; then
-            gh pr create \
+            if ! gh pr create \
              --base main-v2 \
              --head "$RELEASE_NOTES_BRANCH" \
              --title "docs(release): 准备 v${VERSION#v} 中英更新日志" \
-              --body-file /tmp/release-notes.md
+              --body-file /tmp/release-notes.md; then
+              echo "::warning::GitHub Actions could not open the PR; the reviewed branch is preserved."
+              {
+                echo "## Manual PR handoff"
+                echo
+                echo '```sh'
+                echo "gh pr create --repo ${{ github.repository }} --base main-v2 --head $RELEASE_NOTES_BRANCH --fill"
+                echo '```'
+              } >> "$GITHUB_STEP_SUMMARY"
+            fi
          fi
@@ -1,34 +1,22 @@
 name: Release npm

 # npm line. Stable releases are called by release-stable.yml after its single
-# GitHub environment approval. Direct tag pushes are retained only for
-# prereleases so npm `next` can still ship independently without touching the
-# stable Homebrew cask. Bump a prerelease with:
-#   git tag npm-vX.Y.Z-rc.N     # prerelease -> publishes under `next`
-#   git push origin <tag>
-#
-# A manual workflow_dispatch can publish either an opt-in canary from the current
-# ref or recover an approved stable version from an existing tag. Canary publishes
-# to the `canary` dist-tag (npm i reasonix@canary) and never moves
-# `next`/`latest`. build.mjs decides the dist-tag: a `-canary.` build is `canary`,
-# any other prerelease is `next`, and a stable version is `latest` (#5822 — the
-# old "promote latest by hand" rule left it pinned at 0.53.2 and downgraded
-# `npm update -g` users). The verify step below asserts the tag actually landed.
+# GitHub environment approval. Direct prerelease tag publication is disabled;
+# manual workflow_dispatch recovers only an approved Stable version from an
+# existing tag. Historical canary and next package identities remain readable,
+# but normal publication advances only the official release.
 on:
-  push:
-    tags: ['npm-v*-*']
  workflow_dispatch:
    inputs:
      channel:
-        description: "Publish channel"
+        description: "Standalone npm recovery channel"
        required: true
-        default: canary
+        default: stable
        type: choice
        options:
-          - canary
          - stable
      base_version:
-        description: "Version to publish. Canary appends -canary.<run_number>; stable publishes exactly this version."
+        description: "Stable version to recover exactly"
        required: true
        type: string
      tag:
@@ -59,14 +47,30 @@ on:
        required: true
        type: string
      orchestrated:
-        description: "True only when called by release-stable.yml after approval"
+        description: "True only when called by an approved release orchestrator"
        required: false
        default: false
        type: boolean
+      orchestrator:
+        description: "Trusted release orchestrator (legacy Preview calls remain readable)"
+        required: false
+        default: stable
+        type: string
+      preview_number:
+        description: "Legacy Preview ordinal for old workflow-call compatibility"
+        required: false
+        default: ""
+        type: string

 permissions:
  contents: read

+concurrency:
+  # Serialize every publisher for one npm dist-tag. Historical canary calls
+  # remain ordered even though normal publication now uses Stable only.
+  group: release-npm-${{ inputs.channel || 'next' }}
+  cancel-in-progress: false
+
 jobs:
  orchestration-guard:
    name: verify approved orchestrator
@@ -82,7 +86,7 @@ jobs:
      - name: Verify caller and approved release ref
        env:
          ACTUAL_CALLER_WORKFLOW_REF: ${{ github.workflow_ref }}
-          EXPECTED_CALLER_WORKFLOW_REF: ${{ format('{0}/.github/workflows/release-stable.yml@{1}', github.repository, github.ref) }}
+          EXPECTED_CALLER_WORKFLOW_REF: ${{ format('{0}/.github/workflows/release-{1}.yml@{2}', github.repository, inputs.orchestrator, github.ref) }}
          CALLER_EVENT_NAME: ${{ github.event_name }}
          CALLER_REF: ${{ github.ref }}
          CALLER_REF_PROTECTED: ${{ github.ref_protected }}
@@ -90,7 +94,8 @@ jobs:
          CALLER_SHA: ${{ github.sha }}
          APPROVED_CLI_TAG: ${{ inputs.approved_cli_tag }}
          APPROVED_SHA: ${{ inputs.approved_sha }}
-          RELEASE_TAG: ${{ inputs.tag }}
+          APPROVED_CHANNEL: ${{ inputs.orchestrator }}
+          RELEASE_TAG: ${{ inputs.approved_cli_tag }}
          VERIFY_RELEASE_CHECKOUT: false
        run: |
          bash scripts/verify-release-authorization.sh
@@ -98,7 +103,7 @@ jobs:

  release-gate:
    name: approve standalone npm release
-    if: ${{ !inputs.orchestrated && !(github.event_name == 'workflow_dispatch' && inputs.channel == 'canary') }}
+    if: ${{ !inputs.orchestrated }}
    runs-on: ubuntu-latest
    environment: release
    steps:
@@ -109,7 +114,7 @@ jobs:
  cache-guard:
    name: cache hit guard
    needs: [orchestration-guard, release-gate]
-    if: ${{ always() && !cancelled() && ((inputs.orchestrated && needs.orchestration-guard.result == 'success') || (!inputs.orchestrated && ((github.event_name == 'workflow_dispatch' && inputs.channel == 'canary') || needs.release-gate.result == 'success'))) }}
+    if: ${{ always() && !cancelled() && ((inputs.orchestrated && needs.orchestration-guard.result == 'success') || (!inputs.orchestrated && needs.release-gate.result == 'success')) }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
@@ -126,9 +131,8 @@ jobs:
    needs: cache-guard
    if: ${{ always() && !cancelled() && needs.cache-guard.result == 'success' }}
    runs-on: ubuntu-latest
-    # The stable caller has already passed the single GitHub release approval.
-    # Direct prereleases/manual stable recovery pass release-gate above; canaries
-    # run free.
+    # Orchestrated releases have already passed their GitHub environment
+    # approval. Direct prereleases and manual Stable recovery pass release-gate.
    steps:
      - uses: actions/checkout@v7
        with:
@@ -141,9 +145,9 @@ jobs:
        with:
          node-version: '22'
          registry-url: 'https://registry.npmjs.org'
-      # Tag push uses the npm-v* tag. A canary dispatch synthesizes a
-      # <base>-canary.<run_number> version; a manual stable dispatch publishes
-      # the requested semver exactly. build.mjs strips the leading `npm-`/`v`.
+      # Stable publication uses the exact npm-v* tag. build.mjs strips the
+      # leading `npm-`/`v`; historical Preview inputs remain only for old
+      # workflow-call compatibility and are not reachable from a public entry.
      - name: Resolve version
        id: ver
        env:
@@ -154,41 +158,27 @@ jobs:
          IN_TAG: ${{ inputs.tag }}
          REF_NAME: ${{ github.ref_name }}
          RUN_NUMBER: ${{ github.run_number }}
+          IN_PREVIEW_NUMBER: ${{ inputs.preview_number }}
        run: bash scripts/resolve-npm-release.sh
      - name: Revalidate approved release ref
        if: ${{ inputs.orchestrated }}
        env:
-          RELEASE_TAG: ${{ inputs.tag }}
+          RELEASE_TAG: ${{ inputs.approved_cli_tag }}
          APPROVED_SHA: ${{ inputs.approved_sha }}
        run: bash scripts/verify-release-tag.sh
-      - env:
+      - name: Publish or recover immutable npm packages
+        env:
          VERSION_ARG: ${{ steps.ver.outputs.arg }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: node npm/build.mjs "$VERSION_ARG" --publish
-      # Assert the dist-tag landed where build.mjs aimed it. This is the guard
-      # that #5822 lacked: `latest` sat on 0.53.2 for months while stables went
-      # to `next`, and nothing noticed until users got downgraded. The registry
-      # applies tags asynchronously after publish, hence the poll.
-      - name: Verify dist-tags
+      - name: Align legacy aliases with the official release
+        if: ${{ inputs.channel == 'stable' }}
        env:
-          VERSION_ARG: ${{ steps.ver.outputs.arg }}
+          VERSION: ${{ inputs.base_version }}
+          APPROVED_SHA: ${{ inputs.approved_sha }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: |
          set -euo pipefail
-          version="$VERSION_ARG"
-          version="${version#npm-}"; version="${version#v}"
-          case "$version" in
-            *-canary.*) tag=canary ;;
-            *-*)        tag=next ;;
-            *)          tag=latest ;;
-          esac
-          for attempt in 1 2 3 4 5 6; do
-            got="$(npm view reasonix dist-tags."$tag" 2>/dev/null || true)"
-            if [ "$got" = "$version" ]; then
-              echo "dist-tag $tag -> $got"
-              exit 0
-            fi
-            echo "dist-tag $tag -> ${got:-<unset>}, want $version (attempt $attempt)"
-            sleep 10
-          done
-          echo "::error::npm dist-tag '$tag' never landed on $version"
-          exit 1
+          candidate="$APPROVED_SHA"
+          if [ -z "$candidate" ]; then candidate="$(git rev-parse HEAD)"; fi
+          EXPECTED_SHA="$candidate" node scripts/finalize-npm-official-release.mjs "$VERSION"
@@ -0,0 +1,42 @@
+name: Relay stable release
+run-name: Relay stable release ${{ github.ref_name }}
+
+# The tag event itself has a tag-shaped origin. Relay the immutable tag name to
+# release-stable.yml on protected main-v2 so the production SignPath policy can
+# allow exactly one branch name without trusting wildcard tag-like branches.
+on:
+  push:
+    tags:
+      - 'v*'
+      - '!v*-*'
+
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  relay:
+    name: dispatch protected stable control plane
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch release-stable.yml on main-v2
+        uses: actions/github-script@v9
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+          CONTROL_PLANE_REF: ${{ github.event.repository.default_branch }}
+        with:
+          script: |
+            if (process.env.CONTROL_PLANE_REF !== 'main-v2') {
+              core.setFailed(`Unexpected default branch: ${process.env.CONTROL_PLANE_REF}`);
+              return;
+            }
+            await github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'release-stable.yml',
+              ref: process.env.CONTROL_PLANE_REF,
+              inputs: {
+                tag: process.env.RELEASE_TAG,
+                allow_recovery: 'false',
+              },
+            });
@@ -2,24 +2,42 @@ name: Release stable
 run-name: Release stable ${{ inputs.tag || github.ref_name }}

 # Stable publication has exactly one GitHub environment gate. Push the CLI,
-# npm, and desktop tags atomically; the vX.Y.Z tag starts this workflow,
-# preflight verifies that all three tags point to the current main-v2 commit,
-# and one GitHub approval releases every channel. A manual recovery runs the
-# fixed control plane from protected main-v2 while preserving an older tagged
-# candidate on main-v2 history. SignPath intentionally keeps its separate
-# manual confirmations. Prerelease and canary workflows remain independently
-# callable.
+# npm, and desktop tags atomically; release-stable-trigger.yml relays the vX.Y.Z
+# tag to this workflow on protected main-v2. Preflight verifies that all three
+# tags point to the reviewed Notes candidate on main-v2 history, and one GitHub
+# approval releases every surface. After approval, a zero-publication Windows
+# preflight verifies both architectures and signing stages before publication.
+# Keeping the control-plane ref on main-v2 lets SignPath restrict
+# production signing to that one protected origin instead of trusting wildcard
+# tag-like branch names. Manual recovery uses the same fixed control plane while
+# preserving an older tagged candidate on main-v2 history.
 on:
-  push:
-    tags:
-      - 'v*'
-      - '!v*-*'
  workflow_dispatch:
    inputs:
      tag:
        description: "Existing stable CLI tag to recover (for example v1.18.0)"
        required: true
        type: string
+      publish_cli:
+        description: "Recover the CLI/Homebrew channel"
+        required: false
+        default: true
+        type: boolean
+      publish_npm:
+        description: "Recover the npm channel"
+        required: false
+        default: true
+        type: boolean
+      publish_desktop:
+        description: "Recover the Desktop/R2 channel"
+        required: false
+        default: true
+        type: boolean
+      allow_recovery:
+        description: "Allow an existing stable tag on main-v2 history (manual recovery only)"
+        required: false
+        default: true
+        type: boolean

 concurrency:
  group: stable-release-${{ inputs.tag || github.ref_name }}
@@ -36,6 +54,7 @@ jobs:
    name: validate stable release set
    runs-on: ubuntu-latest
    permissions:
+      actions: read
      contents: read
    outputs:
      version: ${{ steps.release.outputs.version }}
@@ -61,10 +80,31 @@ jobs:
        id: release
        env:
          RELEASE_TAG: ${{ inputs.tag || github.ref_name }}
-          ALLOW_STABLE_RECOVERY: ${{ github.event_name == 'workflow_dispatch' }}
+          ALLOW_STABLE_RECOVERY: ${{ inputs.allow_recovery }}
        run: bash scripts/resolve-stable-release.sh
+      - name: Revalidate normal release candidate and exact push CI
+        if: ${{ !inputs.allow_recovery }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_REPOSITORY: ${{ github.repository }}
+          RELEASE_CI_WAIT_SECONDS: 60
+          RELEASE_VERSION: ${{ steps.release.outputs.version }}
+          RELEASE_SHA: ${{ steps.release.outputs.sha }}
+        run: |
+          bash scripts/validate-stable-candidate.sh "$RELEASE_VERSION" "$RELEASE_SHA"
+          bash scripts/verify-release-push-ci.sh "$RELEASE_SHA"
      - name: Validate reviewed release notes
        run: node scripts/release-notes.mjs render --version "${{ steps.release.outputs.cli_tag }}" --output /tmp/release-notes.md
+      # Recovery builds deliberately check out the immutable tagged candidate,
+      # which can predate its reviewed release-note entry. Carry the exact file
+      # validated by this protected control-plane job into both publishers.
+      - name: Upload reviewed release notes
+        uses: actions/upload-artifact@v7
+        with:
+          name: orchestrator-reviewed-release-notes
+          path: /tmp/release-notes.md
+          if-no-files-found: error
+          retention-days: 1
      - name: Cache hit guard
        run: ./scripts/cache-guard.sh

@@ -102,7 +142,8 @@ jobs:

  cli:
    name: publish CLI and Homebrew
-    needs: authorize
+    needs: [authorize, signpath-preflight]
+    if: ${{ always() && !cancelled() && needs.authorize.result == 'success' && (needs.signpath-preflight.result == 'success' || needs.signpath-preflight.result == 'skipped') && (github.event_name != 'workflow_dispatch' || inputs.publish_cli) }}
    uses: ./.github/workflows/release.yml
    with:
      tag: ${{ needs.authorize.outputs.cli_tag }}
@@ -113,7 +154,8 @@ jobs:

  npm:
    name: publish npm
-    needs: authorize
+    needs: [authorize, signpath-preflight]
+    if: ${{ always() && !cancelled() && needs.authorize.result == 'success' && (needs.signpath-preflight.result == 'success' || needs.signpath-preflight.result == 'skipped') && (github.event_name != 'workflow_dispatch' || inputs.publish_npm) }}
    uses: ./.github/workflows/release-npm.yml
    with:
      channel: stable
@@ -124,9 +166,10 @@ jobs:
      orchestrated: true
    secrets: inherit

-  desktop:
-    name: publish desktop
+  signpath-preflight:
+    name: verify stable SignPath control plane
    needs: authorize
+    if: ${{ github.event_name != 'workflow_dispatch' || inputs.publish_desktop }}
    uses: ./.github/workflows/release-desktop.yml
    with:
      channel: stable
@@ -134,6 +177,21 @@ jobs:
      approved_cli_tag: ${{ needs.authorize.outputs.cli_tag }}
      approved_sha: ${{ needs.authorize.outputs.sha }}
      orchestrated: true
+      signing_preflight: true
+    secrets: inherit
+
+  desktop:
+    name: publish desktop
+    needs: [authorize, signpath-preflight]
+    if: ${{ always() && !cancelled() && needs.authorize.result == 'success' && needs.signpath-preflight.result == 'success' && (github.event_name != 'workflow_dispatch' || inputs.publish_desktop) }}
+    uses: ./.github/workflows/release-desktop.yml
+    with:
+      channel: stable
+      tag: ${{ needs.authorize.outputs.desktop_tag }}
+      approved_cli_tag: ${{ needs.authorize.outputs.cli_tag }}
+      approved_sha: ${{ needs.authorize.outputs.sha }}
+      orchestrated: true
+      signing_preflight_verified: true
    secrets: inherit

  postflight:
@@ -142,18 +200,30 @@ jobs:
    if: ${{ always() && !cancelled() }}
    runs-on: ubuntu-latest
    permissions:
-      contents: read
+      actions: write
+      contents: write
    steps:
      - name: Require every publisher to succeed
        env:
+          PUBLISH_CLI: ${{ github.event_name != 'workflow_dispatch' || inputs.publish_cli }}
+          PUBLISH_NPM: ${{ github.event_name != 'workflow_dispatch' || inputs.publish_npm }}
+          PUBLISH_DESKTOP: ${{ github.event_name != 'workflow_dispatch' || inputs.publish_desktop }}
          CLI_RESULT: ${{ needs.cli.result }}
          NPM_RESULT: ${{ needs.npm.result }}
          DESKTOP_RESULT: ${{ needs.desktop.result }}
        run: |
          set -euo pipefail
-          for result in "$CLI_RESULT" "$NPM_RESULT" "$DESKTOP_RESULT"; do
+          for channel in cli npm desktop; do
+            selected_var="PUBLISH_${channel^^}"
+            result_var="${channel^^}_RESULT"
+            selected="${!selected_var}"
+            result="${!result_var}"
+            if [ "$selected" != "true" ]; then
+              echo "$channel recovery skipped; public postflight will still verify it"
+              continue
+            fi
            if [ "$result" != "success" ]; then
-              echo "::error::stable publisher result is $result, expected success"
+              echo "::error::$channel stable publisher result is $result, expected success"
              exit 1
            fi
          done
@@ -173,3 +243,36 @@ jobs:
          CLI_TAG: ${{ needs.authorize.outputs.cli_tag }}
          DESKTOP_TAG: ${{ needs.authorize.outputs.desktop_tag }}
        run: bash scripts/verify-stable-release-artifacts.sh
+      - name: Publish exact Stable release record
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.authorize.outputs.version }}
+          CLI_TAG: ${{ needs.authorize.outputs.cli_tag }}
+          RELEASE_SHA: ${{ needs.authorize.outputs.sha }}
+        run: |
+          set -euo pipefail
+          if ! node -e '
+            const catalog = require("./release-notes/releases.json");
+            const release = catalog.releases.find((item) => item.version === process.env.VERSION);
+            process.exit(release?.status === "reviewed" ? 0 : 1);
+          '; then
+            echo "Legacy Stable notes do not require a publication marker"
+            exit 0
+          fi
+          node scripts/release-event.mjs generate \
+            --version "$VERSION" --sha "$RELEASE_SHA" \
+            --published-at "$(gh api "repos/${{ github.repository }}/releases/tags/$CLI_TAG" --jq .published_at)" \
+            --output /tmp/release-event.json
+          existing="$(mktemp -d)"
+          if gh release download "$CLI_TAG" --pattern release-event.json --dir "$existing" 2>/dev/null; then
+            cmp -s /tmp/release-event.json "$existing/release-event.json" || {
+              echo "::error::published release-event.json differs from the approved Stable event"
+              exit 1
+            }
+          else
+            gh release upload "$CLI_TAG" /tmp/release-event.json
+          fi
+      - name: Refresh public changelog
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run pages.yml --ref main-v2
@@ -0,0 +1,62 @@
+name: Request verification on released issues
+
+# A PR that writes "Fixes #N" auto-closes its issue on merge. One that writes
+# "Refs"/"Related"/"Addresses" does not, so the report stays open waiting for a
+# follow-up nobody remembers to send after the release. This sends it.
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to announce (e.g. desktop-v1.18.0)
+        required: true
+        type: string
+      dry_run:
+        description: Print the targets without commenting
+        required: false
+        default: true
+        type: boolean
+  release:
+    types: [published]
+  push:
+    branches:
+      - main-v2
+    paths:
+      - '.github/workflows/release-verify-issues.yml'
+      - 'scripts/release-verify-issues.mjs'
+      - 'scripts/release-verify-issues.test.mjs'
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: release-verify-issues-${{ github.event.inputs.tag || github.event.release.tag_name || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  notify:
+    if: github.repository == 'esengine/DeepSeek-Reasonix'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+      - name: Test notifier
+        run: node --test scripts/release-verify-issues.test.mjs
+      # A push that only touched the script has no release to announce; the test
+      # above is the whole point of that trigger.
+      - name: Request verification
+        if: github.event_name != 'push'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.event.inputs.tag || github.event.release.tag_name }}
+          DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }}
+        run: |
+          set -euo pipefail
+          args=(--tag "$TAG")
+          if [ "$DRY_RUN" = "true" ]; then args+=(--dry-run); fi
+          node scripts/release-verify-issues.mjs "${args[@]}"
@@ -1,21 +1,29 @@
 name: Release

-# CLI binary line. Stable releases are called by release-stable.yml after its
-# single GitHub `release`-environment approval. Direct tag pushes are retained
-# only for CLI prereleases so they can still ship independently; those runs keep
-# their own approval gate. goreleaser auto-skips the cask upload for prereleases
-# (brew has no prerelease channel — see .goreleaser.yaml).
+# Native CLI binary line. Official releases are called by the protected Stable
+# orchestrator. Manual dispatch remains available only for official recovery;
+# historical Preview inputs below are workflow-call compatibility, not a public
+# publication entrypoint.
 on:
-  push:
-    tags: ['v*-*']
  workflow_dispatch:
    inputs:
+      channel:
+        description: "Standalone CLI recovery channel"
+        required: true
+        default: stable
+        type: choice
+        options: [stable]
      tag:
-        description: "Existing CLI tag to publish (for example v1.18.0-rc.1)"
+        description: "Existing official CLI tag (for example v1.18.0)"
        required: true
        type: string
  workflow_call:
    inputs:
+      channel:
+        description: "Native CLI release channel selected by the approved orchestrator"
+        required: false
+        default: stable
+        type: string
      tag:
        description: "Existing CLI tag selected by the approved release orchestrator"
        required: true
@@ -29,7 +37,17 @@ on:
        required: true
        type: string
      orchestrated:
-        description: "True only when called by release-stable.yml after approval"
+        description: "True only when called by an approved release orchestrator"
+        required: false
+        default: false
+        type: boolean
+      orchestrator:
+        description: "Trusted release orchestrator (legacy Preview calls remain readable)"
+        required: false
+        default: stable
+        type: string
+      allow_preview_recovery:
+        description: "Legacy compatibility for already-created Preview runs"
        required: false
        default: false
        type: boolean
@@ -37,9 +55,77 @@ on:
 permissions:
  contents: write # create the release and upload archives

+concurrency:
+  # A channel pointer is a monotonic public state machine. Serialize all
+  # publishers for the same channel so an older recovery run cannot pass its
+  # read-before-write window after a newer release has published.
+  group: release-cli-${{ inputs.channel || 'stable' }}
+  cancel-in-progress: false
+
 jobs:
+  resolve:
+    name: resolve CLI release
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.release.outputs.tag }}
+      version: ${{ steps.release.outputs.version }}
+      base_version: ${{ steps.release.outputs.base_version }}
+      notes_version: ${{ steps.release.outputs.notes_version }}
+      channel: ${{ steps.release.outputs.channel }}
+      prerelease: ${{ steps.release.outputs.prerelease }}
+      sha: ${{ steps.candidate.outputs.sha }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          ref: ${{ github.sha }}
+      - name: Resolve channel and tag
+        id: release
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          IN_ORCHESTRATED: ${{ inputs.orchestrated }}
+          IN_CHANNEL: ${{ inputs.channel }}
+          IN_TAG: ${{ inputs.tag }}
+          REF_NAME: ${{ github.ref_name }}
+          CALLER_REF: ${{ github.ref }}
+          CALLER_REF_PROTECTED: ${{ github.ref_protected }}
+        run: bash scripts/resolve-cli-release.sh
+      - name: Record immutable candidate
+        id: candidate
+        env:
+          RELEASE_TAG: ${{ steps.release.outputs.tag }}
+          RELEASE_CHANNEL: ${{ steps.release.outputs.channel }}
+          IN_ORCHESTRATED: ${{ inputs.orchestrated }}
+          IN_ORCHESTRATOR: ${{ inputs.orchestrator }}
+          ALLOW_PREVIEW_RECOVERY: ${{ inputs.allow_preview_recovery }}
+        run: |
+          set -euo pipefail
+          git fetch origin main-v2
+          sha="$(git rev-parse "$RELEASE_TAG^{commit}")"
+          if ! git merge-base --is-ancestor "$sha" origin/main-v2; then
+            echo "::error::$RELEASE_TAG points to $sha, which is not on main-v2 history"
+            exit 1
+          fi
+          if [ "$ALLOW_PREVIEW_RECOVERY" = "true" ]; then
+            if [ "$IN_ORCHESTRATED" != "true" ] || [ "$IN_ORCHESTRATOR" != "preview" ] || [ "$RELEASE_CHANNEL" != "preview" ]; then
+              echo "::error::Preview recovery requires the approved Preview orchestrator"
+              exit 1
+            fi
+          elif [ "$RELEASE_CHANNEL" = "preview" ] && [ "$sha" != "$(git rev-parse origin/main-v2)" ]; then
+              echo "::error::CLI Preview must tag current main-v2; $RELEASE_TAG points to $sha"
+              exit 1
+          fi
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+      - name: Verify existing protected tag
+        env:
+          RELEASE_TAG: ${{ steps.release.outputs.tag }}
+          APPROVED_SHA: ${{ steps.candidate.outputs.sha }}
+          VERIFY_RELEASE_CHECKOUT: false
+        run: bash scripts/verify-release-tag.sh
+
  orchestration-guard:
    name: verify approved orchestrator
+    needs: resolve
    if: ${{ inputs.orchestrated }}
    runs-on: ubuntu-latest
    permissions:
@@ -52,7 +138,7 @@ jobs:
      - name: Verify caller and approved release ref
        env:
          ACTUAL_CALLER_WORKFLOW_REF: ${{ github.workflow_ref }}
-          EXPECTED_CALLER_WORKFLOW_REF: ${{ format('{0}/.github/workflows/release-stable.yml@{1}', github.repository, github.ref) }}
+          EXPECTED_CALLER_WORKFLOW_REF: ${{ format('{0}/.github/workflows/release-{1}.yml@{2}', github.repository, inputs.orchestrator, github.ref) }}
          CALLER_EVENT_NAME: ${{ github.event_name }}
          CALLER_REF: ${{ github.ref }}
          CALLER_REF_PROTECTED: ${{ github.ref_protected }}
@@ -60,6 +146,7 @@ jobs:
          CALLER_SHA: ${{ github.sha }}
          APPROVED_CLI_TAG: ${{ inputs.approved_cli_tag }}
          APPROVED_SHA: ${{ inputs.approved_sha }}
+          APPROVED_CHANNEL: ${{ inputs.orchestrator }}
          RELEASE_TAG: ${{ inputs.tag }}
          VERIFY_RELEASE_CHECKOUT: false
        run: |
@@ -68,23 +155,25 @@ jobs:

  release-gate:
    name: approve standalone CLI release
+    needs: resolve
    if: ${{ !inputs.orchestrated }}
    runs-on: ubuntu-latest
    environment: release
    steps:
      - env:
-          RELEASE_TAG: ${{ inputs.tag || github.ref_name }}
-        run: echo "Approved standalone CLI release $RELEASE_TAG"
+          RELEASE_TAG: ${{ needs.resolve.outputs.tag }}
+          RELEASE_CHANNEL: ${{ needs.resolve.outputs.channel }}
+        run: echo "Approved standalone CLI $RELEASE_CHANNEL release $RELEASE_TAG"

  cache-guard:
    name: cache hit guard
-    needs: [orchestration-guard, release-gate]
-    if: ${{ always() && !cancelled() && ((inputs.orchestrated && needs.orchestration-guard.result == 'success') || (!inputs.orchestrated && needs.release-gate.result == 'success')) }}
+    needs: [resolve, orchestration-guard, release-gate]
+    if: ${{ always() && !cancelled() && needs.resolve.result == 'success' && ((inputs.orchestrated && needs.orchestration-guard.result == 'success') || (!inputs.orchestrated && needs.release-gate.result == 'success')) }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
-          ref: ${{ inputs.approved_sha || inputs.tag || github.ref }}
+          ref: ${{ needs.resolve.outputs.sha }}
      - uses: actions/setup-go@v6
        with:
          go-version-file: go.mod
@@ -93,17 +182,39 @@ jobs:

  goreleaser:
    name: archives + checksums + homebrew tap
-    needs: cache-guard
+    needs: [resolve, cache-guard]
    if: ${{ always() && !cancelled() && needs.cache-guard.result == 'success' }}
    runs-on: ubuntu-latest
-    # The stable caller has already passed the single GitHub release approval.
-    # Standalone prereleases pass release-gate above. This job therefore must not
-    # add a second GitHub environment approval.
+    # The Stable caller has already passed the single GitHub release approval.
+    # Official standalone recovery passes release-gate above. This job therefore
+    # must not add a second GitHub environment approval.
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
-          ref: ${{ inputs.approved_sha || inputs.tag || github.ref }}
+          ref: ${{ needs.resolve.outputs.sha }}
+      # Recovery may build an immutable tag that predates the current recovery
+      # policy. Keep product sources pinned above, but execute publication
+      # decisions from the protected workflow commit.
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          path: release-control
+          ref: ${{ github.workflow_sha }}
+      - name: Isolate release-control checkout from product git state
+        run: |
+          set -euo pipefail
+          git_common_dir="$(git rev-parse --path-format=absolute --git-common-dir)"
+          exclude_file="$git_common_dir/info/exclude"
+          if ! grep -qxF '/release-control/' "$exclude_file"; then
+            printf '%s\n' '/release-control/' >> "$exclude_file"
+          fi
+          git check-ignore -q release-control/
+          dirty="$(git status --porcelain --untracked-files=all)"
+          if [ -n "$dirty" ]; then
+            printf 'product checkout is dirty before release:\n%s\n' "$dirty" >&2
+            exit 1
+          fi
      - uses: actions/setup-go@v6
        with:
          go-version-file: go.mod
@@ -111,38 +222,237 @@ jobs:
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
+      - name: Download orchestrator-reviewed release notes
+        if: ${{ inputs.orchestrated }}
+        uses: actions/download-artifact@v8
+        with:
+          name: orchestrator-reviewed-release-notes
+          path: /tmp/orchestrator-reviewed-release-notes
+      - name: Use orchestrator-reviewed release notes
+        if: ${{ inputs.orchestrated }}
+        run: |
+          test -s /tmp/orchestrator-reviewed-release-notes/release-notes.md
+          cp /tmp/orchestrator-reviewed-release-notes/release-notes.md /tmp/release-notes.md
      - name: Render reviewed release notes
+        if: ${{ !inputs.orchestrated }}
        env:
-          RELEASE_TAG: ${{ inputs.tag || github.ref_name }}
+          RELEASE_TAG: ${{ needs.resolve.outputs.notes_version }}
        run: node scripts/release-notes.mjs render --version "$RELEASE_TAG" --output /tmp/release-notes.md
      - name: Revalidate approved release ref
-        if: ${{ inputs.orchestrated }}
        env:
-          RELEASE_TAG: ${{ inputs.tag }}
-          APPROVED_SHA: ${{ inputs.approved_sha }}
+          RELEASE_TAG: ${{ needs.resolve.outputs.tag }}
+          APPROVED_SHA: ${{ needs.resolve.outputs.sha }}
        run: bash scripts/verify-release-tag.sh
+      - name: Decide whether CLI artifacts need publication
+        id: publication
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.resolve.outputs.tag }}
+          CHANNEL: ${{ needs.resolve.outputs.channel }}
+          PRERELEASE: ${{ needs.resolve.outputs.prerelease }}
+        run: |
+          set -euo pipefail
+          validation_channel="$CHANNEL"
+          if [ "$CHANNEL" = "stable" ] && [ "$PRERELEASE" = "true" ]; then
+            validation_channel=any
+          fi
+          release_json=/tmp/existing-cli-release.json
+          release_error=/tmp/existing-cli-release.error
+          checksums=/tmp/existing-cli-release-SHA256SUMS
+          if gh api "repos/${{ github.repository }}/releases/tags/$TAG" \
+            >"$release_json" 2>"$release_error"; then
+            gh release download "$TAG" -R "${{ github.repository }}" \
+              --pattern SHA256SUMS --output "$checksums"
+            decision="$(
+              bash release-control/scripts/decide-cli-release-publication.sh \
+                "$validation_channel" "$TAG" "${{ github.repository }}" \
+                "$release_json" "$checksums"
+            )"
+            echo "existing CLI release $TAG is complete and checksum-bound; reusing it"
+          elif grep -Eiq 'HTTP 404|Not Found' "$release_error"; then
+            decision="$(
+              bash release-control/scripts/decide-cli-release-publication.sh \
+                "$validation_channel" "$TAG" "${{ github.repository }}" - -
+            )"
+            echo "CLI release $TAG does not exist; GoReleaser will publish it"
+          else
+            cat "$release_error" >&2
+            exit 1
+          fi
+          test "$decision" = "publish" -o "$decision" = "reuse"
+          echo "decision=$decision" >> "$GITHUB_OUTPUT"
      - uses: goreleaser/goreleaser-action@v7
+        if: ${{ steps.publication.outputs.decision == 'publish' }}
        with:
          version: '~> v2'
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          HOMEBREW_TAP_TOKEN: ${{ needs.resolve.outputs.channel == 'stable' && secrets.HOMEBREW_TAP_TOKEN || '' }}
          # workflow_dispatch recovery runs have a branch-shaped GITHUB_REF even
          # though checkout is on the release tag. Pin GoReleaser explicitly, and
          # avoid ambiguity from the three release tags sharing one commit.
-          GORELEASER_CURRENT_TAG: ${{ inputs.tag || github.ref_name }}
+          GORELEASER_CURRENT_TAG: ${{ needs.resolve.outputs.tag }}

      - name: Publish product release notes
        env:
          GH_TOKEN: ${{ github.token }}
-          TAG: ${{ inputs.tag || github.ref_name }}
+          TAG: ${{ needs.resolve.outputs.tag }}
        run: gh release edit "$TAG" --notes-file /tmp/release-notes.md

+      - name: Publish CLI release metadata to R2
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.resolve.outputs.tag }}
+          NOTES_TAG: ${{ needs.resolve.outputs.notes_version }}
+          HAS_R2: ${{ secrets.R2_ACCESS_KEY_ID != '' && secrets.R2_SECRET_ACCESS_KEY != '' && secrets.R2_ACCOUNT_ID != '' && secrets.R2_BUCKET != '' }}
+          AWS_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+          AWS_DEFAULT_REGION: auto
+          R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET }}
+        run: |
+          set -euo pipefail
+          if [ "$HAS_R2" != "true" ]; then
+            echo "R2 secrets not configured; skipping CLI release metadata"
+            exit 0
+          fi
+
+          channel=""
+          if [[ "$TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
+            channel="stable"
+          elif [[ "$TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)-preview\.(0|[1-9][0-9]*)$ ]]; then
+            channel="preview"
+          else
+            echo "internal CLI release $TAG; publishing only immutable metadata"
+          fi
+
+          required_assets='[
+            "reasonix-darwin-amd64.tar.gz",
+            "reasonix-darwin-arm64.tar.gz",
+            "reasonix-linux-amd64.tar.gz",
+            "reasonix-linux-arm64.tar.gz",
+            "reasonix-windows-amd64.zip",
+            "reasonix-windows-arm64.zip",
+            "SHA256SUMS"
+          ]'
+          gh api "repos/${{ github.repository }}/releases/tags/$TAG" > /tmp/cli-release.raw.json
+          jq --arg tag "$TAG" --arg notes_tag "$NOTES_TAG" --argjson required "$required_assets" '
+            if .tag_name != $tag then error("release tag mismatch") else . end |
+            if .draft then error("draft release cannot be published") else . end |
+            . as $release |
+            ($release.assets | map({key: .name, value: .}) | from_entries) as $assets |
+            if ($required | all(. as $name | $assets[$name] != null))
+            then {
+              tag_name: $release.tag_name,
+              prerelease: $release.prerelease,
+              html_url: $release.html_url,
+              release_notes_url: ("https://reasonix.io/changelog/" + $notes_tag + "/"),
+              assets: [
+                $required[] as $name |
+                $assets[$name] |
+                {
+                  name: .name,
+                  browser_download_url: .browser_download_url,
+                  size: .size
+                }
+              ]
+            }
+            else error("release is missing one or more required CLI assets")
+            end
+          ' /tmp/cli-release.raw.json > /tmp/cli-release.json
+          if [ -n "$channel" ]; then
+            bash scripts/validate-cli-release-manifest.sh \
+              "$channel" "$TAG" "${{ github.repository }}" /tmp/cli-release.json "$NOTES_TAG"
+          else
+            bash scripts/validate-cli-release-manifest.sh \
+              any "$TAG" "${{ github.repository }}" /tmp/cli-release.json "$NOTES_TAG"
+          fi
+
+          endpoint="https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com"
+          validation_channel="${channel:-any}"
+          immutable_key="cli/releases/${TAG}/latest.json"
+          immutable_error="$(mktemp)"
+          if aws s3 cp "s3://${R2_BUCKET}/${immutable_key}" /tmp/cli-release.immutable.json \
+            --endpoint-url "$endpoint" 2>"$immutable_error"; then
+            bash scripts/validate-cli-release-manifest.sh \
+              "legacy-${validation_channel}" "$TAG" "${{ github.repository }}" \
+              /tmp/cli-release.immutable.json "$NOTES_TAG"
+            if ! bash scripts/compare-cli-release-manifests.sh \
+              /tmp/cli-release.json /tmp/cli-release.immutable.json; then
+              echo "::error::immutable CLI release metadata for $TAG already exists with different content"
+              exit 1
+            fi
+            echo "immutable CLI release metadata for $TAG already exists; preserving it"
+          elif grep -Eiq '404|NoSuchKey|Not Found' "$immutable_error"; then
+            aws s3 cp /tmp/cli-release.json "s3://${R2_BUCKET}/${immutable_key}" \
+              --endpoint-url "$endpoint" \
+              --content-type "application/json; charset=utf-8" \
+              --cache-control "public, max-age=31536000, immutable"
+          else
+            cat "$immutable_error" >&2
+            exit 1
+          fi
+          rm -f "$immutable_error"
+
+          aws s3 cp "s3://${R2_BUCKET}/${immutable_key}" /tmp/cli-release.immutable.json \
+            --endpoint-url "$endpoint"
+          bash scripts/validate-cli-release-manifest.sh \
+            "legacy-${validation_channel}" "$TAG" "${{ github.repository }}" \
+            /tmp/cli-release.immutable.json "$NOTES_TAG"
+          bash scripts/compare-cli-release-manifests.sh \
+            /tmp/cli-release.json /tmp/cli-release.immutable.json
+
+          if [ -z "$channel" ]; then
+            echo "internal CLI release $TAG; Stable and Preview pointers remain unchanged"
+            exit 0
+          fi
+
+          current_tag=""
+          pointer_error="$(mktemp)"
+          if aws s3 cp "s3://${R2_BUCKET}/cli/${channel}/latest.json" /tmp/cli-release.pointer.json \
+            --endpoint-url "$endpoint" 2>"$pointer_error"; then
+            current_tag="$(jq -er '.tag_name | strings' /tmp/cli-release.pointer.json)"
+            bash scripts/validate-cli-release-manifest.sh \
+              "legacy-${channel}" "$current_tag" "${{ github.repository }}" \
+              /tmp/cli-release.pointer.json "$current_tag"
+          elif grep -Eiq '404|NoSuchKey|Not Found' "$pointer_error"; then
+            echo "CLI $channel pointer does not exist yet"
+          else
+            cat "$pointer_error" >&2
+            exit 1
+          fi
+          rm -f "$pointer_error"
+
+          pointer_manifest=-
+          if [ -n "$current_tag" ]; then
+            pointer_manifest=/tmp/cli-release.pointer.json
+          fi
+          pointer_decision="$(
+            bash scripts/decide-cli-pointer-update.sh \
+              "$channel" /tmp/cli-release.json "$pointer_manifest"
+          )"
+          if [ "$pointer_decision" = "skip" ]; then
+            echo "CLI $channel pointer remains ${current_tag:-unset}; candidate $TAG is not newer and needs no repair"
+            exit 0
+          fi
+          aws s3 cp /tmp/cli-release.json "s3://${R2_BUCKET}/cli/${channel}/latest.json" \
+            --endpoint-url "$endpoint" \
+            --content-type "application/json; charset=utf-8" \
+            --cache-control "public, max-age=300, stale-if-error=86400"
+
+          aws s3 cp "s3://${R2_BUCKET}/cli/${channel}/latest.json" /tmp/cli-release.pointer.json \
+            --endpoint-url "$endpoint"
+          bash scripts/validate-cli-release-manifest.sh \
+            "$channel" "$TAG" "${{ github.repository }}" \
+            /tmp/cli-release.pointer.json "$NOTES_TAG"
+          cmp -s /tmp/cli-release.json /tmp/cli-release.pointer.json
+          echo "CLI $channel pointer -> $TAG"
+
      - name: Attach desktop manifest compatibility asset
        env:
          GH_TOKEN: ${{ github.token }}
-          TAG: ${{ inputs.tag || github.ref_name }}
+          TAG: ${{ needs.resolve.outputs.tag }}
          HAS_R2: ${{ secrets.R2_ACCESS_KEY_ID != '' && secrets.R2_SECRET_ACCESS_KEY != '' && secrets.R2_ACCOUNT_ID != '' && secrets.R2_BUCKET != '' }}
          R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
          R2_BUCKET: ${{ secrets.R2_BUCKET }}
@@ -184,7 +494,7 @@ jobs:
      # cover the release CDN propagating the freshly uploaded asset.
      - name: Smoke public compatibility manifest
        env:
-          TAG: ${{ inputs.tag || github.ref_name }}
+          TAG: ${{ needs.resolve.outputs.tag }}
          HAS_R2: ${{ secrets.R2_ACCESS_KEY_ID != '' && secrets.R2_SECRET_ACCESS_KEY != '' && secrets.R2_ACCOUNT_ID != '' && secrets.R2_BUCKET != '' }}
        run: |
          set -euo pipefail
@@ -231,7 +541,7 @@ jobs:
      #     owns asserting the dist-tag lands.
      - name: Check npm latest dist-tag freshness
        env:
-          TAG: ${{ inputs.tag || github.ref_name }}
+          TAG: ${{ needs.resolve.outputs.tag }}
        run: |
          set -euo pipefail
          case "$TAG" in
@@ -0,0 +1,68 @@
+name: Sweep stale version reports
+
+# Reports filed many minors back cannot be confirmed against a current build,
+# and 65% of the open tracker has never had a reply. This asks, waits, then
+# closes — never closing anything that was not asked first.
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Print what would happen without commenting
+        required: false
+        default: true
+        type: boolean
+      limit:
+        description: Maximum issues to touch in this run
+        required: false
+        default: '40'
+        type: string
+  schedule:
+    - cron: '17 3 * * 1'
+  push:
+    branches:
+      - main-v2
+    paths:
+      - '.github/workflows/stale-report-sweep.yml'
+      - 'scripts/stale-report-sweep.mjs'
+      - 'scripts/stale-report-sweep.test.mjs'
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: stale-report-sweep
+  cancel-in-progress: false
+
+jobs:
+  sweep:
+    if: github.repository == 'esengine/DeepSeek-Reasonix'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+      - name: Test sweeper
+        run: node --test scripts/stale-report-sweep.test.mjs
+      # A push that only touched the sweeper runs its tests and stops there.
+      - name: Sweep
+        if: github.event_name != 'push'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          LIMIT: ${{ github.event.inputs.limit || '40' }}
+          # Posting stays off until this repository variable is set to "true", so
+          # merging the sweeper cannot start commenting on its own.
+          ENABLED: ${{ vars.STALE_SWEEP_ENABLED }}
+          REQUESTED_DRY_RUN: ${{ github.event.inputs.dry_run || 'true' }}
+        run: |
+          set -euo pipefail
+          args=(--limit "$LIMIT")
+          if [ "$ENABLED" != "true" ] || [ "$REQUESTED_DRY_RUN" = "true" ]; then
+            args+=(--dry-run)
+            echo "::notice::dry run (STALE_SWEEP_ENABLED=${ENABLED:-unset})"
+          fi
+          node scripts/stale-report-sweep.mjs "${args[@]}"
@@ -71,3 +71,5 @@ temp/
 # Official theme art intermediate outputs / caches
 scripts/official-theme-art/out/
 scripts/official-theme-art/__pycache__/
+agent-complexity-report.txt
+site/.generated/
@@ -0,0 +1,40 @@
+# Report-only complexity monitor for internal/agent production code.
+# Uses funlen + cyclop with generous thresholds so existing code does not
+# generate a flood of noise. issues-exit-code is forced to 0 by the CI step so
+# this never blocks merges while we establish a baseline and track trend.
+version: "2"
+
+run:
+  tests: false
+
+linters:
+  default: none
+  enable:
+    - funlen
+    - cyclop
+  settings:
+    funlen:
+      # Deliberately above a hard 50-line rule: length alone is not the
+      # acceptance gate. This surfaces only the remaining large hotspots after
+      # the Run/executeOne extraction so trend can be tracked.
+      lines: 120
+      statements: 80
+      ignore-comments: true
+    cyclop:
+      max-complexity: 30
+      package-average: 0
+      skip-tests: true
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
+  # Report mode: never fail the job. Baseline/trend is the gate, not a hard cut.
+  # The CI step also passes --issues-exit-code=0 for older golangci-lint builds.
+  uniq-by-line: false
+
+output:
+  formats:
+    text:
+      path: stdout
+      print-linter-name: true
+      print-issued-lines: true
@@ -34,8 +34,9 @@ checksum:
 homebrew_casks:
  - name: reasonix
    ids: [reasonix]
-    # Prereleases (v*-rc*) must not update the stable tap; brew has no separate
-    # prerelease channel, so a pushed rc cask becomes the default `brew install`.
+    # Prereleases (including v*-preview.* and v*-rc*) must not update the stable
+    # tap; brew has no separate prerelease channel, so uploading either cask
+    # would make it the default `brew install`.
    # npm is a separate line (release-npm.yml, `npm-v*`), so an npm prerelease no
    # longer drags brew along — a stable `v*` cask can ship while npm stays on rc.
    skip_upload: "auto"
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Canary-only configuration. SignPath test certificates intentionally do not
+     chain to a Windows trusted root, so authenticode-verify cannot be used for
+     the already test-signed payload. The workflow verifies that every payload
+     executable is signed and hash-identical to the rebuilt portable package.
+     Stable and RC releases use windows-installer-v2 instead. -->
+<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
+  <zip-file>
+    <pe-file path="*installer*.exe">
+      <authenticode-sign />
+    </pe-file>
+  </zip-file>
+</artifact-configuration>
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Sign the finished NSIS container only when the exact payload used to build it
+     is present and already Authenticode-signed. GitHub Actions wraps this flat
+     bundle in a zip before SignPath receives it. Keep this versioned separately
+     so provisioning it cannot break releases still using windows-installer. -->
+<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
+  <zip-file>
+    <pe-file path="*installer*.exe">
+      <authenticode-sign />
+    </pe-file>
+    <pe-file path="reasonix-desktop.exe">
+      <authenticode-verify />
+    </pe-file>
+    <pe-file path="reasonix-guard.exe">
+      <authenticode-verify />
+    </pe-file>
+    <pe-file path="reasonix-launcher.exe">
+      <authenticode-verify />
+    </pe-file>
+    <pe-file path="reasonix-update-helper.exe">
+      <authenticode-verify />
+    </pe-file>
+    <pe-file path="reasonix-cli.exe">
+      <authenticode-verify />
+    </pe-file>
+    <pe-file path="reasonix-uninstall.exe">
+      <authenticode-verify />
+    </pe-file>
+  </zip-file>
+</artifact-configuration>
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Sign every executable that the NSIS installer writes to disk. GitHub Actions
+     wraps the flat payload directory in this zip before SignPath receives it. -->
+<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
+  <zip-file>
+    <pe-file path="reasonix-desktop.exe">
+      <authenticode-sign />
+    </pe-file>
+    <pe-file path="reasonix-guard.exe">
+      <authenticode-sign />
+    </pe-file>
+    <pe-file path="reasonix-launcher.exe">
+      <authenticode-sign />
+    </pe-file>
+    <pe-file path="reasonix-update-helper.exe">
+      <authenticode-sign />
+    </pe-file>
+    <pe-file path="reasonix-cli.exe">
+      <authenticode-sign />
+    </pe-file>
+    <pe-file path="reasonix-uninstall.exe">
+      <authenticode-sign />
+    </pe-file>
+  </zip-file>
+</artifact-configuration>
@@ -0,0 +1,19 @@
+version: 1
+project_slug: DeepSeek-Reasonix
+signing_policy_slug: release-signing
+repository_url: https://github.com/esengine/DeepSeek-Reasonix.git
+allowed_branch_names:
+  - main-v2
+allowed_build_definitions:
+  - .github/workflows/release-stable.yml
+  - .github/workflows/release-desktop.yml
+fingerprint_files:
+  - .github/workflows/release-stable.yml
+  - .github/workflows/release-stable-trigger.yml
+  - .github/workflows/release-desktop.yml
+  - .signpath/artifact-configurations/windows-payload.xml
+  - .signpath/artifact-configurations/windows-installer-v2.xml
+  - scripts/complete-signpath-request.ps1
+  - scripts/package-windows-desktop.sh
+  - scripts/verify-windows-authenticode.ps1
+  - cmd/signpath-contract/main.go
@@ -69,6 +69,33 @@ branch.

 ### Fixed

+- Fixed Remote Workbench failing with only `initialize: workbench-desktop:
+  connection closed` on fresh or cross-platform SSH hosts. Desktop now proves
+  the exact Host CLI Build ID, provisions the matching verified release without
+  requiring remote npm, runs the managed binary explicitly, and preserves a
+  safe structured bootstrap error when the remote command exits early.
+- Hardened Bash permission reuse for dynamic and indirect execution. Parameter/arithmetic expansions,
+  assignments, redirects, heredocs, and globs can only be remembered as exact
+  `Bash=<literal>` rules, while still using Auto's normal fallback. Nested or
+  indirect execution now requires a human in interactive Ask/Auto and fails
+  closed in headless Ask/Auto/DontAsk. Broad Bash rules, Guardian/hook allows,
+  and the approved-plan window can no longer silently authorize that stricter
+  class; YOLO remains the explicit full-access bypass and sandbox enforcement
+  is unchanged.
+- Fixed Desktop sessions incorrectly locking themselves during Goal + Delivery
+  mode changes, controller rebuilds, duplicate-tab restore, and background
+  reattachment. Desktop now keeps one process-local runtime owner per canonical
+  session, fences stale controller events by runtime epoch, blocks sends until
+  that runtime is ready, and scopes single-instance ownership to
+  `REASONIX_HOME` instead of the executable path. Switching saved sessions is
+  now transactional: a target build, restore, or lease failure leaves the
+  current controller, lease, path, mode profile, and runtime epoch untouched.
+- Stabilized the desktop rich composer caret after skill and plugin invocation
+  tags. DOM→model and model→DOM selection mapping now treat invocation chips as
+  zero-length atoms while still counting user text that lands inside the NBSP
+  caret anchor (common on Windows WebView2), restore both selection ends, and
+  recover the insertion point from a `beforeinput` snapshot when the browser
+  temporarily loses selection — so mid-text edits no longer jump to the end.
 - Isolated the Windows desktop WebView2 shell from stale system proxies, so an
  exited proxy client cannot leave the embedded UI hidden during startup. If
  WebView2 still does not reach DOM-ready within 15 seconds, Reasonix now shows
@@ -139,8 +139,9 @@ For advanced CLI usage and configuration, see the **[CLI reference](./docs/CLI.m
 - **Getting started:** [Guide](./docs/GUIDE.md) · [CLI reference](./docs/CLI.md) ·
  [Configuration paths](./docs/CONFIG_PATHS.md) · [ACP editor integration](./docs/ACP.md)
 - **Features & troubleshooting:** [Subagent profiles](./docs/SUBAGENT_PROFILES.md) ·
+  [Context Engine v2](./docs/SESSION_MEMORY_RETRIEVAL.md) ·
  [Capability diagnostics](./docs/CAPABILITY_DIAGNOSTICS.md) ·
-  [Recovery and Safe Mode](./docs/RECOVERY.md) · [Bot guide](./docs/BOT_GUIDE.md) ·
+  [Recovery and updates](./docs/RECOVERY.md) · [Bot guide](./docs/BOT_GUIDE.md) ·
  [Checkpoints & rewind](./docs/CHECKPOINTS.md)
 - **Engineering & migration:** [Spec](./docs/SPEC.md) ·
  [Task contracts & pause policy](./docs/TASK_CONTRACT.md) ·
@@ -131,6 +131,7 @@ CLI 进阶用法和详细配置见 **[CLI 命令参考](./docs/CLI.zh-CN.md)**
  [CLI 命令参考](./docs/CLI.zh-CN.md) · [配置路径](./docs/CONFIG_PATHS.zh-CN.md) ·
  [ACP 编辑器接入](./docs/ACP.zh-CN.md)
 - **功能与排障：** [子智能体 Profile](./docs/SUBAGENT_PROFILES.zh-CN.md) ·
+  [Context Engine v2](./docs/SESSION_MEMORY_RETRIEVAL.zh-CN.md) ·
  [能力诊断](./docs/CAPABILITY_DIAGNOSTICS.zh-CN.md) ·
  [恢复与安全模式](./docs/RECOVERY.zh-CN.md) ·
  [机器人使用指南](./docs/BOT_GUIDE.zh-CN.md) ·
@@ -17,13 +17,19 @@ agent. It is the Reasonix analog of Claude Code's CLAUDE.md.

 ## Memory

- Hierarchical docs: `REASONIX.md` (this file, committed/shared), `REASONIX.local.md`
-  (personal, git-ignored), user-global `~/.config/reasonix/REASONIX.md`, and any
-  `REASONIX.md` in an ancestor dir. `AGENTS.md` is accepted as a fallback name.
+- Standing instructions are hierarchical: committed/shared `REASONIX.md`,
+  `AGENTS.md`, and `CLAUDE.md`; personal `*.local.md` variants; matching files in
+  ancestor directories; and user-global files under the memory state root
+  (`REASONIX_STATE_HOME`, otherwise `REASONIX_HOME`, otherwise `~/.reasonix` on
+  macOS/Linux or `%APPDATA%\reasonix` on Windows). All distinct supported files
+  in a directory load; `AGENTS.md` is not merely a fallback.
 - `@path` on its own line imports another file's contents.
- `#<note>` in chat quick-adds a line here. The `remember` tool saves durable
-  facts to the per-project auto-memory store (frontmatter files + `MEMORY.md`
-  index), which loads into the prefix on the next session.
+- `#<note>` in chat quick-adds an always-on instruction. The `remember` tool
+  instead saves a fallible background fact (frontmatter file + `MEMORY.md`
+  index). Fact `type` classifies content; independent `scope` controls whether it
+  is project-only (the default) or explicitly global. The index loads into the
+  stable prefix on the next session; global user/feedback bodies also load as
+  lower-priority compatibility guidance. The current turn receives a tail note.

 ## Notes

@@ -1,358 +0,0 @@
-package main
-
-import (
-	"bufio"
-	"context"
-	"encoding/json"
-	"flag"
-	"fmt"
-	"os"
-	"strings"
-	"time"
-
-	"reasonix/internal/config"
-	"reasonix/internal/provider"
-	_ "reasonix/internal/provider/anthropic"
-	_ "reasonix/internal/provider/openai"
-	"reasonix/internal/repair"
-)
-
-func runAssist(args []string) int {
-	fs := flag.NewFlagSet("reasonix-guard assist", flag.ContinueOnError)
-	root := fs.String("root", ".", "project root to diagnose")
-	model := fs.String("model", "", "provider or provider/model used for the one-shot plan")
-	network := fs.Bool("network", true, "include provider connectivity diagnostics")
-	apply := fs.Bool("apply", false, "apply the validated plan after preview and confirmation")
-	yes := fs.Bool("yes", false, "confirm plan application non-interactively")
-	allowProject := fs.Bool("allow-project", false, "allow a plan to quarantine project reasonix.toml")
-	jsonOut := fs.Bool("json", false, "print the plan and preview as JSON")
-	if err := fs.Parse(args); err != nil || fs.NArg() != 0 {
-		return 2
-	}
-	ctx, cancel := context.WithTimeout(context.Background(), 90*time.Second)
-	defer cancel()
-	report, err := repair.Diagnose(ctx, repair.DiagnoseOptions{Root: *root, Network: *network})
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	plan, err := requestRepairPlan(ctx, *root, *model, report)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	opts := repair.ApplyPlanOptions{Root: *root, AllowProject: *allowProject}
-	preview, err := repair.PreviewRepairPlan(plan, opts)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	if *jsonOut {
-		if code := printJSON(struct {
-			Plan    repair.RepairPlan          `json:"plan"`
-			Preview []repair.RepairPlanPreview `json:"preview"`
-		}{plan, preview}); code != 0 {
-			return code
-		}
-	} else {
-		printPlanPreview(plan, preview)
-	}
-	if !*apply {
-		return 0
-	}
-	if !*yes && !confirmPlan() {
-		fmt.Println("repair plan not applied")
-		return 0
-	}
-	result, err := repair.ApplyRepairPlan(plan, opts)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	if *jsonOut {
-		return printJSON(result)
-	}
-	for _, action := range result.Applied {
-		fmt.Println("applied:", action)
-	}
-	return 0
-}
-
-func runApplyPlan(args []string) int {
-	fs := flag.NewFlagSet("reasonix-guard apply-plan", flag.ContinueOnError)
-	root := fs.String("root", ".", "project root")
-	file := fs.String("file", "", "RepairPlan JSON file")
-	yes := fs.Bool("yes", false, "confirm plan application non-interactively")
-	allowProject := fs.Bool("allow-project", false, "allow project reasonix.toml repair")
-	jsonOut := fs.Bool("json", false, "print JSON")
-	if err := fs.Parse(args); err != nil || fs.NArg() != 0 || strings.TrimSpace(*file) == "" {
-		return 2
-	}
-	b, err := os.ReadFile(*file)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	plan, err := repair.DecodeRepairPlan(b)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	opts := repair.ApplyPlanOptions{Root: *root, AllowProject: *allowProject}
-	preview, err := repair.PreviewRepairPlan(plan, opts)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	if !*jsonOut {
-		printPlanPreview(plan, preview)
-	}
-	if !*yes && !confirmPlan() {
-		fmt.Println("repair plan not applied")
-		return 0
-	}
-	result, err := repair.ApplyRepairPlan(plan, opts)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	if *jsonOut {
-		return printJSON(result)
-	}
-	for _, action := range result.Applied {
-		fmt.Println("applied:", action)
-	}
-	return 0
-}
-
-func requestRepairPlan(ctx context.Context, root, modelRef string, report repair.DiagnosticReport) (repair.RepairPlan, error) {
-	cfg, err := loadAIProviderConfig(root)
-	if err != nil {
-		return repair.RepairPlan{}, err
-	}
-	if strings.TrimSpace(modelRef) == "" {
-		modelRef = cfg.DefaultModel
-	}
-	entry, ok := cfg.ResolveModel(modelRef)
-	if !ok {
-		return repair.RepairPlan{}, fmt.Errorf("AI assistance model %q is not configured", modelRef)
-	}
-	if entry.RequiresAPIKey() && entry.APIKey() == "" {
-		return repair.RepairPlan{}, fmt.Errorf("AI assistance provider %q has no configured API key", entry.Name)
-	}
-	p, err := provider.New(entry.Kind, provider.Config{
-		Name: entry.Name, BaseURL: entry.BaseURL, Model: entry.Model, APIKey: entry.APIKey(),
-		Extra: map[string]any{
-			"api_key_env": entry.APIKeyEnv, "api_key_source": entry.APIKeySourceLabel(),
-			"thinking": entry.Thinking, "effort": entry.Effort, "reasoning_protocol": entry.ReasoningProtocol,
-			"chat_url": entry.ChatURL, "headers": entry.Headers, "extra_body": entry.ExtraBody,
-			"auth_header": entry.AuthHeader, "proxy_spec": cfg.NetworkProxySpec(),
-		},
-	})
-	if err != nil {
-		return repair.RepairPlan{}, err
-	}
-	safeReport, snapshotAliases := providerSafeReportFrom(report)
-	payload, err := json.Marshal(safeReport)
-	if err != nil {
-		return repair.RepairPlan{}, err
-	}
-	stream, err := p.Stream(ctx, provider.Request{
-		Messages: []provider.Message{
-			{Role: provider.RoleSystem, Content: repairPlanSystemPrompt},
-			{Role: provider.RoleUser, Content: string(payload)},
-		},
-		Temperature: provider.TemperaturePtr(0),
-		MaxTokens:   2000,
-	})
-	if err != nil {
-		return repair.RepairPlan{}, err
-	}
-	var out strings.Builder
-	for chunk := range stream {
-		switch chunk.Type {
-		case provider.ChunkText:
-			out.WriteString(chunk.Text)
-		case provider.ChunkError:
-			if chunk.Err != nil {
-				return repair.RepairPlan{}, chunk.Err
-			}
-		}
-	}
-	plan, err := repair.DecodeRepairPlan([]byte(out.String()))
-	if err != nil {
-		return repair.RepairPlan{}, err
-	}
-	return resolveProviderSnapshotAliases(plan, snapshotAliases)
-}
-
-func loadAIProviderConfig(root string) (*config.Config, error) {
-	// Recovery tooling must never rewrite user configuration, so skip the
-	// on-disk legacy MCP tier migration that LoadForRoot performs.
-	if cfg, err := config.LoadForRootReadOnly(root); err == nil {
-		return cfg, nil
-	}
-	if snapshots, err := repair.ListConfigSnapshots(); err == nil {
-		for _, snapshot := range snapshots {
-			cfg, loadErr := config.LoadForEditReadOnlyStrict(snapshot.Path)
-			if loadErr == nil {
-				return cfg, nil
-			}
-		}
-	}
-	// Built-in recovery defaults resolve the global credential file without
-	// reading, migrating, or rewriting malformed user/project TOML.
-	return config.LoadRecoveryDefaultsForRoot(root), nil
-}
-
-const repairPlanSystemPrompt = `You are a Reasonix recovery planner. Return JSON only, matching exactly:
-{"schemaVersion":1,"summary":"...","actions":[{"type":"...","scope":"","snapshotId":"","target":"","reason":"..."}]}
-The user message is a diagnostic report whose findings carry only a severity, a machine code (e.g. config.invalid_toml, derived.invalid_json, update related codes), and a generic scope; pick actions from those codes.
-Snapshot IDs are host-issued aliases ordered newest first; pendingUpdate=true means rollback_update is available.
-Allowed actions only (return an empty actions array when no safe action applies):
- repair_config with scope global or project
- restore_snapshot with snapshotId
- rebuild_derived_state with target tabs, projects, window, zoom, or all
- rollback_update with no parameters
-Never request shell commands, credential changes, session-content edits, arbitrary paths, plugin execution, or source-code changes. Prefer the smallest reversible plan supported by the diagnostics. Do not invent snapshot IDs.`
-
-// providerSafeReport is the strict allowlist DTO sent to the AI provider.
-// It deliberately carries no free-form diagnostic strings or state metadata:
-// finding messages can quote config lines, URLs, commands, and permission
-// rules, while snapshot and update metadata can be edited on disk. Only fixed
-// diagnostic vocabulary, booleans, and host-issued snapshot aliases leave the
-// machine.
-type providerSafeReport struct {
-	Root          string                 `json:"root"`
-	Network       bool                   `json:"network"`
-	Snapshots     []providerSafeSnapshot `json:"snapshots"`
-	PendingUpdate bool                   `json:"pendingUpdate"`
-	Findings      []providerSafeFinding  `json:"findings"`
-}
-
-type providerSafeSnapshot struct {
-	ID string `json:"id"`
-}
-
-type providerSafeFinding struct {
-	Severity string `json:"severity"`
-	Code     string `json:"code"`
-	Scope    string `json:"scope,omitempty"`
-}
-
-func providerSafeReportFrom(report repair.DiagnosticReport) (providerSafeReport, map[string]string) {
-	safe := providerSafeReport{
-		Root:          "<project>",
-		Network:       report.Network,
-		Snapshots:     make([]providerSafeSnapshot, 0, len(report.Snapshots)),
-		PendingUpdate: report.PendingUpdate != nil,
-		Findings:      make([]providerSafeFinding, 0, len(report.Findings)),
-	}
-	snapshotAliases := make(map[string]string, len(report.Snapshots))
-	for _, snapshot := range report.Snapshots {
-		if strings.TrimSpace(snapshot.ID) != "" {
-			alias := fmt.Sprintf("snapshot-%d", len(safe.Snapshots)+1)
-			safe.Snapshots = append(safe.Snapshots, providerSafeSnapshot{ID: alias})
-			snapshotAliases[alias] = snapshot.ID
-		}
-	}
-	for _, finding := range report.Findings {
-		safe.Findings = append(safe.Findings, providerSafeFinding{
-			Severity: providerSafeSeverity(finding.Severity),
-			Code:     providerSafeDiagnosticCode(finding.Code),
-			Scope:    providerSafeScope(finding.Scope),
-		})
-	}
-	return safe, snapshotAliases
-}
-
-func resolveProviderSnapshotAliases(plan repair.RepairPlan, aliases map[string]string) (repair.RepairPlan, error) {
-	resolved := plan
-	resolved.Actions = append([]repair.RepairPlanAction(nil), plan.Actions...)
-	for i := range resolved.Actions {
-		action := &resolved.Actions[i]
-		if action.Type != "restore_snapshot" {
-			continue
-		}
-		id, ok := aliases[action.SnapshotID]
-		if !ok {
-			return repair.RepairPlan{}, fmt.Errorf("AI repair plan referenced unknown snapshot alias %q", action.SnapshotID)
-		}
-		action.SnapshotID = id
-	}
-	return resolved, nil
-}
-
-func providerSafeSeverity(severity string) string {
-	switch severity {
-	case "error", "warning", "info":
-		return severity
-	default:
-		return "unknown"
-	}
-}
-
-func providerSafeDiagnosticCode(code string) string {
-	switch code {
-	case "config.invalid_toml", "config.load_failed",
-		"provider.missing_name", "provider.duplicate_name", "provider.unsupported_kind",
-		"provider.no_models", "provider.invalid_url", "provider.invalid_models_url",
-		"provider.invalid_key_name", "provider.missing_key",
-		"model.no_default", "model.invalid_default",
-		"plugin.missing_name", "plugin.duplicate_name", "plugin.missing_command",
-		"plugin.command_missing", "plugin.invalid_url", "plugin.invalid_type",
-		"permissions.conflict", "file.permissions",
-		"directory.unavailable", "directory.unreadable", "directory.not_directory", "directory.not_writable",
-		"derived.invalid_json",
-		"network.invalid_proxy", "network.client_failed", "network.unreachable",
-		"network.authentication_failed", "network.ok", "network.unexpected_status":
-		return code
-	default:
-		return "unknown"
-	}
-}
-
-// providerSafeScope generalizes a finding scope to a closed vocabulary.
-// derived:* names survive because rebuild_derived_state needs the target and
-// the suffixes are a fixed enum; provider:*/plugin:* carry user-chosen names
-// and collapse to their category; anything unrecognized becomes "other".
-func providerSafeScope(scope string) string {
-	scope = strings.TrimSpace(scope)
-	switch {
-	case scope == "":
-		return ""
-	case strings.HasPrefix(scope, "derived:"):
-		switch scope[len("derived:"):] {
-		case "tabs", "projects", "window", "zoom":
-			return scope
-		}
-		return "derived:other"
-	case strings.HasPrefix(scope, "provider:"):
-		return "provider"
-	case strings.HasPrefix(scope, "plugin:"):
-		return "plugin"
-	}
-	switch scope {
-	case "global", "project", "runtime", "network", "model", "provider", "plugin", "permissions",
-		"global config", "credential file", "Reasonix home", "Reasonix state directory", "project root":
-		return scope
-	}
-	return "other"
-}
-
-func printPlanPreview(plan repair.RepairPlan, previews []repair.RepairPlanPreview) {
-	fmt.Println("AI repair plan:", plan.Summary)
-	for _, preview := range previews {
-		fmt.Printf("  %d. %s\n", preview.Index, preview.Description)
-		if preview.Diff != "" {
-			fmt.Println(preview.Diff)
-		}
-	}
-}
-
-func confirmPlan() bool {
-	fmt.Print("Apply this repair plan? [y/N] ")
-	line, _ := bufio.NewReader(os.Stdin).ReadString('\n')
-	line = strings.ToLower(strings.TrimSpace(line))
-	return line == "y" || line == "yes"
-}
@@ -1,144 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"strings"
-	"testing"
-
-	"reasonix/internal/repair"
-)
-
-// TestProviderSafeReportDropsUserControlledContent pins the outbound-privacy
-// contract: the payload sent to the AI provider must carry only allowlisted
-// codes, severities, and generic scopes — never diagnostic prose, which can
-// quote config lines, MCP command lines, permission rules, URLs with
-// credentials, emails, tokens, or absolute paths.
-func TestProviderSafeReportDropsUserControlledContent(t *testing.T) {
-	const metadataSecret = "snapshot-metadata-secret"
-	const snapshotID = "20260715T000000.000000000Z-abcdef123456"
-	secrets := []string{
-		"/Users/someone/dotfiles",
-		"[email protected]",
-		"sk-live-Abc123Secret",
-		"npx --api-key=sk-live-Abc123Secret mcp-server",
-		"bash(rm -rf *)",
-		"corp-internal-llm",
-		"https://user:[email protected]:8080",
-		metadataSecret,
-		"secret.finding.code",
-		"secret-severity",
-		snapshotID,
-	}
-	report := repair.DiagnosticReport{
-		GeneratedAt: metadataSecret,
-		Root:        "/Users/someone/dotfiles",
-		Network:     true,
-		Snapshots: []repair.DiagnosticSnapshot{
-			{ID: snapshotID, RecordedAt: metadataSecret, Version: metadataSecret},
-			{ID: metadataSecret, RecordedAt: metadataSecret, Version: metadataSecret},
-		},
-		PendingUpdate: &repair.DiagnosticUpdate{FromVersion: metadataSecret, ToVersion: metadataSecret},
-		Findings: []repair.DiagnosticFinding{
-			{Severity: "error", Code: "config.invalid_toml", Scope: "global",
-				Message: "Configuration cannot be parsed: line 3: api_key = \"sk-live-Abc123Secret\" contact [email protected]"},
-			{Severity: "warning", Code: "plugin.command_missing", Scope: "plugin:corp-internal-llm",
-				Message: `MCP command "npx --api-key=sk-live-Abc123Secret mcp-server" was not found.`},
-			{Severity: "warning", Code: "permissions.conflict", Scope: "permissions",
-				Message: `Permission rule "bash(rm -rf *)" appears in allow, deny; deny takes precedence.`},
-			{Severity: "error", Code: "network.invalid_proxy", Scope: "network",
-				Message: "Proxy configuration is invalid: parse \"https://user:[email protected]:8080\": bad"},
-			{Severity: "warning", Code: "provider.missing_key", Scope: "provider:corp-internal-llm",
-				Message: "The configured API key is missing."},
-			{Severity: "warning", Code: "derived.invalid_json", Scope: "derived:tabs",
-				Message: "Derived desktop state desktop-tabs.json is malformed."},
-			{Severity: "secret-severity", Code: "secret.finding.code", Scope: metadataSecret,
-				Message: metadataSecret, Remediation: metadataSecret},
-		},
-	}
-
-	safeReport, aliases := providerSafeReportFrom(report)
-	payload, err := json.Marshal(safeReport)
-	if err != nil {
-		t.Fatal(err)
-	}
-	body := string(payload)
-	for _, secret := range secrets {
-		if strings.Contains(body, secret) {
-			t.Fatalf("outbound payload leaked %q:\n%s", secret, body)
-		}
-	}
-	for _, want := range []string{
-		`"root":"\u003cproject\u003e"`, // json.Marshal HTML-escapes <project>
-		`"code":"config.invalid_toml"`,
-		`"scope":"provider"`,
-		`"scope":"plugin"`,
-		`"scope":"derived:tabs"`,
-		`"id":"snapshot-1"`,
-		`"id":"snapshot-2"`,
-		`"pendingUpdate":true`,
-		`"severity":"unknown"`,
-		`"code":"unknown"`,
-		`"scope":"other"`,
-	} {
-		if !strings.Contains(body, want) {
-			t.Fatalf("outbound payload missing %s:\n%s", want, body)
-		}
-	}
-	if aliases["snapshot-1"] != snapshotID || aliases["snapshot-2"] != metadataSecret {
-		t.Fatalf("snapshot alias map = %v", aliases)
-	}
-	for _, forbiddenField := range []string{"generatedAt", "recordedAt", "version", "fromVersion", "toVersion"} {
-		if strings.Contains(body, `"`+forbiddenField+`"`) {
-			t.Fatalf("outbound payload retained free-form field %q:\n%s", forbiddenField, body)
-		}
-	}
-}
-
-func TestResolveProviderSnapshotAliases(t *testing.T) {
-	const snapshotID = "20260715T000000.000000000Z-abcdef123456"
-	plan, err := repair.DecodeRepairPlan([]byte(`{
-		"schemaVersion": 1,
-		"summary": "restore newest snapshot",
-		"actions": [
-			{"type":"repair_config","scope":"global","reason":"invalid config"},
-			{"type":"restore_snapshot","snapshotId":"snapshot-1","reason":"known-good config"}
-		]
-	}`))
-	if err != nil {
-		t.Fatal(err)
-	}
-	resolved, err := resolveProviderSnapshotAliases(plan, map[string]string{"snapshot-1": snapshotID})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if got := resolved.Actions[1].SnapshotID; got != snapshotID {
-		t.Fatalf("resolved snapshot ID = %q, want %q", got, snapshotID)
-	}
-	if got := plan.Actions[1].SnapshotID; got != "snapshot-1" {
-		t.Fatalf("alias resolution mutated source plan: %q", got)
-	}
-	if _, err := resolveProviderSnapshotAliases(plan, nil); err == nil {
-		t.Fatal("unknown snapshot alias was accepted")
-	}
-}
-
-func TestProviderSafeScopeClosedVocabulary(t *testing.T) {
-	cases := map[string]string{
-		"":                       "",
-		"global":                 "global",
-		"project":                "project",
-		"derived:tabs":           "derived:tabs",
-		"derived:zoom":           "derived:zoom",
-		"derived:/etc/passwd":    "derived:other",
-		"provider:corp-llm":      "provider",
-		"plugin:internal-mcp":    "plugin",
-		"credential file":        "credential file",
-		"[email protected]":    "other",
-		"/Users/someone/project": "other",
-	}
-	for in, want := range cases {
-		if got := providerSafeScope(in); got != want {
-			t.Errorf("providerSafeScope(%q) = %q, want %q", in, got, want)
-		}
-	}
-}
@@ -1,398 +0,0 @@
-// Command reasonix-guard diagnoses and repairs Reasonix without loading the
-// desktop shell. It is packaged beside the desktop application so recovery
-// remains available when Wails, WebView, or user configuration cannot start.
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"flag"
-	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-	"strings"
-
-	"reasonix/internal/repair"
-)
-
-var version = "dev"
-
-func main() { os.Exit(run(os.Args[1:])) }
-
-func run(args []string) int {
-	if len(args) == 0 {
-		return runLaunch(nil)
-	}
-	switch args[0] {
-	case "check":
-		return runCheck(args[1:], false)
-	case "repair":
-		return runCheck(args[1:], true)
-	case "launch":
-		return runLaunch(args[1:])
-	case "recover":
-		return runRecover(args[1:])
-	case "snapshots":
-		return runSnapshots(args[1:])
-	case "restore":
-		return runRestore(args[1:])
-	case "undo":
-		return runUndo(args[1:])
-	case "diagnose":
-		return runDiagnose(args[1:])
-	case "rebuild":
-		return runRebuild(args[1:])
-	case "assist":
-		return runAssist(args[1:])
-	case "apply-plan":
-		return runApplyPlan(args[1:])
-	case "version", "--version", "-v":
-		fmt.Println("reasonix-guard", version)
-		return 0
-	case "help", "--help", "-h":
-		usage()
-		return 0
-	default:
-		if isMacBundleLauncher() {
-			return runLaunch(append([]string{"--"}, args...))
-		}
-		fmt.Fprintln(os.Stderr, "unknown command:", args[0])
-		usage()
-		return 2
-	}
-}
-
-func runDiagnose(args []string) int {
-	fs := flag.NewFlagSet("reasonix-guard diagnose", flag.ContinueOnError)
-	root := fs.String("root", ".", "project root to inspect")
-	network := fs.Bool("network", false, "probe provider endpoints and credentials")
-	jsonOut := fs.Bool("json", false, "print JSON")
-	if err := fs.Parse(args); err != nil || fs.NArg() != 0 {
-		return 2
-	}
-	report, err := repair.Diagnose(context.Background(), repair.DiagnoseOptions{Root: *root, Network: *network})
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	if *jsonOut {
-		if code := printJSON(report); code != 0 {
-			return code
-		}
-	} else {
-		fmt.Println("Reasonix Guard diagnostics")
-		if len(report.Findings) == 0 {
-			fmt.Println("  ok: no issues found")
-		}
-		for _, finding := range report.Findings {
-			fmt.Printf("  %-7s %-32s %s\n", finding.Severity, finding.Code, finding.Message)
-		}
-	}
-	if report.HasErrors() {
-		return 1
-	}
-	return 0
-}
-
-func runRebuild(args []string) int {
-	fs := flag.NewFlagSet("reasonix-guard rebuild", flag.ContinueOnError)
-	target := fs.String("target", "", "tabs|projects|window|zoom|all")
-	jsonOut := fs.Bool("json", false, "print JSON")
-	if err := fs.Parse(args); err != nil || fs.NArg() != 0 || strings.TrimSpace(*target) == "" {
-		return 2
-	}
-	applied, err := repair.RebuildDerivedState(*target)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	if *jsonOut {
-		return printJSON(applied)
-	}
-	for _, path := range applied {
-		fmt.Println("quarantined:", path)
-	}
-	return 0
-}
-
-func runSnapshots(args []string) int {
-	fs := flag.NewFlagSet("reasonix-guard snapshots", flag.ContinueOnError)
-	jsonOut := fs.Bool("json", false, "print JSON")
-	if err := fs.Parse(args); err != nil || fs.NArg() != 0 {
-		return 2
-	}
-	snapshots, err := repair.ListConfigSnapshots()
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	if *jsonOut {
-		return printJSON(snapshots)
-	}
-	for _, snap := range snapshots {
-		fmt.Printf("%s  %s  %s\n", snap.ID, snap.Version, snap.RecordedAt)
-	}
-	return 0
-}
-
-func runRestore(args []string) int {
-	fs := flag.NewFlagSet("reasonix-guard restore", flag.ContinueOnError)
-	snapshot := fs.String("snapshot", "", "snapshot id to restore")
-	if err := fs.Parse(args); err != nil || fs.NArg() != 0 || strings.TrimSpace(*snapshot) == "" {
-		return 2
-	}
-	tx, err := repair.RestoreConfigSnapshot(*snapshot)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	fmt.Println("restored config snapshot; undo transaction:", tx.ID)
-	return 0
-}
-
-func runUndo(args []string) int {
-	fs := flag.NewFlagSet("reasonix-guard undo", flag.ContinueOnError)
-	jsonOut := fs.Bool("json", false, "print JSON")
-	if err := fs.Parse(args); err != nil || fs.NArg() != 0 {
-		return 2
-	}
-	tx, err := repair.UndoLastRepair()
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	if *jsonOut {
-		return printJSON(tx)
-	}
-	fmt.Println("undid repair:", tx.ID)
-	return 0
-}
-
-func printJSON(v any) int {
-	enc := json.NewEncoder(os.Stdout)
-	enc.SetIndent("", "  ")
-	if err := enc.Encode(v); err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	return 0
-}
-
-func runCheck(args []string, apply bool) int {
-	name := "reasonix-guard check"
-	if apply {
-		name = "reasonix-guard repair"
-	}
-	fs := flag.NewFlagSet(name, flag.ContinueOnError)
-	root := fs.String("root", ".", "project root to inspect")
-	includeProject := fs.Bool("project", false, "allow repair to quarantine project reasonix.toml")
-	jsonOut := fs.Bool("json", false, "print JSON")
-	if err := fs.Parse(args); err != nil || fs.NArg() != 0 {
-		return 2
-	}
-	report, err := repair.InspectAndRepairConfig(repair.ConfigOptions{Root: *root, Apply: apply, IncludeProject: *includeProject})
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	if *jsonOut {
-		enc := json.NewEncoder(os.Stdout)
-		enc.SetIndent("", "  ")
-		if err := enc.Encode(report); err != nil {
-			return 1
-		}
-	} else {
-		fmt.Println("Reasonix Guard")
-		for _, check := range report.Checks {
-			status := "ok"
-			if !check.Exists {
-				status = "missing"
-			} else if !check.Valid {
-				status = "invalid"
-			}
-			fmt.Printf("  %-8s %-8s %s\n", check.Scope, status, check.Path)
-			if check.Error != "" {
-				fmt.Println("    ", check.Error)
-			}
-		}
-		for _, action := range report.Applied {
-			fmt.Println("  applied:", action)
-		}
-	}
-	for _, check := range report.Checks {
-		if check.Exists && !check.Valid {
-			return 1
-		}
-	}
-	return 0
-}
-
-// failedInstallBlocksLaunch decides whether startup must stop after a failed
-// RecoverFailedInstall. The failure marker means the installer may have left
-// the release unit partially replaced, so the binaries cannot be presumed
-// coherent until a rollback completes: any error with the restore unfinished
-// fails closed. MixedInstall alone is not the signal — a rollback that failed
-// before touching anything (e.g. while staging) reports MixedInstall=false yet
-// leaves the installer's half-written unit in place. Only a completed restore
-// (RolledBack, with just the marker cleanup failing) is safe to launch.
-func failedInstallBlocksLaunch(result repair.UpdateRollbackResult, err error) bool {
-	return err != nil && !result.RolledBack
-}
-
-func runLaunch(args []string) int {
-	fs := flag.NewFlagSet("reasonix-guard launch", flag.ContinueOnError)
-	app := fs.String("app", "", "desktop executable path")
-	safeMode := fs.Bool("safe-mode", false, "force Safe Mode")
-	detach := fs.Bool("detach", packagedDetachedLauncher(), "start the desktop and exit the launcher")
-	if err := fs.Parse(args); err != nil {
-		return 2
-	}
-	// An update helper that watched the installer fail records a marker (it
-	// cannot roll back itself from outside the install directory). Restore the
-	// previous release unit immediately instead of waiting for a crash loop.
-	if result, failure, err := repair.RecoverFailedInstall(); err != nil {
-		fmt.Fprintln(os.Stderr, "update rollback after failed install failed:", err)
-		if failedInstallBlocksLaunch(result, err) {
-			fmt.Fprintln(os.Stderr, "error: the failed installer may have left a mix of two releases and the rollback did not complete; refusing to start. Re-run reasonix-guard to retry the rollback, or reinstall Reasonix.")
-			return 1
-		}
-	} else if failure != nil && result.RolledBack {
-		fmt.Fprintf(os.Stderr, "Reasonix Guard restored %s after the %s installer failed.\n", result.ToVersion, result.FromVersion)
-	}
-	tracker := repair.NewStartupTracker("")
-	useSafeMode := *safeMode
-	if !*safeMode && tracker.SafeModeRecommended() {
-		if result, err := repair.RollbackPendingUpdate(); err != nil {
-			fmt.Fprintln(os.Stderr, "update rollback failed:", err)
-			if result.MixedInstall {
-				fmt.Fprintln(os.Stderr, "error: the installation now mixes two releases; refusing to start. Re-run reasonix-guard to retry the rollback, or reinstall Reasonix.")
-				return 1
-			}
-			// The compensated install is still a coherent (new-version) release
-			// unit, so a Safe Mode boot is a sound fallback while the pending
-			// transaction stays on disk for the next rollback attempt.
-			useSafeMode = true
-		} else if result.RolledBack {
-			fmt.Fprintf(os.Stderr, "Reasonix Guard restored %s after %s failed to start.\n", result.ToVersion, result.FromVersion)
-			_ = tracker.MarkClean()
-		} else {
-			switch nativeRecoveryChoice() {
-			case recoveryRepair:
-				if _, err := repair.InspectAndRepairConfig(repair.ConfigOptions{Root: ".", Apply: true}); err != nil {
-					fmt.Fprintln(os.Stderr, "repair failed:", err)
-				}
-				useSafeMode = true
-			case recoverySafeMode:
-				useSafeMode = true
-			case recoveryQuit:
-				return 0
-			}
-		}
-	}
-	path := strings.TrimSpace(*app)
-	if path == "" {
-		path = siblingDesktopExecutable()
-	}
-	if path == "" {
-		fmt.Fprintln(os.Stderr, "error: cannot locate reasonix-desktop; pass --app PATH")
-		return 1
-	}
-	childArgs := append([]string(nil), fs.Args()...)
-	if useSafeMode {
-		childArgs = append([]string{"--safe-mode"}, childArgs...)
-	}
-	cmd := exec.Command(path, childArgs...)
-	cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
-	if *detach {
-		if err := cmd.Start(); err != nil {
-			fmt.Fprintln(os.Stderr, "error:", err)
-			return 1
-		}
-		return 0
-	}
-	if err := cmd.Run(); err != nil {
-		if exit, ok := err.(*exec.ExitError); ok {
-			return exit.ExitCode()
-		}
-		fmt.Fprintln(os.Stderr, "error:", err)
-		return 1
-	}
-	return 0
-}
-
-func packagedDetachedLauncher() bool {
-	if runtime.GOOS != "windows" {
-		return false
-	}
-	exe, err := os.Executable()
-	if err != nil {
-		return false
-	}
-	name := strings.ToLower(filepath.Base(exe))
-	return name == "reasonix-launcher.exe" || name == "reasonix.exe"
-}
-
-func runRecover(args []string) int {
-	fs := flag.NewFlagSet("reasonix-guard recover", flag.ContinueOnError)
-	root := fs.String("root", ".", "project root to inspect")
-	includeProject := fs.Bool("project", false, "allow repair to quarantine project reasonix.toml")
-	app := fs.String("app", "", "desktop executable path")
-	if err := fs.Parse(args); err != nil || fs.NArg() != 0 {
-		return 2
-	}
-	switch nativeRecoveryChoice() {
-	case recoveryRepair:
-		if _, err := repair.InspectAndRepairConfig(repair.ConfigOptions{Root: *root, Apply: true, IncludeProject: *includeProject}); err != nil {
-			fmt.Fprintln(os.Stderr, "repair failed:", err)
-			return 1
-		}
-		launch := []string{"--safe-mode"}
-		if strings.TrimSpace(*app) != "" {
-			launch = append(launch, "--app", *app)
-		}
-		return runLaunch(launch)
-	case recoverySafeMode:
-		launch := []string{"--safe-mode"}
-		if strings.TrimSpace(*app) != "" {
-			launch = append(launch, "--app", *app)
-		}
-		return runLaunch(launch)
-	default:
-		return 0
-	}
-}
-
-func siblingDesktopExecutable() string {
-	exe, err := os.Executable()
-	if err != nil {
-		return ""
-	}
-	name := "reasonix-desktop"
-	if runtime.GOOS == "windows" {
-		name += ".exe"
-	}
-	candidates := []string{filepath.Join(filepath.Dir(exe), name)}
-	if runtime.GOOS == "darwin" {
-		candidates = append(candidates, filepath.Clean(filepath.Join(filepath.Dir(exe), "..", "MacOS", name)))
-	}
-	for _, path := range candidates {
-		if _, err := os.Stat(path); err == nil {
-			return path
-		}
-	}
-	return ""
-}
-
-func isMacBundleLauncher() bool {
-	if runtime.GOOS != "darwin" {
-		return false
-	}
-	exe, err := os.Executable()
-	return err == nil && strings.Contains(filepath.ToSlash(exe), ".app/Contents/MacOS/")
-}
-
-func usage() {
-	fmt.Println("usage: reasonix-guard <check|repair|diagnose|rebuild|assist|apply-plan|launch|recover|snapshots|restore|undo> [options]")
-}
@@ -1,39 +0,0 @@
-package main
-
-import (
-	"errors"
-	"os"
-	"path/filepath"
-	"testing"
-
-	"reasonix/internal/repair"
-)
-
-func TestCheckReportsInvalidProjectConfig(t *testing.T) {
-	root := t.TempDir()
-	if err := os.WriteFile(filepath.Join(root, "reasonix.toml"), []byte("[broken\n"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	if code := run([]string{"check", "--root", root, "--json"}); code != 1 {
-		t.Fatalf("exit code = %d, want 1", code)
-	}
-}
-
-func TestFailedInstallBlocksLaunch(t *testing.T) {
-	cases := []struct {
-		name   string
-		result repair.UpdateRollbackResult
-		err    error
-		want   bool
-	}{
-		{name: "no error never blocks", result: repair.UpdateRollbackResult{}, err: nil, want: false},
-		{name: "incomplete rollback fails closed", result: repair.UpdateRollbackResult{}, err: errors.New("stage failed"), want: true},
-		{name: "uncompensated rollback fails closed", result: repair.UpdateRollbackResult{MixedInstall: true}, err: errors.New("restore failed"), want: true},
-		{name: "completed restore with marker cleanup error launches", result: repair.UpdateRollbackResult{RolledBack: true}, err: errors.New("remove marker: permission denied"), want: false},
-	}
-	for _, tc := range cases {
-		if got := failedInstallBlocksLaunch(tc.result, tc.err); got != tc.want {
-			t.Errorf("%s: failedInstallBlocksLaunch = %v, want %v", tc.name, got, tc.want)
-		}
-	}
-}
@@ -1,9 +0,0 @@
-package main
-
-type recoveryChoice int
-
-const (
-	recoveryQuit recoveryChoice = iota
-	recoverySafeMode
-	recoveryRepair
-)
@@ -1,24 +0,0 @@
-//go:build darwin
-
-package main
-
-import (
-	"os/exec"
-	"strings"
-)
-
-func nativeRecoveryChoice() recoveryChoice {
-	script := `button returned of (display dialog "Reasonix failed to start repeatedly. You can repair damaged configuration or start with external integrations disabled." with title "Reasonix Recovery" buttons {"Quit", "Safe Mode", "Repair and Start"} default button "Repair and Start" with icon caution)`
-	out, err := exec.Command("osascript", "-e", script).Output()
-	if err != nil {
-		return recoverySafeMode
-	}
-	switch strings.TrimSpace(string(out)) {
-	case "Repair and Start":
-		return recoveryRepair
-	case "Safe Mode":
-		return recoverySafeMode
-	default:
-		return recoveryQuit
-	}
-}
@@ -1,36 +0,0 @@
-//go:build linux
-
-package main
-
-import (
-	"errors"
-	"os/exec"
-	"strings"
-)
-
-func nativeRecoveryChoice() recoveryChoice {
-	if path, err := exec.LookPath("zenity"); err == nil {
-		cmd := exec.Command(path, "--question", "--title=Reasonix Recovery",
-			"--text=Reasonix failed to start repeatedly.",
-			"--ok-label=Repair and Start", "--cancel-label=Safe Mode", "--extra-button=Quit")
-		out, err := cmd.Output()
-		if strings.TrimSpace(string(out)) == "Quit" {
-			return recoveryQuit
-		}
-		if err == nil {
-			return recoveryRepair
-		}
-		return recoverySafeMode
-	}
-	if path, err := exec.LookPath("kdialog"); err == nil {
-		err := exec.Command(path, "--warningyesnocancel", "Reasonix failed to start repeatedly. Repair configuration and start?", "--title", "Reasonix Recovery").Run()
-		if err == nil {
-			return recoveryRepair
-		}
-		var exitErr *exec.ExitError
-		if errors.As(err, &exitErr) && exitErr.ExitCode() == 2 {
-			return recoveryQuit
-		}
-	}
-	return recoverySafeMode
-}
@@ -1,5 +0,0 @@
-//go:build !darwin && !windows && !linux
-
-package main
-
-func nativeRecoveryChoice() recoveryChoice { return recoverySafeMode }
@@ -1,27 +0,0 @@
-//go:build windows
-
-package main
-
-import (
-	"os/exec"
-	"strings"
-	"syscall"
-)
-
-func nativeRecoveryChoice() recoveryChoice {
-	script := `Add-Type -AssemblyName PresentationFramework; $r=[System.Windows.MessageBox]::Show('Reasonix failed to start repeatedly. Yes: repair configuration and start. No: start in Safe Mode. Cancel: quit.','Reasonix Recovery','YesNoCancel','Warning'); Write-Output $r`
-	cmd := exec.Command("powershell.exe", "-NoProfile", "-NonInteractive", "-Command", script)
-	cmd.SysProcAttr = &syscall.SysProcAttr{HideWindow: true}
-	out, err := cmd.Output()
-	if err != nil {
-		return recoverySafeMode
-	}
-	switch strings.TrimSpace(string(out)) {
-	case "Yes":
-		return recoveryRepair
-	case "No":
-		return recoverySafeMode
-	default:
-		return recoveryQuit
-	}
-}
@@ -0,0 +1,32 @@
+// Command reasonix-launcher is the permanent thin desktop entry point for the
+// versioned install layout (v1.20+). It reads InstallRoot/current.json, starts
+// the active reasonix-desktop binary, and exits. It never counts crashes,
+// chooses previous versions, or enters a product safe mode.
+//
+// Migration compatibility: old shortcuts may still pass "launch", "--detach",
+// or "--safe-mode". Those tokens are stripped and ignored.
+package main
+
+import (
+	"os"
+
+	"reasonix/internal/desktoplauncher"
+)
+
+var version = "dev"
+
+func main() {
+	os.Exit(run(os.Args[1:]))
+}
+
+func run(args []string) int {
+	return desktoplauncher.Run(args, version)
+}
+
+func resolveDesktopPath(installRoot string) (string, error) {
+	return desktoplauncher.ResolveDesktopPath(installRoot)
+}
+
+func stripLegacyLaunchArgs(args []string) []string {
+	return desktoplauncher.StripLegacyLaunchArgs(args)
+}
@@ -0,0 +1,88 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"reasonix/internal/installlayout"
+)
+
+func TestStripLegacyLaunchArgs(t *testing.T) {
+	got := stripLegacyLaunchArgs([]string{
+		"launch", "--detach", "--safe-mode", "--app", `C:\Old\reasonix-desktop.exe`, "--foo", "bar",
+	})
+	want := []string{"--foo", "bar"}
+	if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
+		t.Fatalf("got %#v want %#v", got, want)
+	}
+	got = stripLegacyLaunchArgs([]string{"--app=ignored", "keep"})
+	if len(got) != 1 || got[0] != "keep" {
+		t.Fatalf("got %#v", got)
+	}
+	got = stripLegacyLaunchArgs([]string{"--", "--safe-mode", "x"})
+	if len(got) != 3 || got[0] != "--" {
+		t.Fatalf("separator not preserved: %#v", got)
+	}
+}
+
+func TestResolveDesktopPathUsesCurrentJSON(t *testing.T) {
+	root := t.TempDir()
+	src := t.TempDir()
+	version := "v1.20.0"
+	members := make([]installlayout.Member, 0, 3)
+	for _, name := range installlayout.AllowedVersionMembers() {
+		path := filepath.Join(src, name)
+		if err := os.WriteFile(path, []byte("bin-"+name), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		members = append(members, installlayout.Member{Name: name, Path: path})
+	}
+	if err := installlayout.ActivateVersion(installlayout.ActivationRequest{
+		InstallRoot: root,
+		Version:     version,
+		RequestID:   "launcher-test",
+		Members:     members,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	path, err := resolveDesktopPath(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := filepath.Join(root, "versions", version, installlayout.DesktopBinaryName())
+	if path != want {
+		t.Fatalf("path=%s want=%s", path, want)
+	}
+}
+
+func TestResolveDesktopPathFallsBackToFlatSibling(t *testing.T) {
+	root := t.TempDir()
+	flat := filepath.Join(root, installlayout.DesktopBinaryName())
+	if err := os.WriteFile(flat, []byte("flat"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	path, err := resolveDesktopPath(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if path != flat {
+		t.Fatalf("path=%s want=%s", path, flat)
+	}
+}
+
+func TestResolveDesktopPathRejectsCorruptPointer(t *testing.T) {
+	root := t.TempDir()
+	// Write a current.json that fails schema validation.
+	if err := os.WriteFile(filepath.Join(root, installlayout.CurrentFileName), []byte(`{"schemaVersion":99}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Even with a flat sibling, a corrupt pointer must fail closed. Falling back
+	// would silently run a stale executable after a partially observed update.
+	if err := os.WriteFile(filepath.Join(root, installlayout.DesktopBinaryName()), []byte("x"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if path, err := resolveDesktopPath(root); err == nil {
+		t.Fatalf("corrupt current.json resolved stale flat desktop %q", path)
+	}
+}
@@ -0,0 +1,525 @@
+// Command reasonix-legacy-migrator is the one-shot flat→versioned install
+// migrator used by v1.20+ packaging. In compatibility payloads it is still
+// named reasonix-guard(.exe) so 1.18–1.19.1 updaters can hand off; the source
+// and behavior are intentionally separate from the old Guard recovery product.
+//
+// It only: acquires a migration lock, validates the flat release unit, creates
+// versions/<version>, writes current.json, rewrites entry points, starts the
+// thin launcher, and self-deletes when possible. It never chooses safe mode,
+// counts crashes, or auto-rolls back.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"time"
+
+	"reasonix/internal/desktoplauncher"
+	"reasonix/internal/fileutil"
+	"reasonix/internal/installlayout"
+	"reasonix/internal/repair"
+)
+
+var version = "dev"
+
+const migrationLockName = ".reasonix-layout-migrate.lock"
+
+func main() {
+	if runningAsLauncher() {
+		os.Exit(desktoplauncher.Run(os.Args[1:], version))
+	}
+	os.Exit(run(os.Args[1:]))
+}
+
+func run(args []string) int {
+	if len(args) == 1 {
+		switch args[0] {
+		case "version", "--version", "-v":
+			fmt.Println("reasonix-legacy-migrator", version)
+			return 0
+		case "help", "--help", "-h":
+			fmt.Println("usage: reasonix-legacy-migrator [--install-root PATH] [--version VERSION] [--activate-staging PATH]")
+			return 0
+		}
+	}
+
+	installRoot := ""
+	activeVersion := strings.TrimSpace(version)
+	activateStaging := ""
+	relaunch := true
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--install-root":
+			if i+1 >= len(args) {
+				fmt.Fprintln(os.Stderr, "error: --install-root requires a path")
+				return 2
+			}
+			i++
+			installRoot = args[i]
+		case "--version":
+			if i+1 >= len(args) {
+				fmt.Fprintln(os.Stderr, "error: --version requires a value")
+				return 2
+			}
+			i++
+			activeVersion = args[i]
+		case "--activate-staging":
+			if i+1 >= len(args) {
+				fmt.Fprintln(os.Stderr, "error: --activate-staging requires a path")
+				return 2
+			}
+			i++
+			activateStaging = args[i]
+		case "launch", "--detach", "--safe-mode":
+			// Accept legacy argv from old shortcuts; no product behavior.
+			continue
+		case "--no-relaunch":
+			relaunch = false
+			continue
+		case "--app":
+			if i+1 < len(args) {
+				i++
+			}
+			continue
+		}
+	}
+	if installRoot == "" {
+		exe, err := os.Executable()
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "error:", err)
+			return 1
+		}
+		installRoot = filepath.Dir(exe)
+	}
+	installRoot = filepath.Clean(installRoot)
+	if activateStaging != "" {
+		activeVersion, err := normalizeActiveVersion(activeVersion)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "error:", err)
+			return 1
+		}
+		if err := activateInstallerStaging(installRoot, activeVersion, activateStaging); err != nil {
+			fmt.Fprintln(os.Stderr, "error:", err)
+			return 1
+		}
+		if relaunch {
+			_ = startLauncher(installRoot)
+		}
+		return 0
+	}
+
+	if err := migrateWithRelaunch(installRoot, activeVersion, relaunch); err != nil {
+		fmt.Fprintln(os.Stderr, "error:", err)
+		return 1
+	}
+	return 0
+}
+
+func migrate(installRoot, activeVersion string) error {
+	return migrateWithRelaunch(installRoot, activeVersion, true)
+}
+
+func migrateWithRelaunch(installRoot, activeVersion string, relaunch bool) error {
+	var err error
+	activeVersion, err = normalizeActiveVersion(activeVersion)
+	if err != nil {
+		return err
+	}
+
+	unlock, err := acquireMigrationLock(installRoot)
+	if err != nil {
+		return err
+	}
+	defer unlock()
+
+	// Pointer already committed: only cleanup, never overwrite the active version.
+	// A present but corrupt pointer is fatal; treating it like an absent pointer
+	// could overwrite evidence of a partial activation and migrate stale files.
+	currentPath := filepath.Join(installRoot, installlayout.CurrentFileName)
+	if _, statErr := os.Lstat(currentPath); statErr == nil {
+		ptr, err := installlayout.ReadCurrent(installRoot)
+		if err != nil {
+			return err
+		}
+		if err := finalizeLegacyPendingUpdate(installRoot, ptr.ActiveVersion); err != nil {
+			return err
+		}
+		_ = cleanupLegacyFlatFiles(installRoot)
+		_ = archiveInstallRootLegacyMarkers(installRoot)
+		if relaunch {
+			_ = startLauncher(installRoot) // best-effort; layout already committed
+			selfDelete()
+		}
+		return nil
+	} else if !os.IsNotExist(statErr) {
+		return fmt.Errorf("migrate: inspect current.json: %w", statErr)
+	}
+
+	desktopName := installlayout.DesktopBinaryName()
+	cliName := installlayout.CLIBinaryName()
+	helperName := installlayout.UpdateHelperBinaryName()
+	flatDesktop := filepath.Join(installRoot, desktopName)
+	if _, err := os.Lstat(flatDesktop); err != nil {
+		return fmt.Errorf("migrate: flat desktop binary missing: %w", err)
+	}
+
+	members := []installlayout.Member{
+		{Name: desktopName, Path: flatDesktop},
+	}
+	if p := optionalRegular(filepath.Join(installRoot, cliName)); p != "" {
+		members = append(members, installlayout.Member{Name: cliName, Path: p})
+	} else {
+		// CLI may be absent on some portable trees; synthesize from desktop only
+		// is not allowed — require the whitelist. Prefer copying desktop as a
+		// last-resort placeholder is forbidden; fail closed.
+		return fmt.Errorf("migrate: flat CLI binary %s is required", cliName)
+	}
+	requiredNames := []string{desktopName, cliName}
+	if runtime.GOOS == "windows" {
+		requiredNames = append(requiredNames, helperName)
+		if p := optionalRegular(filepath.Join(installRoot, helperName)); p != "" {
+			members = append(members, installlayout.Member{Name: helperName, Path: p})
+		} else {
+			return fmt.Errorf("migrate: flat update helper %s is required", helperName)
+		}
+	}
+
+	// Old Linux updaters only publish desktop, CLI, and the compatibility
+	// migrator. On Unix the migrator is also a thin-launcher multicall binary,
+	// so it can create the permanent entry point without another payload member.
+	if err := ensureLauncherEntry(installRoot); err != nil {
+		return err
+	}
+	// v1.18-v1.19 helpers leave an installed transaction awaiting Guard health.
+	// The flat release unit is still intact here, so commit that exact verified
+	// transaction before moving its files into the version directory.
+	if err := finalizeLegacyPendingUpdate(installRoot, activeVersion); err != nil {
+		return err
+	}
+
+	if err := installlayout.ActivateVersion(installlayout.ActivationRequest{
+		InstallRoot:   installRoot,
+		Version:       activeVersion,
+		RequestID:     "legacy-migrate",
+		Members:       members,
+		RequiredNames: requiredNames,
+	}); err != nil {
+		return fmt.Errorf("migrate: activate versioned layout: %w", err)
+	}
+
+	_ = cleanupLegacyFlatFiles(installRoot)
+	_ = archiveInstallRootLegacyMarkers(installRoot)
+	if relaunch {
+		// Launcher start is best-effort: layout activation is the commit point.
+		if err := startLauncher(installRoot); err != nil {
+			fmt.Fprintln(os.Stderr, "warning: start launcher after migrate:", err)
+		}
+		// Unix can unlink the running migrator. On Windows the parent thin launcher
+		// removes it after this process exits.
+		selfDelete()
+	}
+	return nil
+}
+
+func normalizeActiveVersion(activeVersion string) (string, error) {
+	if err := installlayout.ValidateVersionName(activeVersion); err != nil {
+		// Accept bare "dev" builds in development only.
+		if activeVersion == "" || activeVersion == "dev" {
+			activeVersion = "v0.0.0-dev"
+			if err := installlayout.ValidateVersionName(activeVersion); err != nil {
+				return "", err
+			}
+		} else if !strings.HasPrefix(activeVersion, "v") {
+			activeVersion = "v" + activeVersion
+			if err := installlayout.ValidateVersionName(activeVersion); err != nil {
+				return "", err
+			}
+		} else {
+			return "", err
+		}
+	}
+	return activeVersion, nil
+}
+
+func activateInstallerStaging(installRoot, activeVersion, stagingRoot string) error {
+	installRoot = filepath.Clean(strings.TrimSpace(installRoot))
+	stagingRoot = filepath.Clean(strings.TrimSpace(stagingRoot))
+	if !pathWithinInstallRoot(installRoot, stagingRoot) || stagingRoot == installRoot {
+		return fmt.Errorf("installer staging must be inside the install root")
+	}
+	info, err := os.Lstat(stagingRoot)
+	if err != nil {
+		return fmt.Errorf("inspect installer staging: %w", err)
+	}
+	if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+		return fmt.Errorf("installer staging must be a real directory")
+	}
+
+	desktopName := installlayout.DesktopBinaryName()
+	cliName := installlayout.CLIBinaryName()
+	requiredNames := []string{desktopName, cliName}
+	if runtime.GOOS == "windows" {
+		requiredNames = append(requiredNames, installlayout.UpdateHelperBinaryName())
+	}
+	members := make([]installlayout.Member, 0, len(requiredNames))
+	for _, name := range requiredNames {
+		members = append(members, installlayout.Member{Name: name, Path: filepath.Join(stagingRoot, name)})
+	}
+
+	launcherName := installlayout.LauncherBinaryName()
+	launcherSource := filepath.Join(stagingRoot, launcherName)
+	rootMembers := []installlayout.Member{
+		{Name: launcherName, Path: launcherSource},
+		{Name: cliName, Path: filepath.Join(stagingRoot, cliName)},
+	}
+	requiredRootNames := []string{launcherName, cliName}
+	if alias := installlayout.PortableAliasName(); alias != "" {
+		rootMembers = append(rootMembers, installlayout.Member{Name: alias, Path: launcherSource})
+		requiredRootNames = append(requiredRootNames, alias)
+	}
+
+	if err := installlayout.ActivateVersion(installlayout.ActivationRequest{
+		InstallRoot:       installRoot,
+		Version:           activeVersion,
+		RequestID:         "signed-installer-" + activeVersion,
+		Members:           members,
+		RequiredNames:     requiredNames,
+		RootMembers:       rootMembers,
+		RequiredRootNames: requiredRootNames,
+	}); err != nil {
+		return fmt.Errorf("activate signed installer staging: %w", err)
+	}
+	return nil
+}
+
+func runningAsLauncher() bool {
+	exe, err := os.Executable()
+	if err != nil {
+		return false
+	}
+	return strings.EqualFold(filepath.Base(exe), installlayout.LauncherBinaryName())
+}
+
+func optionalRegular(path string) string {
+	info, err := os.Lstat(path)
+	if err != nil || !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 {
+		return ""
+	}
+	return path
+}
+
+func acquireMigrationLock(installRoot string) (func(), error) {
+	if err := os.MkdirAll(installRoot, 0o755); err != nil {
+		return nil, err
+	}
+	path := filepath.Join(installRoot, migrationLockName)
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+	if err != nil {
+		if os.IsExist(err) {
+			// Stale lock from a dead migrator: if older than 10 minutes, steal it.
+			info, statErr := os.Stat(path)
+			if statErr == nil && time.Since(info.ModTime()) > 10*time.Minute {
+				_ = os.Remove(path)
+				f, err = os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+			}
+		}
+		if err != nil {
+			return nil, fmt.Errorf("migrate: acquire lock: %w", err)
+		}
+	}
+	_, _ = fmt.Fprintf(f, "pid=%d\nversion=%s\n", os.Getpid(), version)
+	_ = f.Close()
+	return func() { _ = os.Remove(path) }, nil
+}
+
+func ensureLauncherEntry(installRoot string) error {
+	launcher := installlayout.LauncherBinaryName()
+	path := filepath.Join(installRoot, launcher)
+	if info, err := os.Lstat(path); err == nil {
+		if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 {
+			return fmt.Errorf("migrate: thin launcher %s is not a regular file", launcher)
+		}
+		return nil
+	}
+	// On Windows also accept Reasonix.exe as the alias.
+	if runtime.GOOS == "windows" {
+		if _, err := os.Lstat(filepath.Join(installRoot, "Reasonix.exe")); err == nil {
+			return nil
+		}
+		return fmt.Errorf("migrate: thin launcher %s is missing; install a signed package", launcher)
+	}
+
+	// Legacy Linux archives cannot deliver a fourth member through the old
+	// updater. Copy this signed multicall migrator as the permanent thin launcher.
+	exe, err := os.Executable()
+	if err != nil {
+		return fmt.Errorf("migrate: resolve migrator executable: %w", err)
+	}
+	info, err := os.Lstat(exe)
+	if err != nil || !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 {
+		return fmt.Errorf("migrate: migrator executable is not a regular file")
+	}
+	body, err := os.ReadFile(exe)
+	if err != nil {
+		return fmt.Errorf("migrate: read launcher source: %w", err)
+	}
+	if err := fileutil.AtomicWriteFile(path, body, 0o755); err != nil {
+		return fmt.Errorf("migrate: install thin launcher: %w", err)
+	}
+	return nil
+}
+
+func finalizeLegacyPendingUpdate(installRoot, activeVersion string) error {
+	tx, err := repair.ReadPendingUpdate()
+	if os.IsNotExist(err) {
+		return nil
+	}
+	if err != nil {
+		return fmt.Errorf("migrate: read legacy pending update: %w", err)
+	}
+	if tx.TargetKind != "file" {
+		return fmt.Errorf("migrate: legacy pending update target kind %q is not supported", tx.TargetKind)
+	}
+	if strings.TrimSpace(tx.ToVersion) != strings.TrimSpace(activeVersion) {
+		return fmt.Errorf("migrate: pending update targets %s, not %s", tx.ToVersion, activeVersion)
+	}
+	for _, target := range append([]repair.UpdateTransactionFile{{TargetPath: tx.TargetPath}}, tx.Files...) {
+		if !pathWithinInstallRoot(installRoot, target.TargetPath) {
+			return fmt.Errorf("migrate: pending update target escapes install root")
+		}
+	}
+	id := repair.UpdateTransactionID(tx)
+	if err := repair.MarkUpdateHealthyExact(activeVersion, tx.CreatedAt, id); err != nil {
+		return fmt.Errorf("migrate: commit legacy pending update: %w", err)
+	}
+	if current, err := repair.ReadPendingUpdate(); err == nil {
+		if repair.UpdateTransactionID(current) == id {
+			return fmt.Errorf("migrate: legacy pending update remained after commit")
+		}
+		return fmt.Errorf("migrate: pending update changed during commit")
+	} else if !os.IsNotExist(err) {
+		return fmt.Errorf("migrate: verify legacy pending update commit: %w", err)
+	}
+	return nil
+}
+
+func pathWithinInstallRoot(installRoot, target string) bool {
+	root := filepath.Clean(strings.TrimSpace(installRoot))
+	target = filepath.Clean(strings.TrimSpace(target))
+	if root == "" || target == "" || !filepath.IsAbs(root) || !filepath.IsAbs(target) {
+		return false
+	}
+	rel, err := filepath.Rel(root, target)
+	if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) || filepath.IsAbs(rel) {
+		return false
+	}
+	return true
+}
+
+func cleanupLegacyFlatFiles(installRoot string) error {
+	// Remove flat desktop/CLI/helper/guard sidecars after the version tree is
+	// active. Never delete the thin launcher or current.json.
+	names := []string{
+		installlayout.DesktopBinaryName(),
+		installlayout.CLIBinaryName(),
+		installlayout.UpdateHelperBinaryName(),
+	}
+	if runtime.GOOS == "windows" {
+		names = append(names, "reasonix-guard.exe")
+	} else {
+		names = append(names, "reasonix-guard")
+	}
+	for _, name := range names {
+		path := filepath.Join(installRoot, name)
+		info, err := os.Lstat(path)
+		if err != nil || !info.Mode().IsRegular() {
+			continue
+		}
+		_ = os.Remove(path)
+	}
+	return nil
+}
+
+func archiveInstallRootLegacyMarkers(installRoot string) error {
+	// Very old portable builds wrote markers beside the binary. Current repair
+	// state under Reasonix home is finalized through repair transaction APIs.
+	markers := []string{
+		"pending-update.json",
+		"startup-state.json",
+	}
+	ts := time.Now().UTC().Format("20060102T150405Z")
+	destRoot := filepath.Join(installRoot, "repair", "legacy-v1", ts)
+	moved := false
+	for _, name := range markers {
+		src := filepath.Join(installRoot, name)
+		if _, err := os.Lstat(src); err != nil {
+			continue
+		}
+		if err := os.MkdirAll(destRoot, 0o755); err != nil {
+			return err
+		}
+		dest := filepath.Join(destRoot, name)
+		if err := os.Rename(src, dest); err != nil {
+			// Cross-device: copy+remove best effort.
+			data, readErr := os.ReadFile(src)
+			if readErr != nil {
+				continue
+			}
+			if writeErr := fileutil.AtomicWriteFile(dest, data, 0o600); writeErr == nil {
+				_ = os.Remove(src)
+			}
+		}
+		moved = true
+	}
+	if moved {
+		meta, _ := json.MarshalIndent(map[string]any{
+			"migratedAt": time.Now().UTC().Format(time.RFC3339),
+			"from":       "flat-v1",
+			"to":         installlayout.InstallLayoutVersionedV1,
+		}, "", "  ")
+		_ = fileutil.AtomicWriteFile(filepath.Join(destRoot, "migration.json"), append(meta, '\n'), 0o644)
+	}
+	return nil
+}
+
+func startLauncher(installRoot string) error {
+	launcher := "reasonix-launcher"
+	if runtime.GOOS == "windows" {
+		launcher += ".exe"
+	}
+	path := filepath.Join(installRoot, launcher)
+	if _, err := os.Lstat(path); err != nil {
+		if runtime.GOOS == "windows" {
+			path = filepath.Join(installRoot, "Reasonix.exe")
+		}
+	}
+	if _, err := os.Lstat(path); err != nil {
+		// Migration succeeded; user can start manually.
+		return nil
+	}
+	cmd := exec.Command(path)
+	cmd.Dir = installRoot
+	cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
+	if runtime.GOOS == "windows" {
+		return cmd.Start()
+	}
+	return cmd.Start()
+}
+
+func selfDelete() {
+	exe, err := os.Executable()
+	if err != nil {
+		return
+	}
+	// Do not delete if we are not named like a compatibility guard payload.
+	base := strings.ToLower(filepath.Base(exe))
+	if base != "reasonix-guard" && base != "reasonix-guard.exe" {
+		return
+	}
+	_ = os.Remove(exe)
+}
@@ -0,0 +1,162 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"reasonix/internal/installlayout"
+)
+
+func installerVersionNames() []string {
+	names := []string{installlayout.DesktopBinaryName(), installlayout.CLIBinaryName()}
+	if runtime.GOOS == "windows" {
+		names = append(names, installlayout.UpdateHelperBinaryName())
+	}
+	return names
+}
+
+func writeInstallerStaging(t *testing.T, root, label string, includeLauncher bool) string {
+	t.Helper()
+	staging := filepath.Join(root, "versions", ".installer-"+label)
+	if err := os.MkdirAll(staging, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range installerVersionNames() {
+		if err := os.WriteFile(filepath.Join(staging, name), []byte(label+"-"+name), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if includeLauncher {
+		name := installlayout.LauncherBinaryName()
+		if err := os.WriteFile(filepath.Join(staging, name), []byte(label+"-"+name), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return staging
+}
+
+func TestMigrateFlatInstallToVersioned(t *testing.T) {
+	root := t.TempDir()
+	// Flat release unit.
+	for _, name := range installlayout.AllowedVersionMembers() {
+		if err := os.WriteFile(filepath.Join(root, name), []byte("flat-"+name), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// Thin launcher entry must already exist (packaging places it). Use a
+	// non-executable marker so startLauncher fails closed without hanging.
+	_ = os.WriteFile(filepath.Join(root, "reasonix-launcher"), []byte("launcher"), 0o644)
+	_ = os.WriteFile(filepath.Join(root, "reasonix-launcher.exe"), []byte("launcher"), 0o644)
+	_ = os.WriteFile(filepath.Join(root, "Reasonix.exe"), []byte("launcher"), 0o644)
+	// Marker files that must be archived, not deleted silently without record.
+	_ = os.WriteFile(filepath.Join(root, "pending-update.json"), []byte(`{"pending":true}`), 0o644)
+	_ = os.WriteFile(filepath.Join(root, "startup-state.json"), []byte(`{}`), 0o644)
+
+	if err := migrate(root, "v1.20.0"); err != nil {
+		t.Fatal(err)
+	}
+	if !installlayout.HasCurrent(root) {
+		t.Fatal("current.json missing after migration")
+	}
+	ptr, err := installlayout.ReadCurrent(root)
+	if err != nil || ptr.ActiveVersion != "v1.20.0" {
+		t.Fatalf("pointer=%+v err=%v", ptr, err)
+	}
+	// Flat desktop must be cleaned up after successful activation.
+	if _, err := os.Stat(filepath.Join(root, installlayout.DesktopBinaryName())); !os.IsNotExist(err) {
+		t.Fatal("flat desktop should be removed after migration")
+	}
+	// Active desktop lives under versions/.
+	if _, err := installlayout.ActiveDesktopPath(root); err != nil {
+		t.Fatal(err)
+	}
+	// Second run is idempotent cleanup-only.
+	if err := migrate(root, "v1.20.0"); err != nil {
+		t.Fatalf("idempotent re-run: %v", err)
+	}
+	ptr2, err := installlayout.ReadCurrent(root)
+	if err != nil || ptr2.ActiveVersion != "v1.20.0" {
+		t.Fatalf("re-run overwrote active version: %+v", ptr2)
+	}
+}
+
+func TestMigrateRefusesWithoutFlatUnit(t *testing.T) {
+	root := t.TempDir()
+	if err := migrate(root, "v1.20.0"); err == nil {
+		t.Fatal("expected failure without flat desktop")
+	}
+}
+
+func TestMigrateRefusesCorruptCurrentPointerWithoutOverwritingIt(t *testing.T) {
+	root := t.TempDir()
+	corrupt := []byte(`{"schemaVersion":99}`)
+	current := filepath.Join(root, installlayout.CurrentFileName)
+	if err := os.WriteFile(current, corrupt, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range installlayout.AllowedVersionMembers() {
+		if err := os.WriteFile(filepath.Join(root, name), []byte("stale-"+name), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := migrate(root, "v1.20.0"); err == nil {
+		t.Fatal("corrupt current.json was treated as an absent pointer")
+	}
+	got, err := os.ReadFile(current)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != string(corrupt) {
+		t.Fatalf("corrupt pointer was overwritten: %q", got)
+	}
+}
+
+func TestActivateInstallerStagingPublishesVersionAndRootEntries(t *testing.T) {
+	root := t.TempDir()
+	staging := writeInstallerStaging(t, root, "new", true)
+	if err := activateInstallerStaging(root, "v1.20.0", staging); err != nil {
+		t.Fatal(err)
+	}
+	ptr, err := installlayout.ReadCurrent(root)
+	if err != nil || ptr.ActiveVersion != "v1.20.0" {
+		t.Fatalf("pointer=%+v err=%v", ptr, err)
+	}
+	activeDesktop, err := installlayout.ActiveDesktopPath(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, err := os.ReadFile(activeDesktop); err != nil || string(got) != "new-"+installlayout.DesktopBinaryName() {
+		t.Fatalf("active desktop=%q err=%v", got, err)
+	}
+	for _, name := range []string{installlayout.LauncherBinaryName(), installlayout.CLIBinaryName()} {
+		if info, err := os.Lstat(filepath.Join(root, name)); err != nil || !info.Mode().IsRegular() {
+			t.Fatalf("root entry %s missing or invalid: %v", name, err)
+		}
+	}
+	if alias := installlayout.PortableAliasName(); alias != "" {
+		if got, err := os.ReadFile(filepath.Join(root, alias)); err != nil || string(got) != "new-"+installlayout.LauncherBinaryName() {
+			t.Fatalf("portable alias=%q err=%v", got, err)
+		}
+	}
+}
+
+func TestActivateInstallerStagingFailureKeepsPreviousPointer(t *testing.T) {
+	root := t.TempDir()
+	oldStaging := writeInstallerStaging(t, root, "old", true)
+	if err := activateInstallerStaging(root, "v1.19.1", oldStaging); err != nil {
+		t.Fatal(err)
+	}
+	broken := writeInstallerStaging(t, root, "broken", false)
+	if err := activateInstallerStaging(root, "v1.20.0", broken); err == nil {
+		t.Fatal("staging without a launcher was activated")
+	}
+	ptr, err := installlayout.ReadCurrent(root)
+	if err != nil || ptr.ActiveVersion != "v1.19.1" {
+		t.Fatalf("previous pointer changed after failed activation: %+v err=%v", ptr, err)
+	}
+	if err := activateInstallerStaging(root, "v1.20.0", t.TempDir()); err == nil {
+		t.Fatal("staging outside the install root was accepted")
+	}
+}
@@ -3,18 +3,34 @@ package main

 import (
 	"os"
+	"runtime/debug"

 	"reasonix/internal/cli"
+	"reasonix/internal/config"
+	"reasonix/internal/crashreport"

 	// Blank imports wire compile-time built-ins into their registries.
 	_ "reasonix/internal/provider/anthropic"
 	_ "reasonix/internal/provider/openai"
+	_ "reasonix/internal/provider/responses"
 	_ "reasonix/internal/tool/builtin"
 )

 // version is injected at build time via -ldflags "-X main.version=...".
 var version = "dev"

+var runCLI = cli.Run
+
 func main() {
-	os.Exit(cli.Run(os.Args[1:], version))
+	os.Exit(runWithCrashCapture(os.Args[1:], version))
+}
+
+func runWithCrashCapture(args []string, buildVersion string) (exitCode int) {
+	defer func() {
+		if recovered := recover(); recovered != nil {
+			_ = crashreport.CapturePanic(config.ReasonixHomeDir(), buildVersion, recovered, debug.Stack())
+			panic(recovered)
+		}
+	}()
+	return runCLI(args, buildVersion)
 }
@@ -0,0 +1,56 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"reasonix/internal/config"
+	"reasonix/internal/crashreport"
+)
+
+func TestRunWithCrashCaptureRecordsAndReraises(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("REASONIX_HOME", home)
+	previous := runCLI
+	t.Cleanup(func() { runCLI = previous })
+	secret := "private prompt from panic"
+	runCLI = func([]string, string) int { panic(secret) }
+
+	func() {
+		defer func() {
+			if recovered := recover(); recovered != secret {
+				t.Fatalf("reraised panic = %#v", recovered)
+			}
+		}()
+		runWithCrashCapture([]string{"run"}, "v1.20.0")
+	}()
+
+	reports, err := crashreport.List(config.ReasonixHomeDir())
+	if err != nil || len(reports) != 1 {
+		t.Fatalf("captured reports=%d err=%v", len(reports), err)
+	}
+	if got := reports[0].Report.TopFrame; !strings.Contains(got, "main_test.go:") {
+		t.Fatalf("top frame = %q, want panic call site in main_test.go", got)
+	}
+	preview, err := crashreport.Preview(reports[0].Report)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(preview), secret) {
+		t.Fatalf("panic value leaked into report: %s", preview)
+	}
+}
+
+func TestRunWithCrashCapturePassesThroughExitCode(t *testing.T) {
+	previous := runCLI
+	t.Cleanup(func() { runCLI = previous })
+	runCLI = func(args []string, version string) int {
+		if len(args) != 1 || args[0] != "version" || version != "v1.20.0" {
+			t.Fatalf("runCLI args=%v version=%q", args, version)
+		}
+		return 17
+	}
+	if got := runWithCrashCapture([]string{"version"}, "v1.20.0"); got != 17 {
+		t.Fatalf("exit code=%d", got)
+	}
+}
@@ -0,0 +1,389 @@
+package main
+
+import (
+	"crypto/sha256"
+	"encoding/binary"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+const (
+	contractPath = ".signpath/contracts/release-signing.yml"
+	projectSlug  = "DeepSeek-Reasonix"
+	policySlug   = "release-signing"
+	repository   = "https://github.com/esengine/DeepSeek-Reasonix.git"
+)
+
+var expectedBranches = []string{"main-v2"}
+
+type releaseSigningContract struct {
+	Version                 int      `yaml:"version"`
+	ProjectSlug             string   `yaml:"project_slug"`
+	SigningPolicySlug       string   `yaml:"signing_policy_slug"`
+	RepositoryURL           string   `yaml:"repository_url"`
+	AllowedBranchNames      []string `yaml:"allowed_branch_names"`
+	AllowedBuildDefinitions []string `yaml:"allowed_build_definitions"`
+	FingerprintFiles        []string `yaml:"fingerprint_files"`
+}
+
+type workflowInfo struct {
+	externallyTriggered bool
+	directSigning       bool
+	calls               []string
+}
+
+func main() {
+	if len(os.Args) < 2 || len(os.Args) > 3 {
+		fatalf("usage: signpath-contract <validate|fingerprint> [repository-root]")
+	}
+	root := "."
+	if len(os.Args) == 3 {
+		root = os.Args[2]
+	}
+	contract, err := loadAndValidate(root)
+	if err != nil {
+		fatalf("%v", err)
+	}
+
+	switch os.Args[1] {
+	case "validate":
+		fmt.Println("SignPath release signing contract is valid")
+	case "fingerprint":
+		fingerprint, err := contractFingerprint(root, contract)
+		if err != nil {
+			fatalf("fingerprint contract: %v", err)
+		}
+		fmt.Printf("v1:%x\n", fingerprint)
+	default:
+		fatalf("unknown command %q", os.Args[1])
+	}
+}
+
+func fatalf(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, "signpath-contract: "+format+"\n", args...)
+	os.Exit(1)
+}
+
+func loadAndValidate(root string) (releaseSigningContract, error) {
+	data, err := os.ReadFile(filepath.Join(root, filepath.FromSlash(contractPath)))
+	if err != nil {
+		return releaseSigningContract{}, fmt.Errorf("read %s: %w", contractPath, err)
+	}
+	var contract releaseSigningContract
+	if err := yaml.Unmarshal(data, &contract); err != nil {
+		return releaseSigningContract{}, fmt.Errorf("parse %s: %w", contractPath, err)
+	}
+	if err := validateContract(root, contract); err != nil {
+		return releaseSigningContract{}, err
+	}
+	return contract, nil
+}
+
+func validateContract(root string, contract releaseSigningContract) error {
+	if contract.Version != 1 {
+		return fmt.Errorf("%s version is %d, want 1", contractPath, contract.Version)
+	}
+	if contract.ProjectSlug != projectSlug {
+		return fmt.Errorf("project_slug is %q, want %q", contract.ProjectSlug, projectSlug)
+	}
+	if contract.SigningPolicySlug != policySlug {
+		return fmt.Errorf("signing_policy_slug is %q, want %q", contract.SigningPolicySlug, policySlug)
+	}
+	if contract.RepositoryURL != repository {
+		return fmt.Errorf("repository_url is %q, want %q", contract.RepositoryURL, repository)
+	}
+	if err := requireExactSet("allowed_branch_names", contract.AllowedBranchNames, expectedBranches); err != nil {
+		return err
+	}
+	if len(contract.AllowedBuildDefinitions) == 0 {
+		return errors.New("allowed_build_definitions must not be empty")
+	}
+	for _, value := range append(append([]string{}, contract.AllowedBranchNames...), contract.AllowedBuildDefinitions...) {
+		if strings.ContainsAny(value, "*?[") {
+			return fmt.Errorf("SignPath allowlists must not contain wildcard %q", value)
+		}
+	}
+	for _, name := range contract.AllowedBuildDefinitions {
+		if err := validateRepositoryPath(name); err != nil {
+			return fmt.Errorf("invalid allowed build definition %q: %w", name, err)
+		}
+		if !strings.HasPrefix(name, ".github/workflows/") {
+			return fmt.Errorf("allowed build definition %q is outside .github/workflows", name)
+		}
+	}
+	if err := requireUnique("allowed_build_definitions", contract.AllowedBuildDefinitions); err != nil {
+		return err
+	}
+	if len(contract.FingerprintFiles) == 0 {
+		return errors.New("fingerprint_files must not be empty")
+	}
+	seen := make(map[string]bool, len(contract.FingerprintFiles))
+	for _, name := range contract.FingerprintFiles {
+		if err := validateRepositoryPath(name); err != nil {
+			return fmt.Errorf("invalid fingerprint file %q: %w", name, err)
+		}
+		if seen[name] {
+			return fmt.Errorf("duplicate fingerprint file %q", name)
+		}
+		seen[name] = true
+		info, err := os.Stat(filepath.Join(root, filepath.FromSlash(name)))
+		if err != nil {
+			return fmt.Errorf("fingerprint file %q: %w", name, err)
+		}
+		if !info.Mode().IsRegular() {
+			return fmt.Errorf("fingerprint file %q is not a regular file", name)
+		}
+	}
+
+	reachable, err := discoverTopLevelSigningWorkflows(root)
+	if err != nil {
+		return err
+	}
+	if err := requireExactSet("top-level workflows that reach SignPath", reachable, contract.AllowedBuildDefinitions); err != nil {
+		return fmt.Errorf("SignPath build-definition drift: %w", err)
+	}
+	return nil
+}
+
+func requireExactSet(name string, got, want []string) error {
+	gotCopy := append([]string(nil), got...)
+	wantCopy := append([]string(nil), want...)
+	sort.Strings(gotCopy)
+	sort.Strings(wantCopy)
+	if len(gotCopy) != len(wantCopy) {
+		return fmt.Errorf("%s is %v, want %v", name, got, want)
+	}
+	for i := range gotCopy {
+		if gotCopy[i] != wantCopy[i] {
+			return fmt.Errorf("%s is %v, want %v", name, got, want)
+		}
+		if i > 0 && gotCopy[i] == gotCopy[i-1] {
+			return fmt.Errorf("%s contains duplicate %q", name, gotCopy[i])
+		}
+	}
+	return nil
+}
+
+func requireUnique(name string, values []string) error {
+	seen := make(map[string]bool, len(values))
+	for _, value := range values {
+		if seen[value] {
+			return fmt.Errorf("%s contains duplicate %q", name, value)
+		}
+		seen[value] = true
+	}
+	return nil
+}
+
+func validateRepositoryPath(name string) error {
+	if name == "" || filepath.IsAbs(filepath.FromSlash(name)) {
+		return errors.New("path must be non-empty and repository-relative")
+	}
+	clean := filepath.Clean(filepath.FromSlash(name))
+	if clean == "." || clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
+		return errors.New("path escapes the repository")
+	}
+	if filepath.ToSlash(clean) != name {
+		return errors.New("path must be normalized with forward slashes")
+	}
+	return nil
+}
+
+func discoverTopLevelSigningWorkflows(root string) ([]string, error) {
+	paths, err := filepath.Glob(filepath.Join(root, ".github", "workflows", "*.y*ml"))
+	if err != nil {
+		return nil, fmt.Errorf("list workflows: %w", err)
+	}
+	workflows := make(map[string]workflowInfo, len(paths))
+	for _, path := range paths {
+		data, err := os.ReadFile(path)
+		if err != nil {
+			return nil, fmt.Errorf("read workflow %s: %w", path, err)
+		}
+		name, err := filepath.Rel(root, path)
+		if err != nil {
+			return nil, err
+		}
+		name = filepath.ToSlash(name)
+		info, err := parseWorkflow(data)
+		if err != nil {
+			return nil, fmt.Errorf("parse workflow %s: %w", name, err)
+		}
+		workflows[name] = info
+	}
+
+	state := make(map[string]uint8, len(workflows))
+	memo := make(map[string]bool, len(workflows))
+	var reachesSigning func(string) (bool, error)
+	reachesSigning = func(name string) (bool, error) {
+		if state[name] == 2 {
+			return memo[name], nil
+		}
+		if state[name] == 1 {
+			return false, fmt.Errorf("reusable workflow cycle includes %s", name)
+		}
+		info, ok := workflows[name]
+		if !ok {
+			return false, fmt.Errorf("workflow calls missing local workflow %s", name)
+		}
+		state[name] = 1
+		reachable := info.directSigning
+		for _, called := range info.calls {
+			calledReachable, err := reachesSigning(called)
+			if err != nil {
+				return false, err
+			}
+			reachable = reachable || calledReachable
+		}
+		state[name] = 2
+		memo[name] = reachable
+		return reachable, nil
+	}
+
+	var result []string
+	for name, info := range workflows {
+		if !info.externallyTriggered {
+			continue
+		}
+		reachable, err := reachesSigning(name)
+		if err != nil {
+			return nil, err
+		}
+		if reachable {
+			result = append(result, name)
+		}
+	}
+	sort.Strings(result)
+	return result, nil
+}
+
+func parseWorkflow(data []byte) (workflowInfo, error) {
+	var document yaml.Node
+	if err := yaml.Unmarshal(data, &document); err != nil {
+		return workflowInfo{}, err
+	}
+	if len(document.Content) != 1 || document.Content[0].Kind != yaml.MappingNode {
+		return workflowInfo{}, errors.New("workflow root must be a mapping")
+	}
+	root := document.Content[0]
+	on := mappingValue(root, "on")
+	jobs := mappingValue(root, "jobs")
+	if on == nil || jobs == nil || jobs.Kind != yaml.MappingNode {
+		return workflowInfo{}, errors.New("workflow must contain on and jobs mappings")
+	}
+
+	info := workflowInfo{externallyTriggered: hasExternalTrigger(on)}
+	for i := 1; i < len(jobs.Content); i += 2 {
+		job := jobs.Content[i]
+		if job.Kind != yaml.MappingNode {
+			continue
+		}
+		if uses := mappingScalar(job, "uses"); strings.HasPrefix(uses, "./.github/workflows/") {
+			info.calls = append(info.calls, strings.TrimPrefix(uses, "./"))
+		}
+		if nodeContains(job, "secrets.SIGNPATH_API_TOKEN") {
+			info.directSigning = true
+		}
+		steps := mappingValue(job, "steps")
+		if steps == nil || steps.Kind != yaml.SequenceNode {
+			continue
+		}
+		for _, step := range steps.Content {
+			if step.Kind != yaml.MappingNode {
+				continue
+			}
+			if strings.HasPrefix(mappingScalar(step, "uses"), "signpath/github-action-submit-signing-request@") {
+				info.directSigning = true
+			}
+		}
+	}
+	sort.Strings(info.calls)
+	return info, nil
+}
+
+func nodeContains(node *yaml.Node, text string) bool {
+	if node == nil {
+		return false
+	}
+	if node.Kind == yaml.ScalarNode && strings.Contains(node.Value, text) {
+		return true
+	}
+	for _, child := range node.Content {
+		if nodeContains(child, text) {
+			return true
+		}
+	}
+	return false
+}
+
+func hasExternalTrigger(node *yaml.Node) bool {
+	switch node.Kind {
+	case yaml.ScalarNode:
+		return node.Value != "workflow_call"
+	case yaml.SequenceNode:
+		for _, child := range node.Content {
+			if child.Value != "workflow_call" {
+				return true
+			}
+		}
+	case yaml.MappingNode:
+		for i := 0; i < len(node.Content); i += 2 {
+			if node.Content[i].Value != "workflow_call" {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func mappingValue(node *yaml.Node, key string) *yaml.Node {
+	if node == nil || node.Kind != yaml.MappingNode {
+		return nil
+	}
+	for i := 0; i < len(node.Content); i += 2 {
+		if node.Content[i].Value == key {
+			return node.Content[i+1]
+		}
+	}
+	return nil
+}
+
+func mappingScalar(node *yaml.Node, key string) string {
+	value := mappingValue(node, key)
+	if value == nil || value.Kind != yaml.ScalarNode {
+		return ""
+	}
+	return value.Value
+}
+
+func contractFingerprint(root string, contract releaseSigningContract) ([sha256.Size]byte, error) {
+	names := append([]string{contractPath}, contract.FingerprintFiles...)
+	sort.Strings(names)
+	hash := sha256.New()
+	_, _ = io.WriteString(hash, "reasonix-signpath-release-contract-v1\x00")
+	for _, name := range names {
+		data, err := os.ReadFile(filepath.Join(root, filepath.FromSlash(name)))
+		if err != nil {
+			return [sha256.Size]byte{}, fmt.Errorf("read %s: %w", name, err)
+		}
+		writeLengthPrefixed(hash, []byte(name))
+		writeLengthPrefixed(hash, data)
+	}
+	var result [sha256.Size]byte
+	copy(result[:], hash.Sum(nil))
+	return result, nil
+}
+
+func writeLengthPrefixed(writer io.Writer, data []byte) {
+	var length [8]byte
+	binary.BigEndian.PutUint64(length[:], uint64(len(data)))
+	_, _ = writer.Write(length[:])
+	_, _ = writer.Write(data)
+}
@@ -0,0 +1,68 @@
+package main
+
+import (
+	"fmt"
+	"reflect"
+	"testing"
+)
+
+func TestRepositoryReleaseSigningContract(t *testing.T) {
+	root := "../.."
+	contract, err := loadAndValidate(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	fingerprint, err := contractFingerprint(root, contract)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := fmt.Sprintf("%x", fingerprint); len(got) != 64 {
+		t.Fatalf("fingerprint length = %d, want 64", len(got))
+	}
+}
+
+func TestTopLevelSignPathWorkflowCallGraph(t *testing.T) {
+	got, err := discoverTopLevelSigningWorkflows("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{
+		".github/workflows/release-desktop.yml",
+		".github/workflows/release-stable.yml",
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("top-level workflows that reach SignPath = %v, want %v", got, want)
+	}
+}
+
+func TestReleaseSigningContractRejectsWildcards(t *testing.T) {
+	contract, err := loadAndValidate("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	contract.AllowedBuildDefinitions = []string{".github/workflows/release-*.yml"}
+	if err := validateContract("../..", contract); err == nil {
+		t.Fatal("wildcard build definition unexpectedly passed validation")
+	}
+}
+
+func TestWorkflowUsingSignPathTokenIsSigningEntryPoint(t *testing.T) {
+	workflow := []byte(`
+on: workflow_dispatch
+jobs:
+  sign:
+    runs-on: windows-latest
+    steps:
+      - shell: pwsh
+        env:
+          SIGNPATH_API_TOKEN: ${{ secrets.SIGNPATH_API_TOKEN }}
+        run: ./submit-signing-request.ps1
+`)
+	info, err := parseWorkflow(workflow)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !info.externallyTriggered || !info.directSigning {
+		t.Fatalf("token-backed workflow was not classified as a signing entry point: %+v", info)
+	}
+}
@@ -20,6 +20,7 @@
 /build/darwin/*
 !/build/darwin/entitlements.plist
 !/build/darwin/icon.icns
+!/build/darwin/appicon.svg

 # Commit the hand-written Linux .deb packaging inputs and app icon assets.
 # `wails build` does not generate these, so they must live in git. The .deb is built
@@ -28,6 +29,7 @@
 /build/linux/*
 !/build/linux/nfpm.yaml
 !/build/linux/reasonix.desktop
+!/build/linux/io.reasonix.desktop.update.policy
 !/build/linux/icons
 !/build/linux/icons/**

@@ -137,9 +137,19 @@ The gateway resolves only the desktop `desktop-v*` release line and never uses
 GitHub's repository-wide `/releases/latest` shortcut, so updater behavior does
 not depend on homepage badge semantics. Self-update behavior by platform:

- **Linux / Windows** — download, verify the minisign signature, then update in
-  place: Linux replaces the binary and relaunches; Windows runs the per-user NSIS
-  installer (no admin rights needed).
+- **Linux portable (`.tar.gz`)** — download, verify the minisign signature, replace
+  the binaries in the install directory, and relaunch through Guard. No elevation.
+- **Linux Debian/Ubuntu (`.deb`)** — download the signed `.deb`, request administrator
+  authorization via Polkit (`pkexec`), re-verify and install with `apt-get
+  --only-upgrade`, then relaunch through Guard. The first build that ships the
+  update helper and Polkit policy is a one-time bootstrap: existing `.deb` users
+  should overwrite-install once with
+  `sudo apt install ./Reasonix-linux-amd64.deb` (no uninstall required). After
+  that, in-app authorized updates work. If Polkit/`pkexec` is unavailable, use
+  the same manual command. Failed installs leave the running app intact so you
+  can retry; successful installs are managed by apt/dpkg and are not auto-downgraded.
+- **Windows** — download, verify the minisign signature, then run the per-user
+  NSIS installer (no admin rights needed).
 - **macOS** — *not* self-updating yet. The build is unsigned/un-notarized, so an
  in-place swap would be blocked by Gatekeeper; the banner links to the download
  page for a manual update instead.
@@ -272,16 +282,20 @@ desktop/

 The desktop app sends one anonymous ping per launch to `crash.reasonix.io`:
 a random install id (generated locally, tied to nothing), app version, OS,
-arch, and OS version. It exists solely to count active installs. It never
-includes conversations, API keys, file contents, or paths.
+arch, and OS version. When the previous process ended abnormally, the next
+normal launch may also send a bounded native diagnostic (lifecycle phase,
+symbolized stack, WebView2/window failure kind, and coarse device facts).
+Panic values are removed and paths/secrets are scrubbed before the report is
+queued. It never includes conversations, API keys, or file contents.

 Opt out any time: Settings > Updates > "Anonymous usage ping", or set
 `telemetry = false` under `[desktop]` in the global config. Dev builds
-never ping. Crash and performance-pressure reports are separate and only
-ever sent when the user clicks "Send report" on the diagnostic UI.
+never ping or upload queued native diagnostics. Frontend crash and
+performance-pressure reports remain separate and are sent only when the user
+clicks "Send report" on the diagnostic UI.

 Aggregate quality metrics are also enabled by default and can be disabled from
 Settings > Updates > "Share aggregate quality metrics", or by setting
 `metrics = false` under `[desktop]`. These metrics are anonymous signal/bucket
-counts and preference buckets; they never include conversations, prompts, keys,
-paths, base URLs, or file contents.
+counts, lifecycle/window failure buckets, and preference buckets; they never
+include conversations, prompts, keys, paths, base URLs, or file contents.
@@ -28,6 +28,7 @@ import (
 	"reasonix/internal/control"
 	"reasonix/internal/event"
 	"reasonix/internal/evidence"
+	"reasonix/internal/instruction"
 	"reasonix/internal/jobs"
 	"reasonix/internal/mcplaunch"
 	"reasonix/internal/memory"
@@ -473,7 +474,9 @@ func TestMetaForTabIncludesWorkspaceContext(t *testing.T) {
 	if strings.Contains(string(raw), "sandboxPath") || strings.Contains(string(raw), configuredSandboxRoot) {
 		t.Fatalf("meta should not expose configured sandbox root as sandboxPath: %s", raw)
 	}
-	deadline := time.Now().Add(time.Second)
+	// The first git process launch can be noticeably slower on Windows runners
+	// while MetaForTab intentionally keeps the caller path non-blocking.
+	deadline := time.Now().Add(5 * time.Second)
 	for {
 		if got = app.MetaForTab("tab-1"); got.GitBranch == "feature/meta" {
 			break
@@ -596,18 +599,78 @@ func TestMemoryViewReturnsNonNilArraysBeforeStartup(t *testing.T) {
 	isolateDesktopUserDirs(t)

 	view := NewApp().Memory()
-	if view.Docs == nil || view.Facts == nil || view.Archives == nil || view.Scopes == nil {
+	if view.Docs == nil || view.Facts == nil || view.Archives == nil || view.Scopes == nil || view.InstructionDiagnostics == nil || view.Conflicts == nil || view.LastRecall.Hits == nil {
 		t.Fatalf("Memory() arrays must be non-nil before startup: %+v", view)
 	}
 	raw, err := json.Marshal(view)
 	if err != nil {
 		t.Fatalf("marshal Memory(): %v", err)
 	}
-	for _, bad := range []string{`"docs":null`, `"facts":null`, `"archives":null`, `"scopes":null`} {
+	for _, bad := range []string{`"docs":null`, `"facts":null`, `"archives":null`, `"scopes":null`, `"instructionDiagnostics":null`, `"conflicts":null`, `"hits":null`} {
 		if strings.Contains(string(raw), bad) {
 			t.Fatalf("Memory() JSON contains %s; frontend expects []: %s", bad, raw)
 		}
 	}
+	if revisions := NewApp().MemoryRevisions("missing"); revisions == nil {
+		t.Fatal("MemoryRevisions must return [] before startup, not nil")
+	}
+}
+
+func TestMemoryViewIncludesRecallFreshnessAndOverrides(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	root := t.TempDir()
+	store := memory.Store{Dir: filepath.Join(root, "project"), GlobalDir: filepath.Join(root, "global")}
+	if _, err := (memory.Store{Dir: store.GlobalDir}).Save(memory.Memory{
+		Name: "deploy-target", Title: "Deploy target", Description: "legacy deployment target", Scope: memory.FactScopeGlobal, Type: memory.TypeProject, Body: "Deploy payments to the legacy cluster.",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := (memory.Store{Dir: store.Dir}).Save(memory.Memory{
+		Name: "deploy-target", Title: "Deploy target", Description: "current deployment target", Scope: memory.FactScopeProject, Type: memory.TypeProject, Body: "Deploy payments to the green cluster.",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	ctrl := control.New(control.Options{Memory: &memory.Set{Store: store}})
+	ctrl.Compose("deploy payments target cluster")
+	app := NewApp()
+	app.setTestCtrl(ctrl, "test-model")
+
+	view := app.Memory()
+	if len(view.Facts) != 2 || view.Facts[0].Freshness == "" || view.Facts[1].Freshness == "" {
+		t.Fatalf("facts with freshness = %+v", view.Facts)
+	}
+	if len(view.Conflicts) != 1 || view.Conflicts[0].Resolution != "project_over_global" {
+		t.Fatalf("conflicts = %+v", view.Conflicts)
+	}
+	if view.LastRecall.Query != "deploy payments target cluster" || len(view.LastRecall.Hits) != 1 || view.LastRecall.Hits[0].Scope != "project" {
+		t.Fatalf("last recall = %+v", view.LastRecall)
+	}
+}
+
+func TestMemoryRevisionAPIRestoresSelectedRevision(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	store := memory.Store{Dir: t.TempDir()}
+	first, err := store.SaveWithOptions(memory.Memory{Name: "fact", Description: "one", Body: "v1"}, memory.SaveOptions{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := store.SaveWithOptions(memory.Memory{ID: first.Memory.ID, Name: "fact", Description: "two", Body: "v2"}, memory.SaveOptions{}); err != nil {
+		t.Fatal(err)
+	}
+	app := NewApp()
+	app.setTestCtrl(control.New(control.Options{Memory: &memory.Set{Store: store}}), "test-model")
+
+	revisions := app.MemoryRevisions(first.Memory.ID)
+	if len(revisions) != 1 || revisions[0].Revision != 1 {
+		t.Fatalf("revisions = %+v", revisions)
+	}
+	restored, err := app.RestoreMemoryRevision(first.Memory.ID, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if restored.Revision != 3 || restored.Body != "v1" {
+		t.Fatalf("restored = %+v", restored)
+	}
 }

 func TestMemoryViewIncludesActiveAndArchivedFacts(t *testing.T) {
@@ -638,10 +701,12 @@ func TestMemoryViewIncludesActiveAndArchivedFacts(t *testing.T) {

 	app := NewApp()
 	app.setTestCtrl(control.New(control.Options{Memory: &memory.Set{
-		Docs:    []memory.Source{{Path: filepath.Join(cwd, "AGENTS.md"), Scope: memory.ScopeProject, Body: "Project instructions"}},
-		Store:   store,
-		CWD:     cwd,
-		UserDir: userDir,
+		Docs: []memory.Source{{
+			Path: filepath.Join(cwd, "AGENTS.md"), Scope: memory.ScopeProject, Directory: cwd,
+			Body: "Project instructions", Imports: []instruction.Import{{Path: filepath.Join(cwd, "shared.md"), SourcePath: filepath.Join(cwd, "AGENTS.md")}},
+		}},
+		InstructionDiagnostics: []instruction.Diagnostic{{Code: "import_cycle", Path: "shared.md", SourcePath: filepath.Join(cwd, "AGENTS.md"), Line: 3, Message: "cycle"}},
+		Store:                  store, CWD: cwd, UserDir: userDir,
 	}}), "test-model")

 	view := app.Memory()
@@ -651,18 +716,57 @@ func TestMemoryViewIncludesActiveAndArchivedFacts(t *testing.T) {
 	if len(view.Docs) != 1 || view.Docs[0].Scope != "project" || !strings.Contains(view.Docs[0].Body, "Project instructions") {
 		t.Fatalf("Memory() docs = %+v", view.Docs)
 	}
-	if len(view.Facts) != 1 || view.Facts[0].Name != "active-fact" || view.Facts[0].Type != "project" {
+	if view.Docs[0].Directory != cwd || len(view.Docs[0].Imports) != 1 || len(view.InstructionDiagnostics) != 1 || view.InstructionDiagnostics[0].Code != "import_cycle" {
+		t.Fatalf("Memory() instruction provenance = docs %+v diagnostics %+v", view.Docs, view.InstructionDiagnostics)
+	}
+	if len(view.Facts) != 1 || view.Facts[0].Name != "active-fact" || view.Facts[0].Type != "project" || view.Facts[0].Scope != "project" {
 		t.Fatalf("Memory() active facts = %+v", view.Facts)
 	}
-	if len(view.Archives) != 1 || view.Archives[0].Name != "archived-fact" || view.Archives[0].Type != "feedback" ||
+	if view.Facts[0].ID == "" || view.Facts[0].Revision != 1 || view.Facts[0].CreatedAt == "" || view.Facts[0].UpdatedAt == "" {
+		t.Fatalf("Memory() active fact metadata = %+v", view.Facts[0])
+	}
+	if len(view.Archives) != 1 || view.Archives[0].Name != "archived-fact" || view.Archives[0].Type != "feedback" || view.Archives[0].Scope != "project" ||
 		view.Archives[0].Path == "" || view.Archives[0].ArchivedAt == "" {
 		t.Fatalf("Memory() archived facts = %+v", view.Archives)
 	}
+	if view.Archives[0].ID == "" || view.Archives[0].Revision != 1 || view.Archives[0].CreatedAt == "" || view.Archives[0].UpdatedAt == "" {
+		t.Fatalf("Memory() archived fact metadata = %+v", view.Archives[0])
+	}
 	if len(view.Scopes) != 3 {
 		t.Fatalf("Memory() scopes = %+v, want user/project/local", view.Scopes)
 	}
 }

+func TestRestoreArchivedMemoryRecoversFactForCurrentSession(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	userDir := t.TempDir()
+	cwd := t.TempDir()
+	store := memory.StoreFor(userDir, cwd)
+	first, err := store.SaveWithOptions(memory.Memory{
+		Name: "restorable-fact", Description: "recover me", Body: "Recovered guidance.",
+	}, memory.SaveOptions{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	archivePath, err := store.Archive(first.Memory.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	app := NewApp()
+	app.setTestCtrl(control.New(control.Options{Memory: &memory.Set{Store: store, CWD: cwd, UserDir: userDir}}), "test-model")
+	if _, err := app.RestoreArchivedMemory(archivePath); err != nil {
+		t.Fatal(err)
+	}
+	view := app.Memory()
+	if len(view.Facts) != 1 || view.Facts[0].ID != first.Memory.ID || view.Facts[0].Revision != 2 {
+		t.Fatalf("restored memory view = %+v", view)
+	}
+	if len(view.Archives) != 0 {
+		t.Fatalf("restored archive remained visible: %+v", view.Archives)
+	}
+}
+
 func TestBeforeCloseAllowsSystemQuitWhenBackgroundCloseEnabled(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	consumeSystemQuitRequested()
@@ -942,6 +1046,9 @@ func TestDesktopStartupSettingsUsesUserDesktopPreferencesWithoutFullSettingsPayl
 	if err := userCfg.SetDesktopCheckUpdates(false); err != nil {
 		t.Fatalf("set desktop check updates: %v", err)
 	}
+	if err := userCfg.SetDesktopUpdateChannel("preview"); err != nil {
+		t.Fatalf("set desktop update channel: %v", err)
+	}
 	userCfg.Bot.Enabled = true
 	userCfg.Bot.Allowlist.Enabled = true
 	userCfg.Bot.Allowlist.QQUsers = []string{"alice"}
@@ -950,7 +1057,7 @@ func TestDesktopStartupSettingsUsesUserDesktopPreferencesWithoutFullSettingsPayl
 	}

 	got := NewApp().DesktopStartupSettings()
-	if got.DesktopLanguage != "en" || got.DesktopLayoutStyle != "classic" || got.DesktopTheme != "dark" || got.DesktopThemeStyle != "graphite" || got.DisplayMode != "standard" || got.StatusBarStyle != "icon" || got.CheckUpdates {
+	if got.DesktopLanguage != "en" || got.DesktopLayoutStyle != "classic" || got.DesktopTheme != "dark" || got.DesktopThemeStyle != "graphite" || got.DisplayMode != "standard" || got.StatusBarStyle != "icon" || got.CheckUpdates || got.UpdateChannel != "stable" {
 		t.Fatalf("DesktopStartupSettings desktop prefs = %+v, want user-level startup prefs", got)
 	}
 	if want := []string{"workspace", "git_branch", "model"}; !reflect.DeepEqual(got.StatusBarItems, want) {
@@ -1583,7 +1690,7 @@ func TestSettingsMarksPresetWithChangedCoreConfigAsModified(t *testing.T) {
 	}
 }

-func TestSettingsMigratesLegacyStepFunPresetBaseURLs(t *testing.T) {
+func TestSettingsPreservesStepFunRegionalPresetBaseURLs(t *testing.T) {
 	isolateDesktopUserDirs(t)

 	cfg := config.Default()
@@ -1608,25 +1715,25 @@ func TestSettingsMigratesLegacyStepFunPresetBaseURLs(t *testing.T) {
 	view := NewApp().Settings()
 	for _, id := range []string{"stepfun", "stepfun-anthropic"} {
 		presetView := providerPresetViewByID(t, view, id)
-		if !presetView.Added || presetView.Status != providerPresetStatusInstalled {
-			t.Fatalf("%s preset view = %+v, want installed after migration", id, presetView)
+		if !presetView.Added || presetView.Status != providerPresetStatusInstalledModified {
+			t.Fatalf("%s preset view = %+v, want installed-modified for a preserved regional endpoint", id, presetView)
 		}
 	}

-	migrated := config.LoadForEdit(config.UserConfigPath())
-	stepfunEntryView, ok := migrated.Provider("stepfun")
+	loaded := config.LoadForEdit(config.UserConfigPath())
+	stepfunEntryView, ok := loaded.Provider("stepfun")
 	if !ok {
-		t.Fatal("stepfun provider missing after migration")
+		t.Fatal("stepfun provider missing after load")
 	}
-	if got := stepfunEntryView.BaseURL; got != "https://api.stepfun.com/step_plan/v1" {
-		t.Fatalf("stepfun base_url = %q, want official URL", got)
+	if got := stepfunEntryView.BaseURL; got != "https://api.stepfun.ai/step_plan/v1" {
+		t.Fatalf("stepfun base_url = %q, want preserved regional URL", got)
 	}
-	stepfunAnthropicEntryView, ok := migrated.Provider("stepfun-anthropic")
+	stepfunAnthropicEntryView, ok := loaded.Provider("stepfun-anthropic")
 	if !ok {
-		t.Fatal("stepfun-anthropic provider missing after migration")
+		t.Fatal("stepfun-anthropic provider missing after load")
 	}
-	if got := stepfunAnthropicEntryView.BaseURL; got != "https://api.stepfun.com/step_plan" {
-		t.Fatalf("stepfun-anthropic base_url = %q, want official URL", got)
+	if got := stepfunAnthropicEntryView.BaseURL; got != "https://api.stepfun.ai/step_plan" {
+		t.Fatalf("stepfun-anthropic base_url = %q, want preserved regional URL", got)
 	}
 }

@@ -2844,6 +2951,21 @@ func TestModelsForTabOnlyListsProviderAccessWhenConfigured(t *testing.T) {
 	}
 }

+func TestModelsForTabListsNothingWhenProviderAccessExplicitlyEmpty(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	setDesktopTestCredential(t, "DEEPSEEK_API_KEY", "sk-test")
+
+	cfg := config.Default()
+	cfg.Desktop.ProviderAccess = []string{}
+	if err := cfg.SaveTo(config.UserConfigPath()); err != nil {
+		t.Fatalf("save config: %v", err)
+	}
+
+	if models := NewApp().Models(); len(models) != 0 {
+		t.Fatalf("Models() = %+v, want no models when provider access is explicitly empty", models)
+	}
+}
+
 func TestModelsForTabListsCustomMultiModelProviderWithoutMetadata(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	setDesktopTestCredential(t, "LOCAL_API_KEY", "sk-test")
@@ -3045,7 +3167,7 @@ func TestSetModelForTabRejectsProviderOutsideAccess(t *testing.T) {
 	}
 }

-func TestSetModelForTabRefreshesCarriedSystemPrompt(t *testing.T) {
+func TestSetModelForTabRefreshesCarriedSystemPromptWithoutChangingDefaults(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	setDesktopTestCredential(t, "OLD_MODEL_KEY", "sk-test")
 	setDesktopTestCredential(t, "NEW_MODEL_KEY", "sk-test")
@@ -3089,9 +3211,18 @@ func TestSetModelForTabRefreshesCarriedSystemPrompt(t *testing.T) {
 		sink:        &tabEventSink{tabID: "tab_a", app: app},
 		disabledMCP: map[string]ServerView{},
 	}
-	app.tabs = map[string]*WorkspaceTab{tab.ID: tab}
-	app.tabOrder = []string{tab.ID}
+	sibling := &WorkspaceTab{
+		ID:          "tab_b",
+		Scope:       "global",
+		Ready:       true,
+		model:       "old/old-model",
+		disabledMCP: map[string]ServerView{},
+	}
+	app.tabs = map[string]*WorkspaceTab{tab.ID: tab, sibling.ID: sibling}
+	app.tabOrder = []string{tab.ID, sibling.ID}
 	app.activeTabID = tab.ID
+	var switchTiming modelSwitchTiming
+	app.modelSwitchTimingHook = func(timing modelSwitchTiming) { switchTiming = timing }
 	t.Cleanup(func() {
 		if tab.Ctrl != nil {
 			tab.Ctrl.Close()
@@ -3114,6 +3245,18 @@ func TestSetModelForTabRefreshesCarriedSystemPrompt(t *testing.T) {
 	if history[1].Role != provider.RoleUser || history[1].Content != "hello" {
 		t.Fatalf("carried user message changed: %+v", history[1])
 	}
+	if got := config.LoadForEdit(config.UserConfigPath()).DefaultModel; got != "old/old-model" {
+		t.Fatalf("default model after session switch = %q, want old/old-model", got)
+	}
+	if sibling.model != "old/old-model" {
+		t.Fatalf("sibling tab model after session switch = %q, want old/old-model", sibling.model)
+	}
+	if switchTiming.Outcome != "ok" || switchTiming.Total <= 0 {
+		t.Fatalf("model switch timing = %+v, want successful non-zero observation", switchTiming)
+	}
+	if switchTiming.Build <= 0 || switchTiming.LeaseAndResume <= 0 || switchTiming.SwapAndPersist <= 0 {
+		t.Fatalf("model switch stage timing incomplete: %+v", switchTiming)
+	}
 }

 // TestSetModelForTabRestoresSessionAuthorizations pins the fix for a model
@@ -3704,10 +3847,8 @@ func newStaleWorkspaceBindingFixtureWithLayout(t *testing.T, suffix, layoutStyle
 	isolateDesktopUserDirs(t)
 	setDesktopTestCredential(t, "TEST_MODEL_KEY", "sk-test")

-	// Steers and idle-steer fallbacks start real provider turns (they are no
-	// longer command-interpreted), so the fixture's provider must complete
-	// instantly instead of pointing at an unreachable host — otherwise every
-	// steer leaves the controller running for the rest of the test.
+	// Submitted turns use a real provider, so the fixture must complete them
+	// instantly instead of pointing at an unreachable host.
 	providerStub := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		w.Header().Set("Content-Type", "text/event-stream")
 		w.WriteHeader(http.StatusOK)
@@ -3916,16 +4057,13 @@ func TestDescribeSessionBindingWorkspaceKeepsWindowsPathReadable(t *testing.T) {
 	}
 }

-func TestSteerForTabReconcilesStaleWorkspaceBeforeIdleFallback(t *testing.T) {
+func TestSteerForTabReconcilesStaleWorkspaceBeforeRejectingIdleGuidance(t *testing.T) {
 	f := newStaleWorkspaceBindingFixture(t, "steer_idle_fallback")

-	// The idle fallback submits the steer text verbatim as a provider turn
-	// (steers are never command-interpreted); the fixture's provider stub
-	// completes it instantly.
-	if err := f.app.SteerForTab(f.tab.ID, "steer guidance"); err != nil {
-		t.Fatalf("SteerForTab: %v", err)
+	err := f.app.SteerForTab(f.tab.ID, "steer guidance")
+	if err == nil || !strings.Contains(err.Error(), "remain queued") {
+		t.Fatalf("SteerForTab error = %v, want explicit rejected-guidance result", err)
 	}
-	waitNotRunning(t, f.tab.Ctrl)
 	assertTabRebuiltToPinnedWorkspace(t, f)
 }

@@ -4099,12 +4237,12 @@ func runQuickClickWorkspaceReconcileTest(t *testing.T, layoutStyle string) {
 	wg.Wait()
 	close(errs)
 	for err := range errs {
-		// The steer action holds a real provider turn now, so racing quick
-		// clicks may legitimately observe a busy controller. This test
-		// asserts workspace-rebuild serialization, not that every
-		// concurrent action wins the turn.
+		// Racing quick clicks may legitimately observe a busy controller or an
+		// already-ended steer target. This test asserts workspace-rebuild
+		// serialization, not that every concurrent action wins admission.
 		if strings.Contains(err.Error(), "turn already running") ||
-			strings.Contains(err.Error(), "cannot compact while a turn is running") {
+			strings.Contains(err.Error(), "cannot compact while a turn is running") ||
+			strings.Contains(err.Error(), "remain queued") {
 			continue
 		}
 		t.Error(err)
@@ -4870,6 +5008,32 @@ func TestConnectKeyRestoresDeepSeekProviderAccess(t *testing.T) {
 	}
 }

+func TestBalanceForTabUsesDesktopPricingCurrency(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	cfg := config.Default()
+	cfg.Desktop.Currency = "USD"
+	if err := cfg.SaveTo(config.UserConfigPath()); err != nil {
+		t.Fatalf("save USD desktop currency: %v", err)
+	}
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"is_available":true,"balance_infos":[{"currency":"CNY","total_balance":"70.16"},{"currency":"USD","total_balance":"9.82"}]}`)
+	}))
+	defer srv.Close()
+
+	app := NewApp()
+	app.ctx = context.Background()
+	ctrl := control.New(control.Options{BalanceURL: srv.URL, BalanceClient: srv.Client()})
+	t.Cleanup(ctrl.Close)
+	app.setTestCtrl(ctrl, "deepseek/deepseek-v4-flash")
+
+	got := app.BalanceForTab("test")
+	if !got.Available || got.Display != "$9.82" || got.Err != "" {
+		t.Fatalf("USD desktop balance = %+v, want available $9.82", got)
+	}
+}
+
 func TestConnectKeyRebuildLeaseHeldKeepsCurrentController(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	t.Setenv(onboardingKeyEnv, "")
@@ -5261,6 +5425,10 @@ func TestSetTokenModeLeaseHeldKeepsCurrentController(t *testing.T) {
 	if got := currentTabTokenMode(tab); got != "full" {
 		t.Fatalf("token mode = %q, want full", got)
 	}
+	meta := app.MetaForTab(tab.ID)
+	if !meta.Ready || meta.Runtime.Phase != sessionRuntimeReady {
+		t.Fatalf("failed switch disabled current runtime: ready=%v phase=%q", meta.Ready, meta.Runtime.Phase)
+	}
 }

 func TestSetTokenModeMigratesStaleOfficialDeepSeekTabModel(t *testing.T) {
@@ -5454,6 +5622,17 @@ func TestSetTokenModeRejectsRunningTurn(t *testing.T) {

 func TestSetTokenModeRejectsBackgroundJobs(t *testing.T) {
 	isolateDesktopUserDirs(t)
+	setDesktopTestCredential(t, "OLD_MODEL_KEY", "sk-test")
+
+	cfg := config.Default()
+	cfg.DefaultModel = "old/old-model"
+	cfg.Desktop.ProviderAccess = []string{"old"}
+	cfg.Providers = []config.ProviderEntry{
+		{Name: "old", Kind: "openai", BaseURL: "https://example.invalid/v1", Model: "old-model", APIKeyEnv: "OLD_MODEL_KEY"},
+	}
+	if err := cfg.SaveTo(config.UserConfigPath()); err != nil {
+		t.Fatalf("save config: %v", err)
+	}

 	dir := config.SessionDir()
 	if err := os.MkdirAll(dir, 0o755); err != nil {
@@ -5462,12 +5641,17 @@ func TestSetTokenModeRejectsBackgroundJobs(t *testing.T) {
 	path := filepath.Join(dir, "jobs.jsonl")
 	jm := jobs.NewManager(event.Discard)
 	ctrl := control.New(control.Options{SessionDir: dir, SessionPath: path, Label: "test", Jobs: jm})
-	defer ctrl.Close()
 	app := NewApp()
-	app.setTestCtrl(ctrl, "")
+	app.ctx = context.Background()
+	app.setTestCtrl(ctrl, "old/old-model")
+	t.Cleanup(func() {
+		if current := app.activeCtrl(); current != nil {
+			current.Close()
+		}
+	})

 	release := make(chan struct{})
-	jm.StartForSession(agent.BranchID(path), "bash", "long job", func(ctx context.Context, _ io.Writer) (string, error) {
+	job := jm.StartForSession(agent.BranchID(path), "bash", "long job", func(ctx context.Context, _ io.Writer) (string, error) {
 		select {
 		case <-ctx.Done():
 			return "", ctx.Err()
@@ -5475,11 +5659,21 @@ func TestSetTokenModeRejectsBackgroundJobs(t *testing.T) {
 			return "", nil
 		}
 	})
-	defer close(release)
+	t.Cleanup(func() { close(release) })

 	err := app.SetTokenMode("economy")
-	if err == nil || !strings.Contains(err.Error(), "stop background jobs") {
-		t.Fatalf("SetTokenMode with background job error = %v, want background-job guard", err)
+	if err == nil || !strings.Contains(err.Error(), "background_jobs=1") {
+		t.Fatalf("SetTokenMode with background job error = %v, want exact background-job guard", err)
+	}
+	cancelled, err := app.CancelJobForTab("", job.ID)
+	if err != nil || !cancelled {
+		t.Fatalf("CancelJobForTab = %v, %v, want true, nil", cancelled, err)
+	}
+	if result := jm.WaitForSession(context.Background(), agent.BranchID(path), []string{job.ID}, 5); len(result) != 1 || result[0].Status != jobs.Killed {
+		t.Fatalf("stopped background job = %+v, want one killed result", result)
+	}
+	if err := app.SetTokenMode("economy"); err != nil {
+		t.Fatalf("SetTokenMode after stopping background job: %v", err)
 	}
 }

@@ -6814,6 +7008,46 @@ func TestUserTriggeredCommandsReturnErrorsWhenUnavailable(t *testing.T) {
 	}
 }

+func TestSubmitEntryPointsRejectEmptyProviderInput(t *testing.T) {
+	app := NewApp()
+	for _, tt := range []struct {
+		name string
+		call func() error
+	}{
+		{name: "plain", call: func() error { return app.SubmitToTab("missing", " \n\t ") }},
+		{name: "display", call: func() error { return app.SubmitDisplayToTab("missing", "visible prompt", " ") }},
+		{name: "delivery recovery", call: func() error {
+			return app.SubmitDeliveryRecoveryToTab("missing", "visible prompt", "")
+		}},
+		{name: "invocations", call: func() error {
+			return app.SubmitInvocationsToTab("missing", "/skill visible", "", nil)
+		}},
+		{name: "edited display", call: func() error {
+			return app.SubmitEditedDisplayToTab("missing", "visible prompt", "\n", "original prompt")
+		}},
+		{name: "initial goal", call: func() error {
+			_, err := app.SubmitInitialGoalToTab("missing", "goal", "visible prompt", "", nil, "normal", "auto", "local", 0, 0)
+			return err
+		}},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			if err := tt.call(); !errors.Is(err, errEmptyTurnInput) {
+				t.Fatalf("error = %v, want errEmptyTurnInput", err)
+			}
+		})
+	}
+}
+
+func TestInvocationEntryPointsAllowEmptyExplicitTaskForSkillOnlyTurn(t *testing.T) {
+	invocations := []InvocationRequest{{Name: "skill", Kind: "skill"}}
+	if err := validateInvocationTurnInput("", invocations); err != nil {
+		t.Fatalf("skill-only invocation input rejected: %v", err)
+	}
+	if err := validateInvocationTurnInput("", nil); !errors.Is(err, errEmptyTurnInput) {
+		t.Fatalf("empty input without invocations = %v, want errEmptyTurnInput", err)
+	}
+}
+
 func TestCloseReadOnlyChannelTabDoesNotSnapshotTranscript(t *testing.T) {
 	isolateDesktopUserDirs(t)

@@ -7186,7 +7420,7 @@ func TestCapabilitiesIncludesInstalledPlugins(t *testing.T) {
 	}
 }

-func TestDesktopSharedHostProjectMCPWaitsForLaunchApproval(t *testing.T) {
+func TestDesktopSharedHostProjectMCPConnectsWithoutLaunchApproval(t *testing.T) {
 	if testing.Short() {
 		t.Skip("skipping background MCP boot integration test in short mode")
 	}
@@ -7222,15 +7456,16 @@ url = %q
 	defer ctrl.Close()

 	deadline := time.Now().Add(3 * time.Second)
-	for len(sharedHost.Failures()) == 0 && time.Now().Before(deadline) {
+	for !sharedHost.HasClient("h") && time.Now().Before(deadline) {
 		time.Sleep(25 * time.Millisecond)
 	}
-	if sharedHost.HasClient("h") {
-		t.Fatal("project MCP connected before launch approval")
+	if !sharedHost.HasClient("h") {
+		t.Fatalf("project MCP did not connect automatically; failures=%+v", sharedHost.Failures())
 	}
-	failures := sharedHost.Failures()
-	if len(failures) != 1 || !failures[0].RequiresLaunchApproval || !strings.Contains(failures[0].Error, "until the user authorizes") {
-		t.Fatalf("project MCP failure = %+v", failures)
+	for _, failure := range sharedHost.Failures() {
+		if failure.Name == "h" && failure.RequiresLaunchApproval {
+			t.Fatalf("project MCP unexpectedly requested launch approval: %+v", failure)
+		}
 	}

 	app := NewApp()
@@ -7248,12 +7483,12 @@ url = %q
 	app.activeTabID = "test"

 	view := app.MCPServers()
-	if len(view) != 1 || view[0].Name != "h" || view[0].Status != "failed" || view[0].RuntimeState != "issue" || !view[0].RequiresLaunchApproval {
-		t.Fatalf("MCPServers() = %+v, want project h awaiting launch approval", view)
+	if len(view) != 1 || view[0].Name != "h" || view[0].Status != "connected" || view[0].RuntimeState != "ready" || view[0].RequiresLaunchApproval {
+		t.Fatalf("MCPServers() = %+v, want trusted connected project h", view)
 	}
 }

-func TestProjectMCPLaunchApprovalViewOnlyShowsWhileBlocked(t *testing.T) {
+func TestProjectMCPViewIsTrustedAndKeepsProjectSource(t *testing.T) {
 	entry := config.PluginEntry{Name: "project", Source: config.MCPSourceProjectConfig}
 	connected := withPluginConfig(ServerView{Name: entry.Name, Status: "connected"}, entry)
 	if connected.RequiresLaunchApproval {
@@ -7262,8 +7497,11 @@ func TestProjectMCPLaunchApprovalViewOnlyShowsWhileBlocked(t *testing.T) {
 	blocked := withPluginConfig(ServerView{
 		Name: entry.Name, Status: "failed", RequiresLaunchApproval: true,
 	}, entry)
-	if !blocked.RequiresLaunchApproval {
-		t.Fatalf("blocked project MCP lost launch approval action: %+v", blocked)
+	if blocked.RequiresLaunchApproval {
+		t.Fatalf("project MCP exposed obsolete launch approval action: %+v", blocked)
+	}
+	if blocked.Source != "project" || blocked.ConfigSource != "reasonix.toml" {
+		t.Fatalf("blocked project MCP source = %q/%q, want project/reasonix.toml", blocked.Source, blocked.ConfigSource)
 	}

 	user := withPluginConfig(ServerView{Name: "user", Status: "connected"},
@@ -7271,6 +7509,9 @@ func TestProjectMCPLaunchApprovalViewOnlyShowsWhileBlocked(t *testing.T) {
 	if user.RequiresLaunchApproval {
 		t.Fatalf("user-config MCP must not be launch-gate governed: %+v", user)
 	}
+	if user.Source != "user" || user.ConfigSource != "config.toml" {
+		t.Fatalf("user MCP source = %q/%q, want user/config.toml", user.Source, user.ConfigSource)
+	}
 }

 func TestMCPServersMatchesCapabilitiesServerProjection(t *testing.T) {
@@ -8561,6 +8802,71 @@ args = ["serve"]
 	}
 }

+func TestRemoveProjectMCPRevealsAndRegistersGlobalFallback(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	dir := robustTempDir(t)
+	t.Chdir(dir)
+	userCfg := config.LoadForEdit(config.UserConfigPath())
+	userCfg.Plugins = []config.PluginEntry{{Name: "docs", Command: "global-docs"}}
+	if err := userCfg.SaveTo(config.UserConfigPath()); err != nil {
+		t.Fatal(err)
+	}
+	projectPath := filepath.Join(dir, "reasonix.toml")
+	if err := os.WriteFile(projectPath, []byte(`
+[[plugins]]
+name = "docs"
+command = "project-docs"
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	reg := tool.NewRegistry()
+	var configured []plugin.Spec
+	ctrl := control.New(control.Options{
+		Host:          plugin.NewHost(),
+		Registry:      reg,
+		WorkspaceRoot: dir,
+		MCPConfigureSpec: func(spec *plugin.Spec) {
+			configured = append(configured, *spec)
+		},
+	})
+	defer ctrl.Close()
+	projectEntry, found, err := desktopEffectiveMCPServer(dir, "docs")
+	if err != nil || !found {
+		t.Fatalf("load project docs: entry=%+v found=%v err=%v", projectEntry, found, err)
+	}
+	if _, err := ctrl.RegisterMCPServerOnDemand(projectEntry); err != nil {
+		t.Fatalf("register project docs: %v", err)
+	}
+
+	app := NewApp()
+	app.setTestCtrl(ctrl, "")
+	app.activeTab().WorkspaceRoot = dir
+	if err := app.RemoveMCPServer("docs"); err != nil {
+		t.Fatalf("RemoveMCPServer(docs): %v", err)
+	}
+
+	projectCfg := config.LoadForEdit(projectPath)
+	if _, found := findPluginEntry(projectCfg.Plugins, "docs"); found {
+		t.Fatalf("project docs still configured after removal: %+v", projectCfg.Plugins)
+	}
+	globalCfg := config.LoadForEdit(config.UserConfigPath())
+	globalEntry, found := findPluginEntry(globalCfg.Plugins, "docs")
+	if !found || globalEntry.Command != "global-docs" {
+		t.Fatalf("global docs fallback = %+v, found=%v", globalEntry, found)
+	}
+	effective, found, err := desktopEffectiveMCPServer(dir, "docs")
+	if err != nil || !found || effective.Source != config.MCPSourceUserConfig || effective.Command != "global-docs" {
+		t.Fatalf("effective docs fallback = %+v, found=%v err=%v", effective, found, err)
+	}
+	if len(configured) < 2 || configured[len(configured)-1].Command != "global-docs" {
+		t.Fatalf("registered specs = %+v, want global fallback registered last", configured)
+	}
+	if _, found := reg.Get("mcp__docs__connect"); !found {
+		t.Fatalf("global fallback connect surface missing; names=%v", reg.Names())
+	}
+}
+
 func TestRemoveMCPServerClearsRecordedStartupFailure(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := robustTempDir(t)
@@ -8786,6 +9092,59 @@ func TestUpdateMCPServerEditsProjectMCPJSONEntry(t *testing.T) {
 	}
 }

+func TestUpdateMCPServerPreservesProjectTOMLSourceAndGlobalShadow(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	dir := robustTempDir(t)
+	t.Chdir(dir)
+	userCfg := config.LoadForEdit(config.UserConfigPath())
+	userCfg.Plugins = []config.PluginEntry{{Name: "docs", Command: "global-docs"}}
+	if err := userCfg.SaveTo(config.UserConfigPath()); err != nil {
+		t.Fatal(err)
+	}
+	projectPath := filepath.Join(dir, "reasonix.toml")
+	if err := os.WriteFile(projectPath, []byte(`
+[[plugins]]
+name = "docs"
+command = "project-docs"
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	app := NewApp()
+	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost(), WorkspaceRoot: dir}), "")
+	defer app.activeCtrl().Close()
+	app.activeTab().WorkspaceRoot = dir
+	entry, ok, err := desktopEffectiveMCPServer(dir, "docs")
+	if err != nil || !ok || entry.Source != config.MCPSourceProjectConfig {
+		t.Fatalf("load project docs entry: entry=%+v found=%v err=%v", entry, ok, err)
+	}
+	if err := config.DefaultMCPActivationStore().SetServerEnabled(entry, dir, false); err != nil {
+		t.Fatal(err)
+	}
+	app.activeTab().disabledMCP["docs"] = ServerView{}
+
+	if err := app.UpdateMCPServer("docs", MCPServerInput{
+		Name: "docs", Transport: "stdio", Command: "project-docs-updated",
+	}); err != nil {
+		t.Fatalf("UpdateMCPServer(project reasonix.toml docs): %v", err)
+	}
+
+	projectCfg := config.LoadForEdit(projectPath)
+	projectEntry, found := findPluginEntry(projectCfg.Plugins, "docs")
+	if !found || projectEntry.Command != "project-docs-updated" {
+		t.Fatalf("project docs entry = %+v, found=%v", projectEntry, found)
+	}
+	globalCfg := config.LoadForEdit(config.UserConfigPath())
+	globalEntry, found := findPluginEntry(globalCfg.Plugins, "docs")
+	if !found || globalEntry.Command != "global-docs" {
+		t.Fatalf("global shadow changed while editing project entry: %+v, found=%v", globalEntry, found)
+	}
+	effective, found, err := desktopEffectiveMCPServer(dir, "docs")
+	if err != nil || !found || effective.Source != config.MCPSourceProjectConfig || effective.Command != "project-docs-updated" {
+		t.Fatalf("effective docs after edit = %+v, found=%v err=%v", effective, found, err)
+	}
+}
+
 func TestAddMCPServerPersistsRemoteHeaders(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := robustTempDir(t)
@@ -9186,7 +9545,7 @@ tier = "lazy"
 	t.Fatalf("figma MCP missing from Capabilities: %+v", view.Servers)
 }

-func TestUpdateMCPServerMigratesLegacyTierToBackground(t *testing.T) {
+func TestUpdateMCPServerMigratesLegacyTierInProjectSource(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := robustTempDir(t)
 	t.Chdir(dir)
@@ -9236,19 +9595,19 @@ tier = "lazy"
 		t.Fatalf("env TOKEN = %q, want preserved env", got)
 	}
 	userCfg := config.LoadForEdit(config.UserConfigPath())
-	userPlugin, ok := findPluginEntry(userCfg.Plugins, "playwright")
-	if !ok {
-		t.Fatalf("playwright should be migrated to user config: %+v", userCfg.Plugins)
-	}
-	if userPlugin.Command != "node" || userPlugin.Env["TOKEN"] != "${PLAYWRIGHT_TOKEN}" {
-		t.Fatalf("user plugin after migration = %+v", userPlugin)
-	}
-	if userPlugin.Tier != "" {
-		t.Fatalf("user plugin tier = %q, want migrated empty", userPlugin.Tier)
+	if _, ok := findPluginEntry(userCfg.Plugins, "playwright"); ok {
+		t.Fatalf("project plugin should not be copied to user config: %+v", userCfg.Plugins)
 	}
 	projectCfg := config.LoadForEdit(filepath.Join(dir, "reasonix.toml"))
-	if _, ok := findPluginEntry(projectCfg.Plugins, "playwright"); ok {
-		t.Fatalf("project plugin should be removed after desktop migration: %+v", projectCfg.Plugins)
+	projectPlugin, ok := findPluginEntry(projectCfg.Plugins, "playwright")
+	if !ok {
+		t.Fatalf("playwright should remain in project config: %+v", projectCfg.Plugins)
+	}
+	if projectPlugin.Command != "node" || projectPlugin.Env["TOKEN"] != "${PLAYWRIGHT_TOKEN}" {
+		t.Fatalf("project plugin after update = %+v", projectPlugin)
+	}
+	if projectPlugin.Tier != "" {
+		t.Fatalf("project plugin tier = %q, want migrated empty", projectPlugin.Tier)
 	}
 	view := app.Capabilities()
 	for _, s := range view.Servers {
@@ -9411,7 +9770,7 @@ name = "codegraph"
 	t.Fatalf("codegraph missing after reconnect: %+v", view.Servers)
 }

-func TestSetMCPServerTierRecordsConnectFailure(t *testing.T) {
+func TestSetMCPServerTierPreservesProjectSourceAndRecordsConnectFailure(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := robustTempDir(t)
 	t.Chdir(dir)
@@ -9443,16 +9802,16 @@ tier = "lazy"
 		t.Fatalf("saved tier = %q, want migrated empty", got)
 	}
 	userCfg := config.LoadForEdit(config.UserConfigPath())
-	userPlugin, ok := findPluginEntry(userCfg.Plugins, "broken")
-	if !ok {
-		t.Fatalf("broken should be migrated to user config: %+v", userCfg.Plugins)
-	}
-	if userPlugin.Tier != "" {
-		t.Fatalf("user plugin tier = %q, want migrated empty", userPlugin.Tier)
+	if _, ok := findPluginEntry(userCfg.Plugins, "broken"); ok {
+		t.Fatalf("project plugin should not be copied to user config: %+v", userCfg.Plugins)
 	}
 	projectCfg := config.LoadForEdit(filepath.Join(dir, "reasonix.toml"))
-	if _, ok := findPluginEntry(projectCfg.Plugins, "broken"); ok {
-		t.Fatalf("project plugin should be removed after desktop migration: %+v", projectCfg.Plugins)
+	projectPlugin, ok := findPluginEntry(projectCfg.Plugins, "broken")
+	if !ok {
+		t.Fatalf("broken should remain in project config: %+v", projectCfg.Plugins)
+	}
+	if projectPlugin.Tier != "" {
+		t.Fatalf("project plugin tier = %q, want migrated empty", projectPlugin.Tier)
 	}
 	if !mcpFailed(app.activeCtrl(), "broken") {
 		t.Fatalf("Host.Failures() = %+v, want broken failure recorded", app.activeCtrl().Host().Failures())
@@ -9759,7 +10118,11 @@ func startNonCooperativeSessionJob(t *testing.T, jm *jobs.Manager, sessionPath s

 func waitNotRunning(t *testing.T, ctrl control.SessionAPI) {
 	t.Helper()
-	deadline := time.Now().Add(time.Second)
+	// Windows release runners can take more than one second to schedule the
+	// controller's asynchronous completion while the full desktop suite is
+	// active. Keep a bounded responsiveness check without treating scheduler
+	// delay as a leaked controller.
+	deadline := time.Now().Add(5 * time.Second)
 	for ctrl.Running() {
 		if time.Now().After(deadline) {
 			t.Fatal("controller still running")
@@ -35,6 +35,16 @@ func TestWindowsICOUsesBlueFullCanvasRoundedBackground(t *testing.T) {
 	}
 }

+func TestDarwinICNSUsesMacOSIconSafeArea(t *testing.T) {
+	img := decodeICNSImage(t, "build/darwin/icon.icns", "ic10")
+	if got, want := img.Bounds(), image.Rect(0, 0, 1024, 1024); got != want {
+		t.Fatalf("macOS ic10 frame bounds = %v, want %v", got, want)
+	}
+	if got, want := alphaBounds(img), image.Rect(100, 100, 924, 924); got != want {
+		t.Fatalf("macOS icon visible bounds = %v, want %v", got, want)
+	}
+}
+
 func assertFullCanvasRoundedIcon(t *testing.T, img image.Image, size int) {
 	t.Helper()

@@ -101,6 +111,75 @@ func near(got, want uint8, tolerance uint8) bool {
 	return want-got <= tolerance
 }

+func alphaBounds(img image.Image) image.Rectangle {
+	bounds := img.Bounds()
+	visible := image.Rectangle{}
+	found := false
+	for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
+		for x := bounds.Min.X; x < bounds.Max.X; x++ {
+			_, _, _, a := img.At(x, y).RGBA()
+			if a == 0 {
+				continue
+			}
+			if !found {
+				visible = image.Rect(x, y, x+1, y+1)
+				found = true
+				continue
+			}
+			if x < visible.Min.X {
+				visible.Min.X = x
+			}
+			if y < visible.Min.Y {
+				visible.Min.Y = y
+			}
+			if x >= visible.Max.X {
+				visible.Max.X = x + 1
+			}
+			if y >= visible.Max.Y {
+				visible.Max.Y = y + 1
+			}
+		}
+	}
+	return visible
+}
+
+func decodeICNSImage(t *testing.T, path, iconType string) image.Image {
+	t.Helper()
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(data) < 8 || string(data[:4]) != "icns" {
+		t.Fatal("invalid ICNS header")
+	}
+	if declaredSize := int(binary.BigEndian.Uint32(data[4:8])); declaredSize != len(data) {
+		t.Fatalf("ICNS size = %d, want %d", declaredSize, len(data))
+	}
+
+	for offset := 8; offset < len(data); {
+		if offset+8 > len(data) {
+			t.Fatalf("truncated ICNS entry header at offset %d", offset)
+		}
+		entryType := string(data[offset : offset+4])
+		entrySize := int(binary.BigEndian.Uint32(data[offset+4 : offset+8]))
+		if entrySize < 8 || offset+entrySize > len(data) {
+			t.Fatalf("invalid ICNS entry %q size %d at offset %d", entryType, entrySize, offset)
+		}
+		if entryType == iconType {
+			img, err := png.Decode(bytes.NewReader(data[offset+8 : offset+entrySize]))
+			if err != nil {
+				t.Fatalf("decode ICNS entry %q: %v", iconType, err)
+			}
+			return img
+		}
+		offset += entrySize
+	}
+
+	t.Fatalf("ICNS is missing %q image", iconType)
+	return nil
+}
+
 func decodeICOImage(t *testing.T, path string, size int) image.Image {
 	t.Helper()

@@ -0,0 +1,332 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"reasonix/internal/control"
+	"reasonix/internal/workspacelease"
+)
+
+// ActiveWorkView is the structured Desktop contract for work that prevents a
+// controller rebuild or a destructive tab action. Jobs is always a JSON array.
+type ActiveWorkView struct {
+	Running       bool      `json:"running"`
+	PendingPrompt bool      `json:"pendingPrompt"`
+	Cancellable   bool      `json:"cancellable"`
+	Jobs          []JobView `json:"jobs"`
+}
+
+// JobCancelBatchView reports which requested jobs accepted cancellation. Both
+// slices are initialized so Wails never sends null to React.
+type JobCancelBatchView struct {
+	Cancelled  []string `json:"cancelled"`
+	NotRunning []string `json:"notRunning"`
+}
+
+// BackgroundRuntimeView is one visible or detached runtime with active work.
+// TabID is an opaque process-local handle; paths and session writer ids are
+// deliberately omitted from this user-facing contract.
+type BackgroundRuntimeView struct {
+	TabID         string    `json:"tabId"`
+	Title         string    `json:"title"`
+	Detached      bool      `json:"detached"`
+	Running       bool      `json:"running"`
+	PendingPrompt bool      `json:"pendingPrompt"`
+	Jobs          []JobView `json:"jobs"`
+}
+
+// WorkspaceConflictView describes a currently-waiting Delivery writer without
+// exposing the lock path, process id, or session path.
+type WorkspaceConflictView struct {
+	State             string         `json:"state"`
+	OwnerTabID        string         `json:"ownerTabId,omitempty"`
+	OwnerTitle        string         `json:"ownerTitle,omitempty"`
+	OwnerWork         ActiveWorkView `json:"ownerWork"`
+	CanReveal         bool           `json:"canReveal"`
+	CanCreateWorktree bool           `json:"canCreateWorktree"`
+}
+
+func activeWorkForController(ctrl control.SessionAPI) ActiveWorkView {
+	view := ActiveWorkView{Jobs: []JobView{}}
+	if ctrl == nil {
+		return view
+	}
+	status := ctrl.RuntimeStatus()
+	view.Running = status.Running
+	view.PendingPrompt = status.PendingPrompt
+	view.Cancellable = status.Cancellable
+	for _, job := range ctrl.Jobs() {
+		view.Jobs = append(view.Jobs, JobView{
+			ID: job.ID, Kind: job.Kind, Label: job.Label,
+			Status: job.Status, StartedAt: job.StartedAt,
+		})
+	}
+	return view
+}
+
+func (v ActiveWorkView) active() bool {
+	return v.Running || v.PendingPrompt || len(v.Jobs) > 0
+}
+
+// ActiveWorkForTab returns the precise blocker state for one tab. It is a
+// preflight aid only; rebuild paths still re-check active work atomically.
+func (a *App) ActiveWorkForTab(tabID string) ActiveWorkView {
+	return activeWorkForController(a.ctrlForRuntimeTabID(tabID))
+}
+
+// CancelJobsForTab requests cancellation for a stable tab id. The job manager
+// keeps cancelled-but-unwinding jobs visible until their done channels close.
+func (a *App) CancelJobsForTab(tabID string, jobIDs []string) (JobCancelBatchView, error) {
+	result := JobCancelBatchView{Cancelled: []string{}, NotRunning: []string{}}
+	seen := map[string]bool{}
+	for _, raw := range jobIDs {
+		id := strings.TrimSpace(raw)
+		if id == "" || seen[id] {
+			continue
+		}
+		seen[id] = true
+		cancelled, err := a.CancelJobForTab(tabID, id)
+		if err != nil {
+			return result, err
+		}
+		if cancelled {
+			result.Cancelled = append(result.Cancelled, id)
+		} else {
+			result.NotRunning = append(result.NotRunning, id)
+		}
+	}
+	return result, nil
+}
+
+type backgroundRuntimeSnapshot struct {
+	id       string
+	ctrl     control.SessionAPI
+	detached bool
+	title    string
+}
+
+// BackgroundRuntimes returns every process-local runtime that still needs a
+// visible recovery path, including runtimes detached by an explicit tab close.
+func (a *App) BackgroundRuntimes() []BackgroundRuntimeView {
+	a.mu.RLock()
+	snapshots := make([]backgroundRuntimeSnapshot, 0, len(a.tabs)+len(a.detachedSessions))
+	seen := map[*WorkspaceTab]bool{}
+	for _, tab := range a.tabs {
+		if tab == nil || seen[tab] {
+			continue
+		}
+		seen[tab] = true
+		title := strings.TrimSpace(tab.TopicTitle)
+		if title == "" {
+			title = strings.TrimSpace(tab.Label)
+		}
+		snapshots = append(snapshots, backgroundRuntimeSnapshot{id: tab.ID, ctrl: tab.Ctrl, title: title})
+	}
+	for _, tab := range a.detachedSessions {
+		if tab == nil || seen[tab] {
+			continue
+		}
+		seen[tab] = true
+		title := strings.TrimSpace(tab.TopicTitle)
+		if title == "" {
+			title = strings.TrimSpace(tab.Label)
+		}
+		snapshots = append(snapshots, backgroundRuntimeSnapshot{id: tab.ID, ctrl: tab.Ctrl, detached: true, title: title})
+	}
+	a.mu.RUnlock()
+
+	out := make([]BackgroundRuntimeView, 0, len(snapshots))
+	for _, snapshot := range snapshots {
+		work := activeWorkForController(snapshot.ctrl)
+		if !work.active() {
+			continue
+		}
+		out = append(out, BackgroundRuntimeView{
+			TabID: snapshot.id, Title: snapshot.title, Detached: snapshot.detached,
+			Running: work.Running, PendingPrompt: work.PendingPrompt, Jobs: work.Jobs,
+		})
+	}
+	return out
+}
+
+func (a *App) ctrlForRuntimeTabID(tabID string) control.SessionAPI {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	if strings.TrimSpace(tabID) == "" {
+		return a.activeCtrlLocked()
+	}
+	tab := a.tabByEventSinkIDLocked(tabID)
+	if tab == nil {
+		return nil
+	}
+	return tab.Ctrl
+}
+
+// RevealBackgroundRuntime activates a visible owner or reopens the exact
+// detached session. It never reattaches by workspace alone.
+func (a *App) RevealBackgroundRuntime(tabID string) (TabMeta, error) {
+	a.mu.RLock()
+	if tab := a.tabs[tabID]; tab != nil {
+		a.mu.RUnlock()
+		if err := a.SetActiveTab(tabID); err != nil {
+			return TabMeta{}, err
+		}
+		a.mu.RLock()
+		current := a.tabs[tabID]
+		if current == nil {
+			a.mu.RUnlock()
+			return TabMeta{}, fmt.Errorf("background task is no longer available")
+		}
+		meta := a.tabMeta(current, true)
+		a.mu.RUnlock()
+		return enrichTabMeta(meta), nil
+	}
+	tab := a.tabByEventSinkIDLocked(tabID)
+	if tab == nil || tab.Ctrl == nil {
+		a.mu.RUnlock()
+		return TabMeta{}, fmt.Errorf("background task is no longer available")
+	}
+	scope := tab.Scope
+	workspaceRoot := tab.WorkspaceRoot
+	topicID := tab.TopicID
+	sessionPath := tab.currentSessionPath()
+	a.mu.RUnlock()
+	if strings.TrimSpace(sessionPath) == "" {
+		return TabMeta{}, fmt.Errorf("background task session is unavailable")
+	}
+	return a.OpenTopicSession(scope, workspaceRoot, topicID, sessionPath)
+}
+
+type workspaceLeaseReporter interface {
+	WorkspaceLeaseState() workspacelease.State
+}
+
+func controllerWorkspaceLeaseState(ctrl control.SessionAPI) workspacelease.State {
+	if reporter, ok := ctrl.(workspaceLeaseReporter); ok {
+		return reporter.WorkspaceLeaseState()
+	}
+	return workspacelease.State{}
+}
+
+// WorkspaceConflictForTab classifies the owner that a Delivery writer is
+// currently waiting for. An acquired process-local owner is actionable; when no
+// local owner matches, the OS lock is treated as external.
+func (a *App) WorkspaceConflictForTab(tabID string) WorkspaceConflictView {
+	empty := WorkspaceConflictView{State: "none", OwnerWork: ActiveWorkView{Jobs: []JobView{}}}
+	a.mu.RLock()
+	var target *WorkspaceTab
+	if strings.TrimSpace(tabID) == "" {
+		target = a.activeTabLocked()
+	} else {
+		target = a.tabByEventSinkIDLocked(tabID)
+	}
+	if target == nil {
+		a.mu.RUnlock()
+		return empty
+	}
+	targetCtrl := target.Ctrl
+	targetWorkspaceRoot := target.WorkspaceRoot
+	a.mu.RUnlock()
+	if targetCtrl == nil {
+		return empty
+	}
+	targetState := controllerWorkspaceLeaseState(targetCtrl)
+	if !targetState.Waiting || targetState.Acquired {
+		return empty
+	}
+	targetRoot, err := workspacelease.CanonicalWorkspace(targetWorkspaceRoot)
+	if err != nil {
+		return empty
+	}
+	availability := a.DeliveryWorktreeAvailability(targetWorkspaceRoot)
+
+	a.mu.RLock()
+	type candidate struct {
+		id    string
+		ctrl  control.SessionAPI
+		root  string
+		title string
+	}
+	candidates := make([]candidate, 0, len(a.tabs)+len(a.detachedSessions))
+	seen := map[*WorkspaceTab]bool{}
+	for _, tab := range a.runtimeTabsLocked() {
+		if tab == nil || tab == target || seen[tab] || tab.Ctrl == nil {
+			continue
+		}
+		seen[tab] = true
+		title := strings.TrimSpace(tab.TopicTitle)
+		if title == "" {
+			title = strings.TrimSpace(tab.Label)
+		}
+		candidates = append(candidates, candidate{id: tab.ID, ctrl: tab.Ctrl, root: tab.WorkspaceRoot, title: title})
+	}
+	a.mu.RUnlock()
+
+	for _, candidate := range candidates {
+		root, err := workspacelease.CanonicalWorkspace(candidate.root)
+		if err != nil || root != targetRoot || !controllerWorkspaceLeaseState(candidate.ctrl).Acquired {
+			continue
+		}
+		return WorkspaceConflictView{
+			State: "local", OwnerTabID: candidate.id, OwnerTitle: candidate.title,
+			OwnerWork: activeWorkForController(candidate.ctrl), CanReveal: true,
+			CanCreateWorktree: availability.Available,
+		}
+	}
+	empty.State = "external"
+	empty.CanCreateWorktree = availability.Available
+	return empty
+}
+
+// RevealWorkspaceWriterForTab opens the exact process-local runtime identified
+// by WorkspaceConflictForTab. External writers remain non-actionable.
+func (a *App) RevealWorkspaceWriterForTab(tabID string) (TabMeta, error) {
+	conflict := a.WorkspaceConflictForTab(tabID)
+	if conflict.State != "local" || conflict.OwnerTabID == "" {
+		return TabMeta{}, fmt.Errorf("the workspace writer is not available in this Reasonix window")
+	}
+	return a.RevealBackgroundRuntime(conflict.OwnerTabID)
+}
+
+const stopAndCloseGrace = 15 * time.Second
+
+// CloseTabWithPolicy makes the old implicit detach behavior an explicit user
+// choice. stop_and_close never removes the tab until all owned work is idle.
+func (a *App) CloseTabWithPolicy(tabID, policy string) error {
+	switch strings.TrimSpace(policy) {
+	case "keep_running":
+		return a.closeTab(tabID, true)
+	case "stop_and_close":
+		ctrl := a.ctrlForRuntimeTabID(tabID)
+		if ctrl == nil {
+			return a.closeTab(tabID, false)
+		}
+		ctrl.Cancel()
+		jobs := ctrl.Jobs()
+		ids := make([]string, 0, len(jobs))
+		for _, job := range jobs {
+			ids = append(ids, job.ID)
+		}
+		if _, err := a.CancelJobsForTab(tabID, ids); err != nil {
+			return err
+		}
+		deadline := time.NewTimer(stopAndCloseGrace)
+		defer deadline.Stop()
+		ticker := time.NewTicker(25 * time.Millisecond)
+		defer ticker.Stop()
+		for {
+			if !activeWorkForController(ctrl).active() {
+				return a.closeTab(tabID, false)
+			}
+			select {
+			case <-deadline.C:
+				return fmt.Errorf("background work did not stop within %s; the task was kept open", stopAndCloseGrace)
+			case <-ticker.C:
+			}
+		}
+	default:
+		return fmt.Errorf("unknown close policy %q", policy)
+	}
+}
@@ -0,0 +1,154 @@
+package main
+
+import (
+	"testing"
+
+	"reasonix/internal/control"
+	"reasonix/internal/jobs"
+	"reasonix/internal/remote/workbench/client"
+	"reasonix/internal/workspacelease"
+)
+
+type backgroundRuntimeController struct {
+	control.SessionAPI
+	status     control.RuntimeStatus
+	jobs       []jobs.View
+	lease      workspacelease.State
+	cancelled  []string
+	turnCancel int
+}
+
+func (c *backgroundRuntimeController) RuntimeStatus() control.RuntimeStatus { return c.status }
+func (c *backgroundRuntimeController) Jobs() []jobs.View {
+	return append([]jobs.View(nil), c.jobs...)
+}
+func (c *backgroundRuntimeController) CancelJob(id string) bool {
+	for _, job := range c.jobs {
+		if job.ID == id {
+			c.cancelled = append(c.cancelled, id)
+			return true
+		}
+	}
+	return false
+}
+func (c *backgroundRuntimeController) Cancel() { c.turnCancel++ }
+func (c *backgroundRuntimeController) WorkspaceLeaseState() workspacelease.State {
+	return c.lease
+}
+
+func TestBackgroundRuntimeAPIsKeepDetachedJobsActionable(t *testing.T) {
+	targetCtrl := &backgroundRuntimeController{
+		status: control.RuntimeStatus{BackgroundJobs: 1},
+		jobs:   []jobs.View{{ID: "job-target", Kind: "bash", Label: "target tests", Status: "running", StartedAt: 1}},
+	}
+	focusedCtrl := &backgroundRuntimeController{
+		status: control.RuntimeStatus{BackgroundJobs: 1},
+		jobs:   []jobs.View{{ID: "job-focused", Kind: "bash", Label: "focused tests", Status: "running", StartedAt: 2}},
+	}
+	target := &WorkspaceTab{ID: "target", TopicTitle: "Detached task", Ctrl: targetCtrl}
+	focused := &WorkspaceTab{ID: "focused", TopicTitle: "Focused task", Ctrl: focusedCtrl}
+	app := &App{
+		tabs:             map[string]*WorkspaceTab{"focused": focused},
+		tabOrder:         []string{"focused"},
+		activeTabID:      "focused",
+		detachedSessions: map[string]*WorkspaceTab{"session-target": target},
+	}
+
+	work := app.ActiveWorkForTab("target")
+	if len(work.Jobs) != 1 || work.Jobs[0].ID != "job-target" {
+		t.Fatalf("ActiveWorkForTab(target) = %+v, want target job", work)
+	}
+	result, err := app.CancelJobsForTab("target", []string{"job-target", "job-target", "missing"})
+	if err != nil {
+		t.Fatalf("CancelJobsForTab: %v", err)
+	}
+	if len(result.Cancelled) != 1 || result.Cancelled[0] != "job-target" || len(result.NotRunning) != 1 || result.NotRunning[0] != "missing" {
+		t.Fatalf("CancelJobsForTab result = %+v", result)
+	}
+	if len(targetCtrl.cancelled) != 1 || len(focusedCtrl.cancelled) != 0 {
+		t.Fatalf("cancellation routing target=%v focused=%v", targetCtrl.cancelled, focusedCtrl.cancelled)
+	}
+
+	runtimes := app.BackgroundRuntimes()
+	if len(runtimes) != 2 {
+		t.Fatalf("BackgroundRuntimes = %+v, want visible and detached", runtimes)
+	}
+	var foundDetached bool
+	for _, runtime := range runtimes {
+		if runtime.TabID == "target" {
+			foundDetached = runtime.Detached && runtime.Title == "Detached task" && len(runtime.Jobs) == 1
+		}
+	}
+	if !foundDetached {
+		t.Fatalf("detached runtime missing from %+v", runtimes)
+	}
+}
+
+func TestCancelJobForLocalRuntimeWhileRemoteWorkbenchIsActive(t *testing.T) {
+	localCtrl := &backgroundRuntimeController{
+		status: control.RuntimeStatus{BackgroundJobs: 1},
+		jobs:   []jobs.View{{ID: "job-local", Kind: "bash", Status: "running"}},
+	}
+	app := &App{
+		tabs:        map[string]*WorkspaceTab{"local": {ID: "local", Ctrl: localCtrl}},
+		tabOrder:    []string{"local"},
+		activeTabID: "local",
+	}
+	kernel := app.workbench()
+	_, generation, err := kernel.targets.BeginRemoteConnect("remote-host", "/srv/work")
+	if err != nil {
+		t.Fatalf("BeginRemoteConnect: %v", err)
+	}
+	if err := kernel.targets.MarkRemoteConnected(generation); err != nil {
+		t.Fatalf("MarkRemoteConnected: %v", err)
+	}
+	if _, _, _, err := kernel.targets.ActivateRemote(generation); err != nil {
+		t.Fatalf("ActivateRemote: %v", err)
+	}
+	kernel.mu.Lock()
+	kernel.remote = &client.Client{}
+	kernel.remoteGen = generation
+	kernel.remoteTabID = "remote"
+	kernel.mu.Unlock()
+
+	listed := app.JobsForTab("local")
+	if len(listed) != 1 || listed[0].ID != "job-local" {
+		t.Fatalf("JobsForTab(local) = %+v, want local job while Remote Workbench is active", listed)
+	}
+	cancelled, err := app.CancelJobForTab("local", "job-local")
+	if err != nil {
+		t.Fatalf("CancelJobForTab(local): %v", err)
+	}
+	if !cancelled || len(localCtrl.cancelled) != 1 || localCtrl.cancelled[0] != "job-local" {
+		t.Fatalf("local cancellation = %t, calls=%v; want local job cancelled", cancelled, localCtrl.cancelled)
+	}
+}
+
+func TestWorkspaceConflictIdentifiesExactLocalWriterWithoutIdentity(t *testing.T) {
+	root := t.TempDir()
+	waiterCtrl := &backgroundRuntimeController{
+		status: control.RuntimeStatus{Running: true},
+		lease:  workspacelease.State{Waiting: true},
+	}
+	ownerCtrl := &backgroundRuntimeController{
+		status: control.RuntimeStatus{BackgroundJobs: 1},
+		jobs:   []jobs.View{{ID: "owner-job", Kind: "bash", Status: "running"}},
+		lease:  workspacelease.State{Acquired: true},
+	}
+	app := &App{
+		tabs: map[string]*WorkspaceTab{
+			"waiter": {ID: "waiter", WorkspaceRoot: root, Ctrl: waiterCtrl},
+			"owner":  {ID: "owner", TopicTitle: "Writing task", WorkspaceRoot: root, Ctrl: ownerCtrl},
+		},
+		tabOrder:    []string{"waiter", "owner"},
+		activeTabID: "waiter",
+	}
+
+	conflict := app.WorkspaceConflictForTab("waiter")
+	if conflict.State != "local" || conflict.OwnerTabID != "owner" || conflict.OwnerTitle != "Writing task" || !conflict.CanReveal {
+		t.Fatalf("WorkspaceConflictForTab = %+v, want exact local owner", conflict)
+	}
+	if len(conflict.OwnerWork.Jobs) != 1 || conflict.OwnerWork.Jobs[0].ID != "owner-job" {
+		t.Fatalf("owner work = %+v, want sanitized active work", conflict.OwnerWork)
+	}
+}
@@ -185,7 +185,7 @@ func (h *botBridgeHub) observe(tabID string, e event.Event) {
 			// 桌面端主动停止的任务不推送，避免正常操作变成噪音。
 			return
 		}
-		h.enqueue(h.turnDoneNotification(tabID, e.Err))
+		h.enqueue(h.turnDoneNotification(tabID, e))
 	}
 }

@@ -359,15 +359,21 @@ func (h *botBridgeHub) askNotification(tabID string, ask event.Ask) desktopBridg
 	return desktopBridgeNotification{text: textFor, card: card}
 }

-func (h *botBridgeHub) turnDoneNotification(tabID string, err error) desktopBridgeNotification {
+func (h *botBridgeHub) turnDoneNotification(tabID string, e event.Event) desktopBridgeNotification {
 	label := h.tabLabel(tabID)
-	if err != nil {
+	if e.Outcome == event.TurnOutcomeRecoveryPaused {
+		return desktopBridgeNotification{text: constText(fmt.Sprintf(
+			"⏸️ 桌面会话「%s」已暂停自动重试。已完成的工作会保留；发送“继续”即可开始新一轮，也可以补充要求调整方向。",
+			label,
+		))}
+	}
+	if e.Err != nil {
 		// Error text can contain paths/tokens; only detail it in a private chat.
 		return desktopBridgeNotification{text: func(route bot.DesktopWatchRoute) string {
 			if isSharedChat(route.ChatType) {
 				return fmt.Sprintf("❌ 桌面会话「%s」任务出错（详情见桌面端或私聊）。", label)
 			}
-			return fmt.Sprintf("❌ 桌面会话「%s」任务出错: %s", label, truncateForBridge(err.Error(), botBridgeErrTextLimit))
+			return fmt.Sprintf("❌ 桌面会话「%s」任务出错: %s", label, truncateForBridge(e.Err.Error(), botBridgeErrTextLimit))
 		}}
 	}
 	return desktopBridgeNotification{text: constText(fmt.Sprintf("✅ 桌面会话「%s」任务完成。", label))}
@@ -357,6 +357,21 @@ func TestBridgeSuppressesCanceledTurnAndErrorsNotify(t *testing.T) {
 	}
 }

+func TestBridgeRecoveryPauseNotifiesAsControlledPause(t *testing.T) {
+	env := newBridgeTestEnv([]TabMeta{{ID: "tab-1", Label: "会话一"}})
+	env.hub.SetWatch(testWatchRoute(), true)
+
+	env.hub.observe("tab-1", event.Event{
+		Kind:    event.TurnDone,
+		Err:     errors.New("automatic recovery paused"),
+		Outcome: event.TurnOutcomeRecoveryPaused,
+	})
+	call := env.waitNotification(t)
+	if strings.Contains(call.msg.Text, "❌") || !strings.Contains(call.msg.Text, "已暂停自动重试") || !strings.Contains(call.msg.Text, "继续") {
+		t.Fatalf("recovery pause text = %q, want a neutral actionable pause notice", call.msg.Text)
+	}
+}
+
 func TestBridgeAskAnswerRoundTrip(t *testing.T) {
 	env := newBridgeTestEnv([]TabMeta{{ID: "tab-2", Label: "问答会话"}})
 	env.hub.SetWatch(testWatchRoute(), true)
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024" role="img" aria-label="Reasonix">
+  <!-- Legacy ICNS renderers do not apply the modern macOS icon mask. Keep the
+       rounded-square artwork in the 824px icon grid used by peer applications. -->
+  <g transform="translate(100 100) scale(2.06)">
+    <rect width="400" height="400" rx="126.37" ry="126.37" fill="#0153e5"/>
+    <path fill="#fff" d="M253.29,235.46l.02-.02c14.11-4.16,26.51-11.63,36.45-22.4v-.04c10.82-12.11,17.61-26.76,19.97-42.87,5.39-35.23-12.1-67.41-45.05-81.04-11.59-4.65-23.48-6.64-36.12-6.52l-122.5.04v234.74l60.22-.05v-79.23c6.57,2.11,13.49,3.25,20.59,3.22l19.71,27.21,35.83,48.92,71.52-.1-60.64-81.87ZM250.87,224.64c-8.21,2.71-17.01,2.31-25.39-.14-14.4-10.89-22.2-22.51-34.48-33.59-15.72-14.19-36.52-24.02-57.83-23.06,1.7-4.65,4.14-9.09,7.31-13.16,11-13.74,26-18.1,43.24-15.69,6.36.89,13.16-6.58,26.1-5.14.86.1,1.75.75,1.83,1.27.3,1.77-4.71,2.72-4.71,7.55,0,2.03.91,4.39,2.83,5.73,6.6,4.63,12.32,9.83,18.3,15.21,2.91,2.61,12.76,9.96,15.26,3.98,1.47-3.49,2.43-7.15,3.4-10.86.48-1.84-.54-2.93-2.02-3.8-10.17-6.03-13.99-18.56-10.02-29.67.38-1.07,1.38-1.59,2.22-1.63,3.41-.15,1.59,6.18,10.04,8.78,8.01,2.48,8.25,9.13,12.14,6.47,9.07-6.18,12.34-1.12,20.76-9.05.86-.81,2.36-.87,3.25-.25.56.38,1.04,1.38.99,2.55-.25,6.7-2.86,13.1-7.44,18.01-8.66,9.29-15.93,4.84-16.4,11.36-1.38,19.11-7.63,38.18-21.19,52.06-.44.45-.69,1.08-.62,1.51.07.45.61.89,1.2,1.08l11.42,3.89c1.61.55,2.79,2,2.58,3.54-.18,1.35-1.26,2.54-2.79,3.05Z"/>
+  </g>
+</svg>
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE policyconfig PUBLIC
+ "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
+ "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
+<!--
+  Polkit policy for Reasonix desktop in-app .deb upgrades.
+  The action only authorizes the fixed root-owned helper with argv1=install.
+  Active sessions require auth_admin every time; authorization is not retained.
+-->
+<policyconfig>
+  <vendor>Reasonix</vendor>
+  <vendor_url>https://reasonix.io</vendor_url>
+
+  <action id="io.reasonix.desktop.update">
+    <description gettext-domain="reasonix-desktop">Install a Reasonix desktop update</description>
+    <description xml:lang="zh_CN" gettext-domain="reasonix-desktop">安装 Reasonix 桌面端更新</description>
+    <description xml:lang="zh_TW" gettext-domain="reasonix-desktop">安裝 Reasonix 桌面端更新</description>
+    <message gettext-domain="reasonix-desktop">Authentication is required to install a Reasonix update</message>
+    <message xml:lang="zh_CN" gettext-domain="reasonix-desktop">安装 Reasonix 更新需要管理员授权</message>
+    <message xml:lang="zh_TW" gettext-domain="reasonix-desktop">安裝 Reasonix 更新需要管理員授權</message>
+    <defaults>
+      <allow_any>no</allow_any>
+      <allow_inactive>no</allow_inactive>
+      <allow_active>auth_admin</allow_active>
+    </defaults>
+    <annotate key="org.freedesktop.policykit.exec.path">/usr/lib/reasonix/reasonix-update-helper</annotate>
+    <annotate key="org.freedesktop.policykit.exec.argv1">install</annotate>
+  </action>
+</policyconfig>
@@ -1,12 +1,13 @@
 # nfpm config for the Linux .deb package. scripts/desktop-build.sh's linux branch
 # runs `nfpm package` after `wails build`, from the desktop/ dir (so the src paths
-# below are relative to desktop/). The .deb is a human-download artifact only — like
-# the macOS .dmg — so the Linux updater channel stays the .tar.gz and cmd/sign's
-# manifest skips .deb files.
+# below are relative to desktop/). Portable clients keep using the .tar.gz under
+# platforms[]; this .deb is the native package channel (native_packages) and also
+# remains a human-download artifact.
 #
-# $DEB_VERSION and $DEB_ARCH are exported by desktop-build.sh. DEB_VERSION is the tag
-# minus a leading "v" and any prerelease suffix (a strict X.Y.Z that dpkg accepts);
-# DEB_ARCH is the Go arch name, which already matches Debian's (amd64, arm64).
+# $DEB_VERSION and $DEB_ARCH are exported by desktop-build.sh. DEB_VERSION follows
+# Debian version ordering: stable X.Y.Z, prereleases as X.Y.Z~rc.N / X.Y.Z~canary.N
+# so they sort below the matching stable package. DEB_ARCH is the Go arch name,
+# which already matches Debian's (amd64, arm64).
 name: "reasonix-desktop"
 arch: "${DEB_ARCH}"
 platform: "linux"
@@ -21,22 +22,32 @@ homepage: "https://github.com/esengine/DeepSeek-Reasonix"
 license: "MIT"
 # Runtime libraries the WebKitGTK 4.1 build links against (-tags webkit2_41); apt
 # pulls them in on install. These package names ship from Ubuntu 22.04 / Debian 12 on.
+# pkexec is required for the in-app Polkit authorization update path.
 depends:
  - libgtk-3-0
  - libwebkit2gtk-4.1-0
+  - pkexec
 contents:
  - src: ./build/bin/reasonix-desktop
    dst: /usr/bin/reasonix-desktop
    file_info:
      mode: 0755
-  - src: ./build/bin/reasonix-guard
-    dst: /usr/bin/reasonix-guard
+  - src: ./build/bin/reasonix-launcher
+    dst: /usr/bin/reasonix-launcher
    file_info:
      mode: 0755
  - src: ./build/bin/reasonix
    dst: /usr/bin/reasonix
    file_info:
      mode: 0755
+  - src: ./build/bin/reasonix-update-helper
+    dst: /usr/lib/reasonix/reasonix-update-helper
+    file_info:
+      mode: 0755
+  - src: ./build/linux/io.reasonix.desktop.update.policy
+    dst: /usr/share/polkit-1/actions/io.reasonix.desktop.update.policy
+    file_info:
+      mode: 0644
  - src: ./build/linux/reasonix.desktop
    dst: /usr/share/applications/reasonix.desktop
    file_info:
@@ -2,7 +2,7 @@
 Type=Application
 Name=Reasonix
 Comment=Reasonix desktop — a Wails shell around the Go kernel
-Exec=reasonix-guard launch --detach
+Exec=reasonix-launcher
 Icon=reasonix-desktop
 Categories=Development;Utility;
 Terminal=false
@@ -83,8 +83,13 @@ LangString reasonixUpdateSubtitle ${LANG_ENGLISH} "Installing the verified updat
 LangString reasonixUpdateSubtitle ${LANG_SIMPCHINESE} "正在安装已验证的更新，完成后 Reasonix 将自动重启。"
 LangString reasonixUpdateSubtitle ${LANG_TRADCHINESE} "正在安裝已驗證的更新，完成後 Reasonix 將自動重新啟動。"

-## The following two statements can be used to sign the installer and the uninstaller. The path to the binaries are provided in %1
-#!uninstfinalize 'signtool --file "%1"'
+## Preserve the first-pass generated uninstaller so the release workflow can
+## Authenticode-sign it together with the other installed payload files.
+## The second pass provides ARG_REASONIX_SIGNED_UNINSTALLER and embeds that
+## signed binary instead of generating another unsigned uninstaller.
+!ifndef ARG_REASONIX_SIGNED_UNINSTALLER
+!uninstfinalize 'cmd.exe /C copy /Y "%1" "reasonix-uninstall.exe" >NUL'
+!endif
 #!finalize 'signtool --file "%1"'

 Name "${INFO_PRODUCTNAME}"
@@ -95,8 +100,12 @@ OutFile "..\..\bin\${INFO_PROJECTNAME}-${ARCH}-installer.exe" # Name of the inst
 !define REASONIX_LAUNCHER "reasonix-launcher.exe"
 !define REASONIX_CLI "reasonix-cli.exe"
 !define REASONIX_PORTABLE_ENTRY "Reasonix.exe"
+!define REASONIX_LAYOUT_INSTALLER "reasonix-layout-installer.exe"
+!define REASONIX_PAYLOAD_MANIFEST "reasonix-payload.json"
+!define REASONIX_PAYLOAD_SIGNATURE "reasonix-payload.json.minisig"
 !define REASONIX_UNLOCK_RETRIES 60
 Var ReasonixUpdateMode
+Var ReasonixStageMode
 InstallDirRegKey HKCU "${UNINST_KEY}" "InstallLocation" # Reuse the previous install path on update; .onInit falls back to the default on first install.
 InstallDir "${REASONIX_DEFAULT_INSTALLDIR}" # Per-user install location (no admin rights required).
 ShowInstDetails show # This will always show the installation details.
@@ -106,7 +115,11 @@ ShowInstDetails show # This will always show the installation details.
 ## wails.deleteUninstaller, which write HKLM and would fail without admin rights.
 ####
 !macro reasonix.writeUninstaller
+    !ifdef ARG_REASONIX_SIGNED_UNINSTALLER
+    File "/oname=uninstall.exe" "${ARG_REASONIX_SIGNED_UNINSTALLER}"
+    !else
    WriteUninstaller "$INSTDIR\uninstall.exe"
+    !endif

    WriteRegStr HKCU "${UNINST_KEY}" "Publisher" "${INFO_COMPANYNAME}"
    WriteRegStr HKCU "${UNINST_KEY}" "DisplayName" "${INFO_PRODUCTNAME}"
@@ -140,6 +153,7 @@ Function .onInit
   ; destination, then closes automatically after the file copy so the helper
   ; can relaunch Reasonix. A normal manual installer keeps the full wizard.
   StrCpy $ReasonixUpdateMode "0"
+   StrCpy $ReasonixStageMode "0"
   ${GetParameters} $R0
   ClearErrors
   ${GetOptions} $R0 "/REASONIXUPDATE=" $R1
@@ -148,6 +162,13 @@ Function .onInit
   StrCpy $ReasonixUpdateMode "1"

 reasonix_update_mode_done:
+   ClearErrors
+   ${GetOptions} $R0 "/REASONIXSTAGE=" $R2
+   IfErrors reasonix_stage_mode_done
+   StrCmp $R2 "1" 0 reasonix_stage_mode_done
+   StrCpy $ReasonixStageMode "1"
+
+reasonix_stage_mode_done:

   ; InstallDirRegKey leaves $INSTDIR empty when the InstallLocation value is
   ; missing. Older installers still wrote DisplayIcon, so use its parent folder
@@ -193,12 +214,21 @@ Function reasonix.waitForExecutableUnlock
   StrCpy $0 0

 retry:
-   IfFileExists "$INSTDIR\${PRODUCT_EXECUTABLE}" 0 check_guard
+   IfFileExists "$INSTDIR\${PRODUCT_EXECUTABLE}" 0 check_versioned_target
   ClearErrors
   FileOpen $1 "$INSTDIR\${PRODUCT_EXECUTABLE}" a
   IfErrors locked
   FileClose $1

+check_versioned_target:
+   ; A same-version recovery install replaces this directory transactionally.
+   ; Detect the running active binary before asking the Go activator to rename it.
+   IfFileExists "$INSTDIR\versions\v${INFO_PRODUCTVERSION}\${PRODUCT_EXECUTABLE}" 0 check_guard
+   ClearErrors
+   FileOpen $1 "$INSTDIR\versions\v${INFO_PRODUCTVERSION}\${PRODUCT_EXECUTABLE}" a
+   IfErrors locked
+   FileClose $1
+
 check_guard:
   IfFileExists "$INSTDIR\${REASONIX_GUARD}" 0 check_launcher
   ClearErrors
@@ -253,49 +283,102 @@ FunctionEnd
 Section
    !insertmacro wails.setShellContext

+    ; /REASONIXSTAGE=1: flat six-member payload for 1.18–1.19.1 helpers (and
+    ; the new helper's staging extract). Do not write shortcuts/uninstaller.
+    ; Normal install: versioned-v1 layout under versions/v${INFO_PRODUCTVERSION}/
+    ; with a permanent thin launcher at InstallRoot. Guard is only present in
+    ; STAGE payloads (as the one-shot legacy migrator) and is not persisted on
+    ; a normal install.
+    StrCmp $ReasonixStageMode "1" reasonix_stage_payload
    !insertmacro wails.webview2runtime
-
    Call reasonix.waitForExecutableUnlock
+    Goto reasonix_normal_install

+reasonix_stage_payload:
    SetOutPath $INSTDIR
-
+    !if /FileExists "${REASONIX_PAYLOAD_MANIFEST}"
+    File "/oname=${REASONIX_PAYLOAD_MANIFEST}" "${REASONIX_PAYLOAD_MANIFEST}"
+    !endif
+    !if /FileExists "${REASONIX_PAYLOAD_SIGNATURE}"
+    File "/oname=${REASONIX_PAYLOAD_SIGNATURE}" "${REASONIX_PAYLOAD_SIGNATURE}"
+    !endif
    !insertmacro wails.files
    !if /FileExists "${REASONIX_UPDATE_HELPER}"
    File "/oname=${REASONIX_UPDATE_HELPER}" "${REASONIX_UPDATE_HELPER}"
-    !else
-    !warning "${REASONIX_UPDATE_HELPER} was not found; Windows auto-update will fail safely until the helper is installed."
    !endif
    !if /FileExists "${REASONIX_GUARD}"
    File "/oname=${REASONIX_GUARD}" "${REASONIX_GUARD}"
    !endif
    !if /FileExists "${REASONIX_LAUNCHER}"
    File "/oname=${REASONIX_LAUNCHER}" "${REASONIX_LAUNCHER}"
-    ; Portable archives expose Reasonix.exe as a second copy of the Guard
-    ; launcher. Preserve that layout only when upgrading an existing portable
-    ; directory, and keep the alias in lockstep with the canonical launcher.
-    IfFileExists "$INSTDIR\${REASONIX_PORTABLE_ENTRY}" 0 reasonix_no_portable_entry
-    File "/oname=${REASONIX_PORTABLE_ENTRY}" "${REASONIX_LAUNCHER}"
-reasonix_no_portable_entry:
-    ; Keep the Guard launcher as the target while taking the visible shortcut
-    ; icon from the Wails application. The launcher embeds the same icon too,
-    ; but an explicit icon source prevents stale/generic taskbar pins after an
-    ; in-place upgrade from a launcher build that had no Windows resources.
-    CreateShortcut "$SMPROGRAMS\${INFO_PRODUCTNAME}.lnk" "$INSTDIR\${REASONIX_LAUNCHER}" "launch --detach" "$INSTDIR\${PRODUCT_EXECUTABLE}" 0
-    CreateShortCut "$DESKTOP\${INFO_PRODUCTNAME}.lnk" "$INSTDIR\${REASONIX_LAUNCHER}" "launch --detach" "$INSTDIR\${PRODUCT_EXECUTABLE}" 0
+    !endif
+    !if /FileExists "${REASONIX_CLI}"
+    File "/oname=${REASONIX_CLI}" "${REASONIX_CLI}"
+    !endif
+    Goto reasonix_section_done
+
+reasonix_normal_install:
+    ; Extract into an install-local temporary directory, then let the signed Go
+    ; activator validate the complete release unit, transactionally publish the
+    ; version/root entries, and strictly atomically replace current.json last.
+    ; The normal/recovery installer therefore shares the same commit protocol as
+    ; automatic updates instead of writing live files or current.json in place.
+    System::Call 'kernel32::GetCurrentProcessId() i .R8'
+    CreateDirectory "$INSTDIR\versions"
+    StrCpy $R9 "$INSTDIR\versions\.installer-v${INFO_PRODUCTVERSION}-$R8"
+    RMDir /r "$R9"
+    CreateDirectory "$R9"
+    SetOutPath "$R9"
+    !insertmacro wails.files
+    !if /FileExists "${REASONIX_UPDATE_HELPER}"
+    File "/oname=${REASONIX_UPDATE_HELPER}" "${REASONIX_UPDATE_HELPER}"
    !else
-    CreateShortcut "$SMPROGRAMS\${INFO_PRODUCTNAME}.lnk" "$INSTDIR\${PRODUCT_EXECUTABLE}"
-    CreateShortCut "$DESKTOP\${INFO_PRODUCTNAME}.lnk" "$INSTDIR\${PRODUCT_EXECUTABLE}"
+    !warning "${REASONIX_UPDATE_HELPER} was not found; Windows auto-update will fail safely until the helper is installed."
    !endif
    !if /FileExists "${REASONIX_CLI}"
    File "/oname=${REASONIX_CLI}" "${REASONIX_CLI}"
    !else
    !warning "${REASONIX_CLI} was not found; remote upload installation will be unavailable."
    !endif
+    !if /FileExists "${REASONIX_LAUNCHER}"
+    File "/oname=${REASONIX_LAUNCHER}" "${REASONIX_LAUNCHER}"
+    !endif
+
+    SetOutPath "$PLUGINSDIR"
+    !if /FileExists "${REASONIX_GUARD}"
+    File "/oname=${REASONIX_LAYOUT_INSTALLER}" "${REASONIX_GUARD}"
+    !else
+    !error "${REASONIX_GUARD} was not found; normal installs require the signed layout activator."
+    !endif
+    ExecWait '"$PLUGINSDIR\${REASONIX_LAYOUT_INSTALLER}" --install-root "$INSTDIR" --version "v${INFO_PRODUCTVERSION}" --activate-staging "$R9" --no-relaunch' $0
+    StrCmp $0 "0" reasonix_layout_activated
+    DetailPrint "Reasonix layout activation failed with exit code $0; the previous version remains active."
+    RMDir /r "$R9"
+    SetErrorLevel 1
+    Abort "Reasonix could not activate the verified release. The previous version was left unchanged."
+
+reasonix_layout_activated:
+    RMDir /r "$R9"
+    SetOutPath "$INSTDIR"
+
+    ; Remove flat leftovers from prior 1.18–1.19 installs when overwriting.
+    Delete "$INSTDIR\${PRODUCT_EXECUTABLE}"
+    Delete "$INSTDIR\${REASONIX_GUARD}"
+    Delete "$INSTDIR\${REASONIX_UPDATE_HELPER}"
+
+    !if /FileExists "${REASONIX_LAUNCHER}"
+    CreateShortcut "$SMPROGRAMS\${INFO_PRODUCTNAME}.lnk" "$INSTDIR\${REASONIX_LAUNCHER}" "" "$INSTDIR\versions\v${INFO_PRODUCTVERSION}\${PRODUCT_EXECUTABLE}" 0
+    CreateShortCut "$DESKTOP\${INFO_PRODUCTNAME}.lnk" "$INSTDIR\${REASONIX_LAUNCHER}" "" "$INSTDIR\versions\v${INFO_PRODUCTVERSION}\${PRODUCT_EXECUTABLE}" 0
+    !else
+    CreateShortcut "$SMPROGRAMS\${INFO_PRODUCTNAME}.lnk" "$INSTDIR\versions\v${INFO_PRODUCTVERSION}\${PRODUCT_EXECUTABLE}"
+    CreateShortCut "$DESKTOP\${INFO_PRODUCTNAME}.lnk" "$INSTDIR\versions\v${INFO_PRODUCTVERSION}\${PRODUCT_EXECUTABLE}"
+    !endif

    !insertmacro wails.associateFiles
    !insertmacro wails.associateCustomProtocols
-
    !insertmacro reasonix.writeUninstaller
+
+reasonix_section_done:
 SectionEnd

 Section "uninstall"
@@ -303,13 +386,15 @@ Section "uninstall"

    RMDir /r "$AppData\${PRODUCT_EXECUTABLE}" # Remove the WebView2 DataPath

-    ; Precision uninstall: delete main application files
+    ; Precision uninstall: flat leftovers, thin entry points, and version trees.
    Delete "$INSTDIR\${PRODUCT_EXECUTABLE}"
    Delete "$INSTDIR\${REASONIX_UPDATE_HELPER}"
    Delete "$INSTDIR\${REASONIX_GUARD}"
    Delete "$INSTDIR\${REASONIX_LAUNCHER}"
    Delete "$INSTDIR\${REASONIX_CLI}"
    Delete "$INSTDIR\${REASONIX_PORTABLE_ENTRY}"
+    Delete "$INSTDIR\current.json"
+    RMDir /r "$INSTDIR\versions"

    Delete "$SMPROGRAMS\${INFO_PRODUCTNAME}.lnk"
    Delete "$DESKTOP\${INFO_PRODUCTNAME}.lnk"
@@ -10,10 +10,14 @@
 //	                             encrypted minisign private key in $MINISIGN_PRIVATE_KEY
 //	                             (decrypted with $MINISIGN_PASSWORD).
 //
-//	manifest <dir> <ver> <tag>   Scan <dir> for the per-platform artifacts, compute
+//	manifest <dir> <ver> <tag> [notes-ver]
+//	                             Scan <dir> for the per-platform artifacts, compute
 //	                             size + sha256, and write <dir>/latest.json with GitHub
 //	                             release download URLs. The R2 mirror step rewrites those
 //	                             URLs to the CDN afterwards (url + sig fields together).
+//
+//	windows-payload <dir> <ver> Write a deterministic manifest of the exact
+//	                             executables embedded in the Windows installer.
 package main

 import (
@@ -37,6 +41,11 @@ import (
 // generator and the updater agree on update.PlatformKey output.
 var platforms = []string{"darwin-arm64", "darwin-amd64", "windows-amd64", "windows-arm64", "linux-amd64"}

+var websiteDownloads = map[string]struct{}{
+	"Reasonix-darwin-universal.dmg": {},
+	"Reasonix-windows-amd64.zip":    {},
+}
+
 func main() {
 	if len(os.Args) < 2 {
 		usage()
@@ -46,10 +55,19 @@ func main() {
 	case "sign":
 		err = signFiles(os.Args[2:])
 	case "manifest":
-		if len(os.Args) != 5 {
+		if len(os.Args) != 5 && len(os.Args) != 6 {
 			usage()
 		}
-		err = genManifest(os.Args[2], os.Args[3], os.Args[4])
+		notesVersion := os.Args[3]
+		if len(os.Args) == 6 {
+			notesVersion = os.Args[5]
+		}
+		err = genManifest(os.Args[2], os.Args[3], os.Args[4], notesVersion)
+	case "windows-payload":
+		if len(os.Args) != 4 {
+			usage()
+		}
+		err = genWindowsPayloadManifest(os.Args[2], os.Args[3])
 	case "genkey":
 		if len(os.Args) != 3 {
 			usage()
@@ -70,10 +88,34 @@ func main() {
 }

 func usage() {
-	fmt.Fprintln(os.Stderr, "usage:\n  sign <file>...\n  manifest <dir> <version> <tag>\n  genkey <dir>\n  verify <file>")
+	fmt.Fprintln(os.Stderr, "usage:\n  sign <file>...\n  manifest <dir> <version> <tag> [notes-version]\n  windows-payload <dir> <version>\n  genkey <dir>\n  verify <file>")
 	os.Exit(2)
 }

+func genWindowsPayloadManifest(dir, version string) error {
+	hashes := make(map[string]string)
+	for _, name := range update.WindowsPayloadFileNames() {
+		path := filepath.Join(dir, name)
+		info, err := os.Lstat(path)
+		if err != nil {
+			return fmt.Errorf("Windows payload %s: %w", name, err)
+		}
+		if !info.Mode().IsRegular() {
+			return fmt.Errorf("Windows payload %s is not a regular file", name)
+		}
+		_, sum, err := hashFile(path)
+		if err != nil {
+			return err
+		}
+		hashes[name] = sum
+	}
+	b, err := update.EncodeWindowsPayloadManifest(version, hashes)
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(filepath.Join(dir, update.WindowsPayloadManifestName), b, 0o644)
+}
+
 // verifyFile checks <file> against <file>.minisig using the embedded public key —
 // the same check the updater runs before applying. A self-test that the signing
 // key matches what's compiled in. Returns an error (nonzero exit) on mismatch.
@@ -164,15 +206,29 @@ func signFiles(files []string) error {
 // genManifest scans dir for the per-platform artifacts and writes dir/latest.json.
 // version is the semver compared by the updater (e.g. "v1.1.0"); tag is the GitHub
 // release tag used in download URLs (e.g. "desktop-v1.1.0").
-func genManifest(dir, version, tag string) error {
+//
+// Portable updater channels land in platforms (tarballs/installers). Debian/Ubuntu
+// .deb packages land only in native_packages so older clients keep resolving the
+// tarball under platforms["linux-amd64"].
+func genManifest(dir, version, tag string, notesVersions ...string) error {
 	repo := os.Getenv("GITHUB_REPOSITORY")
 	if repo == "" || repo == "esengine/reasonix" {
 		repo = "esengine/DeepSeek-Reasonix"
 	}
+	notesVersion := version
+	if len(notesVersions) > 1 {
+		return fmt.Errorf("manifest: expected at most one release-notes version")
+	}
+	if len(notesVersions) == 1 {
+		notesVersion = notesVersions[0]
+	}
 	m := update.Manifest{
-		Version:      version,
-		DownloadPage: "https://reasonix.io/?download=desktop#start",
-		Platforms:    map[string]update.Asset{},
+		Version:         version,
+		DownloadPage:    "https://reasonix.io/?download=desktop#start",
+		ReleaseNotesURL: "https://reasonix.io/changelog/" + notesVersion + "/",
+		Platforms:       map[string]update.Asset{},
+		NativePackages:  map[string]update.Asset{},
+		Downloads:       map[string]update.Asset{},
 	}
 	entries, err := os.ReadDir(dir)
 	if err != nil {
@@ -183,8 +239,9 @@ func genManifest(dir, version, tag string) error {
 		if e.IsDir() || strings.HasSuffix(name, ".minisig") || name == "latest.json" {
 			continue
 		}
-		key := matchPlatform(name)
-		if key == "" {
+		key, kind := matchArtifact(name)
+		_, websiteDownload := websiteDownloads[name]
+		if key == "" && !websiteDownload {
 			continue
 		}
 		size, sum, err := hashFile(filepath.Join(dir, name))
@@ -192,12 +249,31 @@ func genManifest(dir, version, tag string) error {
 			return err
 		}
 		url := fmt.Sprintf("https://github.com/%s/releases/download/%s/%s", repo, tag, name)
-		m.Platforms[key] = update.Asset{URL: url, Sig: url + ".minisig", Size: size, SHA256: sum}
-		fmt.Printf("manifest: %s -> %s (%d bytes)\n", key, name, size)
+		asset := update.Asset{URL: url, Sig: url + ".minisig", Size: size, SHA256: sum}
+		if websiteDownload {
+			m.Downloads[name] = asset
+			fmt.Printf("manifest download: %s (%d bytes)\n", name, size)
+		}
+		if key != "" {
+			switch kind {
+			case artifactNative:
+				m.NativePackages[key] = asset
+				fmt.Printf("manifest native: %s -> %s (%d bytes)\n", key, name, size)
+			default:
+				m.Platforms[key] = asset
+				fmt.Printf("manifest: %s -> %s (%d bytes)\n", key, name, size)
+			}
+		}
 	}
 	if len(m.Platforms) == 0 {
 		return fmt.Errorf("manifest: no platform artifacts found in %s", dir)
 	}
+	if len(m.NativePackages) == 0 {
+		m.NativePackages = nil // omit empty map so older tooling sees a clean document
+	}
+	if len(m.Downloads) == 0 {
+		m.Downloads = nil
+	}
 	b, err := json.MarshalIndent(m, "", "  ")
 	if err != nil {
 		return err
@@ -205,24 +281,35 @@ func genManifest(dir, version, tag string) error {
 	return os.WriteFile(filepath.Join(dir, "latest.json"), append(b, '\n'), 0o644)
 }

-// matchPlatform returns the platform key embedded in a file name, or "" if none.
-func matchPlatform(name string) string {
-	// The .deb is a human-download package (like the macOS .dmg); the Linux updater
-	// channel is the .tar.gz. Skip it so it doesn't shadow the tarball's linux-amd64 key.
+const (
+	artifactPortable = "portable"
+	artifactNative   = "native"
+)
+
+// matchArtifact returns the platform key and channel kind embedded in a file name,
+// or ("", "") if the file is not a publishable updater/download artifact.
+func matchArtifact(name string) (key, kind string) {
+	// .deb is the Linux native package channel. Keep it out of platforms so the
+	// tarball remains the portable linux-amd64 key for older clients.
 	if strings.HasSuffix(name, ".deb") {
-		return ""
+		for _, p := range platforms {
+			if strings.Contains(name, p) {
+				return p, artifactNative
+			}
+		}
+		return "", ""
 	}
 	// The Windows updater channel is the per-arch -installer.exe; the portable .zip
 	// is a human download, so skip it or it would shadow the installer's key.
 	if strings.Contains(name, "windows-") && !strings.HasSuffix(name, "-installer.exe") {
-		return ""
+		return "", ""
 	}
 	for _, p := range platforms {
 		if strings.Contains(name, p) {
-			return p
+			return p, artifactPortable
 		}
 	}
-	return ""
+	return "", ""
 }

 // hashFile returns the size and lowercase-hex SHA-256 of a file, streaming it so
@@ -55,6 +55,7 @@ func TestGenManifest(t *testing.T) {
 	names := []string{
 		"Reasonix-darwin-arm64.zip",
 		"Reasonix-darwin-amd64.zip",
+		"Reasonix-darwin-universal.dmg",
 		"Reasonix-windows-amd64-installer.exe",
 		"Reasonix-windows-amd64.zip", // portable download, not the updater channel
 		"Reasonix-windows-arm64-installer.exe",
@@ -88,6 +89,9 @@ func TestGenManifest(t *testing.T) {
 	if m.DownloadPage != "https://reasonix.io/?download=desktop#start" {
 		t.Fatalf("download_page = %q, want official install page", m.DownloadPage)
 	}
+	if m.ReleaseNotesURL != "https://reasonix.io/changelog/v1.2.0/" {
+		t.Fatalf("release_notes_url = %q, want exact version history", m.ReleaseNotesURL)
+	}
 	if len(m.Platforms) != 5 {
 		t.Fatalf("want 5 platforms, got %d: %v", len(m.Platforms), m.Platforms)
 	}
@@ -114,8 +118,8 @@ func TestGenManifest(t *testing.T) {
 	if !strings.HasSuffix(arm.URL, "/Reasonix-windows-arm64-installer.exe") {
 		t.Fatalf("windows-arm64 url = %q, want the installer, not the portable zip", arm.URL)
 	}
-	// The Linux updater channel must stay the .tar.gz; the co-located .deb is a
-	// human download and must not shadow the linux-amd64 key.
+	// The Linux portable channel stays the .tar.gz; the co-located .deb lands
+	// only in native_packages so older clients keep resolving platforms["linux-amd64"].
 	lin, ok := m.Platforms["linux-amd64"]
 	if !ok {
 		t.Fatal("linux-amd64 missing")
@@ -123,4 +127,108 @@ func TestGenManifest(t *testing.T) {
 	if !strings.HasSuffix(lin.URL, "/Reasonix-linux-amd64.tar.gz") {
 		t.Fatalf("linux-amd64 url = %q, want the .tar.gz, not the .deb", lin.URL)
 	}
+	if lin.Sig == "" || lin.SHA256 == "" || lin.Size == 0 {
+		t.Fatalf("linux portable asset incomplete: %+v", lin)
+	}
+	deb, ok := m.NativePackages["linux-amd64"]
+	if !ok {
+		t.Fatal("native_packages linux-amd64 missing")
+	}
+	if !strings.HasSuffix(deb.URL, "/Reasonix-linux-amd64.deb") {
+		t.Fatalf("native linux-amd64 url = %q, want the .deb", deb.URL)
+	}
+	if deb.Sig != deb.URL+".minisig" || deb.SHA256 == "" || deb.Size == 0 {
+		t.Fatalf("native linux asset incomplete: %+v", deb)
+	}
+	if len(m.Downloads) != 2 {
+		t.Fatalf("want 2 website downloads, got %d: %+v", len(m.Downloads), m.Downloads)
+	}
+	for _, name := range []string{"Reasonix-darwin-universal.dmg", "Reasonix-windows-amd64.zip"} {
+		asset, ok := m.Downloads[name]
+		if !ok {
+			t.Fatalf("website download %q missing", name)
+		}
+		if !strings.HasSuffix(asset.URL, "/"+name) ||
+			asset.Sig != asset.URL+".minisig" ||
+			asset.SHA256 == "" ||
+			asset.Size == 0 {
+			t.Fatalf("website download %q incomplete: %+v", name, asset)
+		}
+	}
+}
+
+func TestGenManifestCanReuseStableNotesForStandaloneRC(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "Reasonix-linux-amd64.tar.gz"), []byte("rc"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := genManifest(dir, "v1.3.0-rc.1", "desktop-v1.3.0-rc.1", "v1.3.0"); err != nil {
+		t.Fatalf("genManifest: %v", err)
+	}
+	raw, err := os.ReadFile(filepath.Join(dir, "latest.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m update.Manifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	if m.ReleaseNotesURL != "https://reasonix.io/changelog/v1.3.0/" {
+		t.Fatalf("release_notes_url = %q, want stable base history", m.ReleaseNotesURL)
+	}
+}
+
+// TestGenManifestIgnoresUnknownNativePackages ensures a .deb without a known
+// platform key is skipped rather than inventing a native_packages entry.
+func TestGenManifestIgnoresUnknownNativePackages(t *testing.T) {
+	dir := t.TempDir()
+	for _, n := range []string{
+		"Reasonix-linux-amd64.tar.gz",
+		"Reasonix-mystery.deb",
+	} {
+		if err := os.WriteFile(filepath.Join(dir, n), []byte(n), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("GITHUB_REPOSITORY", "esengine/DeepSeek-Reasonix")
+	if err := genManifest(dir, "v1.2.0", "desktop-v1.2.0"); err != nil {
+		t.Fatalf("genManifest: %v", err)
+	}
+	raw, err := os.ReadFile(filepath.Join(dir, "latest.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m update.Manifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	if len(m.NativePackages) != 0 {
+		t.Fatalf("unexpected native_packages: %+v", m.NativePackages)
+	}
+}
+
+func TestGenWindowsPayloadManifestHashesExactReleaseUnit(t *testing.T) {
+	dir := t.TempDir()
+	for _, name := range update.WindowsPayloadFileNames() {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("payload:"+name), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := genWindowsPayloadManifest(dir, "v2.3.4"); err != nil {
+		t.Fatal(err)
+	}
+	b, err := os.ReadFile(filepath.Join(dir, update.WindowsPayloadManifestName))
+	if err != nil {
+		t.Fatal(err)
+	}
+	hashes, err := update.DecodeWindowsPayloadManifest(b, "v2.3.4")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range update.WindowsPayloadFileNames() {
+		want := update.WindowsPayloadSHA256([]byte("payload:" + name))
+		if hashes[name] != want {
+			t.Fatalf("manifest hash for %s = %q, want %q", name, hashes[name], want)
+		}
+	}
 }
@@ -4,10 +4,10 @@ import "fmt"

 func installerCommandLine(installer, dir string) string {
 	// Auto-updates use a dedicated visible progress mode instead of NSIS /S.
-	// The installer skips its welcome and directory pages in this mode, keeps
-	// the current install directory fixed, and closes itself after the file copy
-	// completes so this helper can relaunch Reasonix.
-	line := fmt.Sprintf(`"%s" /REASONIXUPDATE=1`, installer)
+	// The current helper also requires staging-only extraction: NSIS never writes
+	// the live install, and the helper compare-and-publishes the claimed release
+	// unit after validating every staged member.
+	line := fmt.Sprintf(`"%s" /REASONIXUPDATE=1 /REASONIXSTAGE=1`, installer)
 	if dir != "" {
 		line += " /D=" + dir
 	}
@@ -7,7 +7,7 @@ import (

 func TestInstallerCommandLineUsesVisibleUpdateModeAndLeavesDFlagLast(t *testing.T) {
 	got := installerCommandLine(`C:\Temp\Reasonix Installer.exe`, `D:\Tools\Reasonix App`)
-	want := `"C:\Temp\Reasonix Installer.exe" /REASONIXUPDATE=1 /D=D:\Tools\Reasonix App`
+	want := `"C:\Temp\Reasonix Installer.exe" /REASONIXUPDATE=1 /REASONIXSTAGE=1 /D=D:\Tools\Reasonix App`
 	if got != want {
 		t.Fatalf("installerCommandLine = %q, want %q", got, want)
 	}
@@ -17,4 +17,7 @@ func TestInstallerCommandLineUsesVisibleUpdateModeAndLeavesDFlagLast(t *testing.
 	if !strings.HasSuffix(got, `/D=D:\Tools\Reasonix App`) {
 		t.Fatalf("/D= must be the final unquoted NSIS token, got %q", got)
 	}
+	if !strings.Contains(got, " /REASONIXSTAGE=1") {
+		t.Fatalf("auto-update must extract away from the live install, got %q", got)
+	}
 }
@@ -0,0 +1,10 @@
+//go:build !windows
+
+package main
+
+import "os"
+
+// Windows verifies each executable with the OS Authenticode policy while the
+// same read handle is held. Non-Windows builds keep the release-unit loader
+// testable without importing platform-specific trust APIs.
+var readVerifiedWindowsStagedPayloadFn = os.ReadFile
@@ -0,0 +1,97 @@
+//go:build windows
+
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+)
+
+var readVerifiedWindowsStagedPayloadFn = readVerifiedWindowsStagedPayload
+
+// readVerifiedWindowsStagedPayload verifies the Authenticode signature and
+// reads the payload through one handle that disallows concurrent writes,
+// deletes, and renames. The bytes handed to the publisher therefore cannot
+// change between signature verification and publication.
+func readVerifiedWindowsStagedPayload(path string) ([]byte, error) {
+	info, err := os.Lstat(path)
+	if err != nil {
+		return nil, err
+	}
+	if !info.Mode().IsRegular() {
+		return nil, fmt.Errorf("staged payload is not a regular file")
+	}
+	path16, err := windows.UTF16PtrFromString(path)
+	if err != nil {
+		return nil, err
+	}
+	handle, err := windows.CreateFile(
+		path16,
+		windows.GENERIC_READ,
+		windows.FILE_SHARE_READ,
+		nil,
+		windows.OPEN_EXISTING,
+		windows.FILE_ATTRIBUTE_NORMAL|windows.FILE_FLAG_SEQUENTIAL_SCAN,
+		0,
+	)
+	if err != nil {
+		return nil, err
+	}
+	file := os.NewFile(uintptr(handle), path)
+	if file == nil {
+		_ = windows.CloseHandle(handle)
+		return nil, fmt.Errorf("open staged payload handle")
+	}
+	defer file.Close()
+
+	fileInfo, err := file.Stat()
+	if err != nil {
+		return nil, err
+	}
+	if !fileInfo.Mode().IsRegular() {
+		return nil, fmt.Errorf("staged payload is not a regular file")
+	}
+
+	trustFile := &windows.WinTrustFileInfo{
+		Size:     uint32(unsafe.Sizeof(windows.WinTrustFileInfo{})),
+		FilePath: path16,
+		File:     handle,
+	}
+	trustData := &windows.WinTrustData{
+		Size:                            uint32(unsafe.Sizeof(windows.WinTrustData{})),
+		UIChoice:                        windows.WTD_UI_NONE,
+		RevocationChecks:                windows.WTD_REVOKE_NONE,
+		UnionChoice:                     windows.WTD_CHOICE_FILE,
+		FileOrCatalogOrBlobOrSgnrOrCert: unsafe.Pointer(trustFile),
+		StateAction:                     windows.WTD_STATEACTION_VERIFY,
+		UIContext:                       windows.WTD_UICONTEXT_EXECUTE,
+	}
+	verifyErr := windows.WinVerifyTrustEx(
+		windows.InvalidHWND,
+		&windows.WINTRUST_ACTION_GENERIC_VERIFY_V2,
+		trustData,
+	)
+	trustData.StateAction = windows.WTD_STATEACTION_CLOSE
+	closeErr := windows.WinVerifyTrustEx(
+		windows.InvalidHWND,
+		&windows.WINTRUST_ACTION_GENERIC_VERIFY_V2,
+		trustData,
+	)
+	if verifyErr != nil {
+		if closeErr != nil {
+			return nil, fmt.Errorf("Authenticode verification failed: %v (release trust state: %w)", verifyErr, closeErr)
+		}
+		return nil, fmt.Errorf("Authenticode verification failed: %w", verifyErr)
+	}
+	if closeErr != nil {
+		return nil, fmt.Errorf("release Authenticode verification state: %w", closeErr)
+	}
+	if _, err := file.Seek(0, io.SeekStart); err != nil {
+		return nil, err
+	}
+	return io.ReadAll(file)
+}
@@ -0,0 +1,489 @@
+//go:build linux
+
+// Command reasonix-update-helper (Linux) installs a verified .deb under Polkit.
+// It is invoked only via pkexec with fixed argv and re-validates every input as
+// root before calling apt-get. The unprivileged desktop process never runs apt.
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"strconv"
+	"strings"
+	"syscall"
+
+	"reasonix/desktop/internal/update"
+)
+
+// Stable exit codes observed by the desktop installer.
+const (
+	exitOK              = 0
+	exitUsage           = 2
+	exitNotRoot         = 10
+	exitBadInput        = 11
+	exitVerifyFailed    = 12
+	exitPackageRejected = 13
+	exitBusy            = 14
+	exitInstallFailed   = 15
+	exitPostVerify      = 16
+)
+
+const (
+	packageName   = "reasonix-desktop"
+	dpkgDebPath   = "/usr/bin/dpkg-deb"
+	dpkgQueryPath = "/usr/bin/dpkg-query"
+	dpkgPath      = "/usr/bin/dpkg"
+	aptGetPath    = "/usr/bin/apt-get"
+
+	// maxInputBytes bounds untrusted package/signature files before they are
+	// copied into the root temp directory (desktop .deb + minisig).
+	maxInputBytes = 512 << 20 // 512 MiB
+
+	// phasePrefix is a single-line protocol the desktop parses from stderr so
+	// the UI can leave "authorizing" once Polkit has launched this helper and
+	// validation finished, before apt-get starts.
+	phasePrefix = "REASONIX_UPDATE_PHASE="
+)
+
+type helperResult struct {
+	OK      bool   `json:"ok"`
+	Version string `json:"version,omitempty"`
+	Error   string `json:"error,omitempty"`
+	Code    string `json:"code,omitempty"`
+}
+
+// installDeps holds the privileged install seams. Production uses realDeps();
+// tests inject fakes so every branch is deterministic without root/apt.
+type installDeps struct {
+	geteuid          func() int
+	getenv           func(string) string
+	mkTempDir        func() (string, error)
+	removeAll        func(string) error
+	copyOwnedRegular func(src, dst string, mode os.FileMode, ownerUID int, maxBytes int64) error
+	readFile         func(string) ([]byte, error)
+	verify           func(data, sig []byte) error
+	inspectDeb       func(path string) (debIdentity, error)
+	installedVersion func() (string, error)
+	compareVersions  func(a, b string) (int, error)
+	aptInstall       func(pkgPath string, allowDowngrade bool) error
+	verifyInstalled  func(want string) error
+	writePhase       func(phase string)
+	writeResult      func(helperResult)
+	goArch           string
+	maxInputBytes    int64
+}
+
+func realDeps() installDeps {
+	return installDeps{
+		geteuid:          os.Geteuid,
+		getenv:           os.Getenv,
+		mkTempDir:        func() (string, error) { return os.MkdirTemp("", "reasonix-update-*") },
+		removeAll:        os.RemoveAll,
+		copyOwnedRegular: copyOwnedRegularFile,
+		readFile:         os.ReadFile,
+		verify:           update.Verify,
+		inspectDeb:       inspectDeb,
+		installedVersion: installedPackageVersion,
+		compareVersions:  compareDebVersions,
+		aptInstall:       aptInstallOnlyUpgrade,
+		verifyInstalled:  verifyInstalled,
+		writePhase:       writePhaseLine,
+		writeResult:      writeResultJSON,
+		goArch:           runtime.GOARCH,
+		maxInputBytes:    maxInputBytes,
+	}
+}
+
+func main() {
+	os.Exit(run(os.Args[1:]))
+}
+
+func run(args []string) int {
+	return runWith(realDeps(), args)
+}
+
+func runWith(d installDeps, args []string) int {
+	if len(args) == 0 {
+		d.writeResult(helperResult{OK: false, Error: "missing command", Code: "usage"})
+		return exitUsage
+	}
+	switch args[0] {
+	case "install":
+		return runInstall(d, args[1:])
+	default:
+		d.writeResult(helperResult{OK: false, Error: "unknown command", Code: "usage"})
+		return exitUsage
+	}
+}
+
+func runInstall(d installDeps, args []string) int {
+	fs := flag.NewFlagSet("install", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var packagePath, signaturePath string
+	fs.StringVar(&packagePath, "package", "", "path to the verified .deb")
+	fs.StringVar(&signaturePath, "signature", "", "path to the detached .minisig")
+	if err := fs.Parse(args); err != nil {
+		d.writeResult(helperResult{OK: false, Error: "invalid arguments", Code: "usage"})
+		return exitUsage
+	}
+	if packagePath == "" || signaturePath == "" || fs.NArg() != 0 {
+		d.writeResult(helperResult{OK: false, Error: "install requires --package and --signature", Code: "usage"})
+		return exitUsage
+	}
+
+	if d.geteuid() != 0 {
+		d.writeResult(helperResult{OK: false, Error: "helper must run as root", Code: "not_root"})
+		return exitNotRoot
+	}
+	pkUID, err := strconv.Atoi(strings.TrimSpace(d.getenv("PKEXEC_UID")))
+	if err != nil || pkUID < 0 {
+		d.writeResult(helperResult{OK: false, Error: "missing or invalid PKEXEC_UID", Code: "not_root"})
+		return exitNotRoot
+	}
+
+	tmpDir, err := d.mkTempDir()
+	if err != nil {
+		d.writeResult(helperResult{OK: false, Error: "create temp dir failed", Code: "install_failed"})
+		return exitInstallFailed
+	}
+	// Ensure root-only access before any untrusted bytes land here.
+	if err := os.Chmod(tmpDir, 0o700); err != nil {
+		_ = d.removeAll(tmpDir)
+		d.writeResult(helperResult{OK: false, Error: "secure temp dir failed", Code: "install_failed"})
+		return exitInstallFailed
+	}
+	defer func() { _ = d.removeAll(tmpDir) }()
+
+	maxBytes := d.maxInputBytes
+	if maxBytes <= 0 {
+		maxBytes = maxInputBytes
+	}
+	pkgCopy := filepath.Join(tmpDir, "package.deb")
+	sigCopy := filepath.Join(tmpDir, "package.deb.minisig")
+	if err := d.copyOwnedRegular(packagePath, pkgCopy, 0o600, pkUID, maxBytes); err != nil {
+		d.writeResult(helperResult{OK: false, Error: "invalid package input", Code: "bad_input"})
+		return exitBadInput
+	}
+	if err := d.copyOwnedRegular(signaturePath, sigCopy, 0o600, pkUID, maxBytes); err != nil {
+		d.writeResult(helperResult{OK: false, Error: "invalid signature input", Code: "bad_input"})
+		return exitBadInput
+	}
+
+	pkgData, err := d.readFile(pkgCopy)
+	if err != nil {
+		d.writeResult(helperResult{OK: false, Error: "read package failed", Code: "bad_input"})
+		return exitBadInput
+	}
+	sigData, err := d.readFile(sigCopy)
+	if err != nil {
+		d.writeResult(helperResult{OK: false, Error: "read signature failed", Code: "bad_input"})
+		return exitBadInput
+	}
+	// Re-verify as root; never trust the unprivileged process's prior check.
+	if err := d.verify(pkgData, sigData); err != nil {
+		d.writeResult(helperResult{OK: false, Error: "signature verification failed", Code: "verify_failed"})
+		return exitVerifyFailed
+	}
+
+	candidate, err := d.inspectDeb(pkgCopy)
+	if err != nil {
+		d.writeResult(helperResult{OK: false, Error: err.Error(), Code: "package_rejected"})
+		return exitPackageRejected
+	}
+	if err := acceptDebIdentity(candidate, d.goArch); err != nil {
+		d.writeResult(helperResult{OK: false, Error: err.Error(), Code: "package_rejected"})
+		return exitPackageRejected
+	}
+
+	installed, err := d.installedVersion()
+	if err != nil {
+		d.writeResult(helperResult{OK: false, Error: err.Error(), Code: "package_rejected"})
+		return exitPackageRejected
+	}
+	cmp, err := d.compareVersions(candidate.Version, installed)
+	if err != nil {
+		d.writeResult(helperResult{OK: false, Error: "version compare failed", Code: "package_rejected"})
+		return exitPackageRejected
+	}
+	allowDowngrade, err := acceptVersionTransition(cmp, candidate.Version, installed)
+	if err != nil {
+		d.writeResult(helperResult{OK: false, Error: err.Error(), Code: "package_rejected"})
+		return exitPackageRejected
+	}
+
+	// Polkit already authorized this process; validation is complete. Tell the
+	// desktop to leave "authorizing" before the long apt-get call.
+	d.writePhase("installing")
+
+	if err := d.aptInstall(pkgCopy, allowDowngrade); err != nil {
+		code := "install_failed"
+		exit := exitInstallFailed
+		if isPackageManagerBusy(err) {
+			code = "package_manager_busy"
+			exit = exitBusy
+		}
+		d.writeResult(helperResult{OK: false, Error: sanitizeHelperError(err), Code: code})
+		return exit
+	}
+
+	if err := d.verifyInstalled(candidate.Version); err != nil {
+		d.writeResult(helperResult{OK: false, Error: err.Error(), Code: "package_verify_failed"})
+		return exitPostVerify
+	}
+
+	d.writeResult(helperResult{OK: true, Version: candidate.Version})
+	return exitOK
+}
+
+type debIdentity struct {
+	Package string
+	Version string
+	Arch    string
+}
+
+// acceptDebIdentity enforces package name and architecture. Pure for tests.
+func acceptDebIdentity(id debIdentity, goArch string) error {
+	if id.Package != packageName {
+		return errors.New("package name rejected")
+	}
+	wantArch := goArch
+	if wantArch == "386" {
+		wantArch = "i386"
+	}
+	if id.Arch != wantArch && id.Arch != "all" {
+		return errors.New("package architecture rejected")
+	}
+	if id.Version == "" {
+		return errors.New("package version missing")
+	}
+	return nil
+}
+
+var (
+	stableDebVersionRE  = regexp.MustCompile(`^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$`)
+	previewDebVersionRE = regexp.MustCompile(`^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)~preview\.(0|[1-9][0-9]*)$`)
+)
+
+// acceptVersionTransition permits ordinary upgrades and the one intentional
+// downgrade: replacing a public Preview package with a public Stable package
+// after the user switches channels.
+func acceptVersionTransition(cmp int, candidate, installed string) (bool, error) {
+	switch {
+	case cmp > 0:
+		return false, nil
+	case cmp == 0:
+		return false, errors.New("candidate version is not strictly newer")
+	case stableDebVersionRE.MatchString(candidate) && previewDebVersionRE.MatchString(installed):
+		return true, nil
+	default:
+		return false, errors.New("candidate downgrade is not an allowed preview-to-stable transition")
+	}
+}
+
+// aptInstallArgv is the fixed absolute apt-get argv (never shell). Pure for tests.
+func aptInstallArgv(pkgPath string, allowDowngrade bool) []string {
+	argv := []string{
+		aptGetPath,
+		"install",
+		"--assume-yes",
+		"--only-upgrade",
+		"--no-remove",
+	}
+	if allowDowngrade {
+		argv = append(argv, "--allow-downgrades")
+	}
+	return append(argv, pkgPath)
+}
+
+func inspectDeb(path string) (debIdentity, error) {
+	pkg, err := dpkgDebField(path, "Package")
+	if err != nil {
+		return debIdentity{}, errors.New("dpkg-deb inspection failed")
+	}
+	ver, err := dpkgDebField(path, "Version")
+	if err != nil {
+		return debIdentity{}, errors.New("dpkg-deb inspection failed")
+	}
+	arch, err := dpkgDebField(path, "Architecture")
+	if err != nil {
+		return debIdentity{}, errors.New("dpkg-deb inspection failed")
+	}
+	return debIdentity{Package: pkg, Version: ver, Arch: arch}, nil
+}
+
+func dpkgDebField(path, field string) (string, error) {
+	out, err := exec.Command(dpkgDebPath, "-f", path, field).Output()
+	if err != nil {
+		return "", err
+	}
+	return strings.TrimSpace(string(out)), nil
+}
+
+func installedPackageVersion() (string, error) {
+	out, err := exec.Command(dpkgQueryPath, "-W", "-f=${Version}", packageName).Output()
+	if err != nil {
+		return "", errors.New("installed package not found")
+	}
+	v := strings.TrimSpace(string(out))
+	if v == "" {
+		return "", errors.New("installed package version empty")
+	}
+	return v, nil
+}
+
+// compareDebVersions returns >0 when a > b using dpkg --compare-versions.
+func compareDebVersions(a, b string) (int, error) {
+	if err := exec.Command(dpkgPath, "--compare-versions", a, "gt", b).Run(); err == nil {
+		return 1, nil
+	}
+	if err := exec.Command(dpkgPath, "--compare-versions", a, "eq", b).Run(); err == nil {
+		return 0, nil
+	}
+	if err := exec.Command(dpkgPath, "--compare-versions", a, "lt", b).Run(); err == nil {
+		return -1, nil
+	}
+	return 0, errors.New("compare-versions failed")
+}
+
+func aptInstallOnlyUpgrade(pkgPath string, allowDowngrade bool) error {
+	argv := aptInstallArgv(pkgPath, allowDowngrade)
+	cmd := exec.Command(argv[0], argv[1:]...)
+	// Fixed absolute argv only — never shell.
+	cmd.Env = append(os.Environ(), "DEBIAN_FRONTEND=noninteractive")
+	var stderr bytes.Buffer
+	cmd.Stdout = io.Discard
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("%w: %s", err, strings.TrimSpace(stderr.String()))
+	}
+	return nil
+}
+
+func verifyInstalled(wantVersion string) error {
+	out, err := exec.Command(dpkgQueryPath, "-W", "-f=${Status}\n${Version}", packageName).Output()
+	if err != nil {
+		return errors.New("post-install dpkg-query failed")
+	}
+	lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+	if len(lines) < 2 {
+		return errors.New("post-install package state incomplete")
+	}
+	if strings.TrimSpace(lines[0]) != "install ok installed" {
+		return errors.New("package not in install ok installed state")
+	}
+	if strings.TrimSpace(lines[1]) != wantVersion {
+		return errors.New("installed version mismatch")
+	}
+	return nil
+}
+
+// copyOwnedRegularFile opens src with O_NOFOLLOW only (fail closed — no Lstat/Open
+// fallback), requires a regular file owned by ownerUID, enforces maxBytes, and
+// writes a root-owned copy at dst. Ownership is checked on the opened fd.
+func copyOwnedRegularFile(src, dst string, mode os.FileMode, ownerUID int, maxBytes int64) error {
+	f, err := os.OpenFile(src, os.O_RDONLY|syscall.O_NOFOLLOW, 0)
+	if err != nil {
+		// Fail closed: never fall back to a followable open (TOCTOU).
+		return fmt.Errorf("open without following links: %w", err)
+	}
+	defer f.Close()
+
+	info, err := f.Stat()
+	if err != nil {
+		return err
+	}
+	if !info.Mode().IsRegular() {
+		return errors.New("not a regular file")
+	}
+	if maxBytes > 0 && info.Size() > maxBytes {
+		return errors.New("input exceeds size bound")
+	}
+	st, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return errors.New("stat owner unavailable")
+	}
+	if int(st.Uid) != ownerUID {
+		return errors.New("input owner does not match PKEXEC_UID")
+	}
+
+	out, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_EXCL, mode)
+	if err != nil {
+		return err
+	}
+	defer out.Close()
+	// Cap the copy even if size grew after Stat (regular files can still be
+	// truncated/appended by the owner on some filesystems; bound the bytes we take).
+	limited := io.LimitReader(f, maxBytes+1)
+	n, err := io.Copy(out, limited)
+	if err != nil {
+		return err
+	}
+	if maxBytes > 0 && n > maxBytes {
+		return errors.New("input exceeds size bound")
+	}
+	return out.Close()
+}
+
+func isPackageManagerBusy(err error) bool {
+	if err == nil {
+		return false
+	}
+	low := strings.ToLower(err.Error())
+	return strings.Contains(low, "could not get lock") ||
+		strings.Contains(low, "unable to acquire the dpkg frontend lock") ||
+		strings.Contains(low, "is another process using it") ||
+		strings.Contains(low, "dpkg frontend lock")
+}
+
+// sanitizeHelperError strips absolute paths from helper diagnostics so the
+// desktop UI never surfaces user home directories.
+func sanitizeHelperError(err error) string {
+	if err == nil {
+		return "install failed"
+	}
+	msg := err.Error()
+	// Drop anything that looks like an absolute path segment.
+	fields := strings.Fields(msg)
+	for i, f := range fields {
+		if strings.HasPrefix(f, "/") {
+			fields[i] = "<path>"
+		}
+	}
+	out := strings.Join(fields, " ")
+	if out == "" {
+		return "install failed"
+	}
+	if len(out) > 240 {
+		out = out[:240]
+	}
+	return out
+}
+
+func writePhaseLine(phase string) {
+	// Single line, no user paths — desktop parses this while the helper runs.
+	fmt.Fprintf(os.Stderr, "%s%s\n", phasePrefix, phase)
+}
+
+func writeResultJSON(r helperResult) {
+	enc := json.NewEncoder(os.Stdout)
+	_ = enc.Encode(r)
+}
+
+// parsePhaseLine extracts a progress phase from a helper stderr line.
+func parsePhaseLine(line string) (phase string, ok bool) {
+	line = strings.TrimSpace(line)
+	if !strings.HasPrefix(line, phasePrefix) {
+		return "", false
+	}
+	phase = strings.TrimSpace(strings.TrimPrefix(line, phasePrefix))
+	return phase, phase != ""
+}
@@ -0,0 +1,596 @@
+//go:build linux
+
+package main
+
+import (
+	"crypto/rand"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"aead.dev/minisign"
+)
+
+func TestSanitizeHelperErrorStripsPaths(t *testing.T) {
+	err := errors.New("/home/user/cache/foo.deb locked by /var/lib/dpkg/lock")
+	got := sanitizeHelperError(err)
+	if strings.Contains(got, "/home/") || strings.Contains(got, "/var/") {
+		t.Fatalf("path leaked: %q", got)
+	}
+	if !strings.Contains(got, "<path>") {
+		t.Fatalf("expected path redaction, got %q", got)
+	}
+}
+
+func TestIsPackageManagerBusy(t *testing.T) {
+	if !isPackageManagerBusy(errors.New("Could not get lock /var/lib/dpkg/lock-frontend")) {
+		t.Fatal("expected busy detection")
+	}
+	if isPackageManagerBusy(errors.New("dependency problems prevent configuration")) {
+		t.Fatal("dependency failure is not busy")
+	}
+}
+
+func TestAcceptDebIdentity(t *testing.T) {
+	cases := []struct {
+		name    string
+		id      debIdentity
+		goArch  string
+		wantErr string
+	}{
+		{
+			name:   "ok amd64",
+			id:     debIdentity{Package: packageName, Version: "1.2.3", Arch: "amd64"},
+			goArch: "amd64",
+		},
+		{
+			name:    "wrong package",
+			id:      debIdentity{Package: "evil", Version: "1.2.3", Arch: "amd64"},
+			goArch:  "amd64",
+			wantErr: "package name rejected",
+		},
+		{
+			name:    "wrong arch",
+			id:      debIdentity{Package: packageName, Version: "1.2.3", Arch: "arm64"},
+			goArch:  "amd64",
+			wantErr: "package architecture rejected",
+		},
+		{
+			name:   "arch all allowed",
+			id:     debIdentity{Package: packageName, Version: "1.2.3", Arch: "all"},
+			goArch: "amd64",
+		},
+		{
+			name:    "missing version",
+			id:      debIdentity{Package: packageName, Version: "", Arch: "amd64"},
+			goArch:  "amd64",
+			wantErr: "package version missing",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := acceptDebIdentity(tc.id, tc.goArch)
+			if tc.wantErr == "" {
+				if err != nil {
+					t.Fatalf("unexpected err: %v", err)
+				}
+				return
+			}
+			if err == nil || err.Error() != tc.wantErr {
+				t.Fatalf("err = %v, want %q", err, tc.wantErr)
+			}
+		})
+	}
+}
+
+func TestAcceptVersionTransition(t *testing.T) {
+	tests := []struct {
+		name          string
+		cmp           int
+		candidate     string
+		installed     string
+		wantDowngrade bool
+		wantErr       bool
+	}{
+		{name: "ordinary upgrade", cmp: 1, candidate: "1.3.0", installed: "1.2.0"},
+		{name: "equal rejected", cmp: 0, candidate: "1.2.0", installed: "1.2.0", wantErr: true},
+		{name: "preview to older stable", cmp: -1, candidate: "1.2.0", installed: "1.3.0~preview.1", wantDowngrade: true},
+		{name: "stable to older stable rejected", cmp: -1, candidate: "1.2.0", installed: "1.3.0", wantErr: true},
+		{name: "preview to older preview rejected", cmp: -1, candidate: "1.2.0~preview.1", installed: "1.3.0~preview.1", wantErr: true},
+		{name: "rc to stable rejected", cmp: -1, candidate: "1.2.0", installed: "1.3.0~rc.1", wantErr: true},
+		{name: "internal preview rejected", cmp: -1, candidate: "1.2.0", installed: "1.3.0~preview.1+internal", wantErr: true},
+		{name: "malformed stable rejected", cmp: -1, candidate: "01.2.0", installed: "1.3.0~preview.1", wantErr: true},
+		{name: "malformed preview rejected", cmp: -1, candidate: "1.2.0", installed: "1.3.0~preview.01", wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			allowDowngrade, err := acceptVersionTransition(tt.cmp, tt.candidate, tt.installed)
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("error = %v, wantErr %v", err, tt.wantErr)
+			}
+			if allowDowngrade != tt.wantDowngrade {
+				t.Fatalf("allowDowngrade = %v, want %v", allowDowngrade, tt.wantDowngrade)
+			}
+		})
+	}
+}
+
+func TestAptInstallArgvFixed(t *testing.T) {
+	argv := aptInstallArgv("/tmp/pkg.deb", false)
+	want := []string{
+		"/usr/bin/apt-get",
+		"install",
+		"--assume-yes",
+		"--only-upgrade",
+		"--no-remove",
+		"/tmp/pkg.deb",
+	}
+	if len(argv) != len(want) {
+		t.Fatalf("argv = %v", argv)
+	}
+	for i := range want {
+		if argv[i] != want[i] {
+			t.Fatalf("argv[%d] = %q, want %q", i, argv[i], want[i])
+		}
+	}
+	joined := strings.Join(argv, " ")
+	for _, bad := range []string{"--allow-unauthenticated", "--allow-downgrades", "--force-yes", "sh -c"} {
+		if strings.Contains(joined, bad) {
+			t.Fatalf("forbidden apt option present: %s in %v", bad, argv)
+		}
+	}
+
+	downgradeArgv := aptInstallArgv("/tmp/pkg.deb", true)
+	if strings.Count(strings.Join(downgradeArgv, " "), "--allow-downgrades") != 1 {
+		t.Fatalf("constrained downgrade argv = %v", downgradeArgv)
+	}
+	if downgradeArgv[len(downgradeArgv)-1] != "/tmp/pkg.deb" {
+		t.Fatalf("package path must remain the final fixed argument: %v", downgradeArgv)
+	}
+}
+
+func TestParsePhaseLine(t *testing.T) {
+	phase, ok := parsePhaseLine(phasePrefix + "installing")
+	if !ok || phase != "installing" {
+		t.Fatalf("got %q %v", phase, ok)
+	}
+	if _, ok := parsePhaseLine("noise"); ok {
+		t.Fatal("noise should not parse")
+	}
+}
+
+func TestCopyOwnedRegularFileRejectsSymlinkFailClosed(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "real.deb")
+	if err := os.WriteFile(target, []byte("deb"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	link := filepath.Join(dir, "link.deb")
+	if err := os.Symlink(target, link); err != nil {
+		t.Fatal(err)
+	}
+	dst := filepath.Join(dir, "out.deb")
+	// Any UID — O_NOFOLLOW must fail before ownership is checked.
+	if err := copyOwnedRegularFile(link, dst, 0o600, os.Getuid(), maxInputBytes); err == nil {
+		t.Fatal("symlink must be rejected without fallback open")
+	}
+}
+
+func TestCopyOwnedRegularFileRejectsWrongOwner(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("running as root; cannot construct a non-self-owned file cheaply")
+	}
+	dir := t.TempDir()
+	src := filepath.Join(dir, "in.deb")
+	if err := os.WriteFile(src, []byte("package-bytes"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	dst := filepath.Join(dir, "out.deb")
+	// Claim the file must be owned by root while the test user owns it.
+	if err := copyOwnedRegularFile(src, dst, 0o600, 0, maxInputBytes); err == nil {
+		t.Fatal("wrong owner must be rejected")
+	}
+}
+
+func TestCopyOwnedRegularFileRejectsOversize(t *testing.T) {
+	dir := t.TempDir()
+	src := filepath.Join(dir, "in.deb")
+	if err := os.WriteFile(src, []byte("0123456789"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	dst := filepath.Join(dir, "out.deb")
+	if err := copyOwnedRegularFile(src, dst, 0o600, os.Getuid(), 4); err == nil {
+		t.Fatal("oversize input must be rejected")
+	}
+}
+
+func TestCopyOwnedRegularFileCopiesMatchingOwner(t *testing.T) {
+	dir := t.TempDir()
+	src := filepath.Join(dir, "in.deb")
+	payload := []byte("package-bytes")
+	if err := os.WriteFile(src, payload, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	dst := filepath.Join(dir, "out.deb")
+	if err := copyOwnedRegularFile(src, dst, 0o600, os.Getuid(), maxInputBytes); err != nil {
+		t.Fatal(err)
+	}
+	got, err := os.ReadFile(dst)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != string(payload) {
+		t.Fatalf("copy mismatch: %q", got)
+	}
+}
+
+// --- runInstall table-driven coverage via injectable deps ---
+
+type installProbe struct {
+	phases   []string
+	results  []helperResult
+	aptCalls []string
+}
+
+func baseFakeDeps(p *installProbe) installDeps {
+	return installDeps{
+		geteuid: func() int { return 0 },
+		getenv: func(k string) string {
+			if k == "PKEXEC_UID" {
+				return "1000"
+			}
+			return ""
+		},
+		mkTempDir: func() (string, error) {
+			return os.MkdirTemp("", "reasonix-helper-test-*")
+		},
+		removeAll: os.RemoveAll,
+		copyOwnedRegular: func(src, dst string, mode os.FileMode, ownerUID int, maxBytes int64) error {
+			data, err := os.ReadFile(src)
+			if err != nil {
+				return err
+			}
+			return os.WriteFile(dst, data, mode)
+		},
+		readFile: os.ReadFile,
+		verify:   func(data, sig []byte) error { return nil },
+		inspectDeb: func(path string) (debIdentity, error) {
+			return debIdentity{Package: packageName, Version: "1.2.0", Arch: "amd64"}, nil
+		},
+		installedVersion: func() (string, error) { return "1.1.0", nil },
+		compareVersions:  func(a, b string) (int, error) { return 1, nil },
+		aptInstall: func(pkgPath string, allowDowngrade bool) error {
+			p.aptCalls = append(p.aptCalls, pkgPath)
+			// Assert argv shape through the pure helper used by production.
+			argv := aptInstallArgv(pkgPath, allowDowngrade)
+			if argv[0] != aptGetPath || argv[1] != "install" {
+				return fmt.Errorf("bad argv: %v", argv)
+			}
+			return nil
+		},
+		verifyInstalled: func(want string) error {
+			if want != "1.2.0" {
+				return errors.New("installed version mismatch")
+			}
+			return nil
+		},
+		writePhase:    func(phase string) { p.phases = append(p.phases, phase) },
+		writeResult:   func(r helperResult) { p.results = append(p.results, r) },
+		goArch:        "amd64",
+		maxInputBytes: maxInputBytes,
+	}
+}
+
+func writeInstallInputs(t *testing.T) (pkg, sig string) {
+	t.Helper()
+	dir := t.TempDir()
+	pkg = filepath.Join(dir, "Reasonix.deb")
+	sig = filepath.Join(dir, "Reasonix.deb.minisig")
+	if err := os.WriteFile(pkg, []byte("deb-payload"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(sig, []byte("sig-payload"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return pkg, sig
+}
+
+func TestRunInstallSuccessEmitsInstallingPhaseBeforeApt(t *testing.T) {
+	pkg, sig := writeInstallInputs(t)
+	var probe installProbe
+	d := baseFakeDeps(&probe)
+	aptStarted := false
+	d.aptInstall = func(pkgPath string, allowDowngrade bool) error {
+		aptStarted = true
+		if allowDowngrade {
+			t.Fatal("ordinary upgrade unexpectedly enabled downgrades")
+		}
+		if len(probe.phases) == 0 || probe.phases[0] != "installing" {
+			t.Fatalf("phase installing must be emitted before apt; phases=%v", probe.phases)
+		}
+		probe.aptCalls = append(probe.aptCalls, pkgPath)
+		return nil
+	}
+	code := runWith(d, []string{"install", "--package", pkg, "--signature", sig})
+	if code != exitOK {
+		t.Fatalf("exit = %d, results=%+v", code, probe.results)
+	}
+	if !aptStarted || len(probe.aptCalls) != 1 {
+		t.Fatalf("apt not called: %+v", probe.aptCalls)
+	}
+	if len(probe.results) != 1 || !probe.results[0].OK || probe.results[0].Version != "1.2.0" {
+		t.Fatalf("result = %+v", probe.results)
+	}
+}
+
+func TestRunInstallTable(t *testing.T) {
+	pkg, sig := writeInstallInputs(t)
+
+	type tc struct {
+		name        string
+		mutate      func(*installDeps, *installProbe)
+		args        []string
+		wantCode    int
+		wantCodeStr string
+		wantPhase   bool // installing emitted only on success path past validation
+		wantOK      bool
+	}
+	cases := []tc{
+		{
+			name:        "usage missing flags",
+			args:        []string{"install"},
+			wantCode:    exitUsage,
+			wantCodeStr: "usage",
+		},
+		{
+			name: "not root",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.geteuid = func() int { return 1000 }
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitNotRoot,
+			wantCodeStr: "not_root",
+		},
+		{
+			name: "missing PKEXEC_UID",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.getenv = func(string) string { return "" }
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitNotRoot,
+			wantCodeStr: "not_root",
+		},
+		{
+			name: "bad input copy",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.copyOwnedRegular = func(string, string, os.FileMode, int, int64) error {
+					return errors.New("owner mismatch")
+				}
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitBadInput,
+			wantCodeStr: "bad_input",
+		},
+		{
+			name: "verify failed",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.verify = func([]byte, []byte) error { return errors.New("bad sig") }
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitVerifyFailed,
+			wantCodeStr: "verify_failed",
+		},
+		{
+			name: "wrong package name",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.inspectDeb = func(string) (debIdentity, error) {
+					return debIdentity{Package: "other", Version: "2.0", Arch: "amd64"}, nil
+				}
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitPackageRejected,
+			wantCodeStr: "package_rejected",
+		},
+		{
+			name: "wrong architecture",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.inspectDeb = func(string) (debIdentity, error) {
+					return debIdentity{Package: packageName, Version: "2.0", Arch: "arm64"}, nil
+				}
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitPackageRejected,
+			wantCodeStr: "package_rejected",
+		},
+		{
+			name: "same version rejected",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.compareVersions = func(a, b string) (int, error) { return 0, nil }
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitPackageRejected,
+			wantCodeStr: "package_rejected",
+		},
+		{
+			name: "downgrade rejected",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.compareVersions = func(a, b string) (int, error) { return -1, nil }
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitPackageRejected,
+			wantCodeStr: "package_rejected",
+		},
+		{
+			name: "preview to stable downgrade allowed",
+			mutate: func(d *installDeps, p *installProbe) {
+				d.inspectDeb = func(string) (debIdentity, error) {
+					return debIdentity{Package: packageName, Version: "1.2.0", Arch: "amd64"}, nil
+				}
+				d.installedVersion = func() (string, error) { return "1.3.0~preview.1", nil }
+				d.compareVersions = func(a, b string) (int, error) { return -1, nil }
+				d.aptInstall = func(pkgPath string, allowDowngrade bool) error {
+					if !allowDowngrade {
+						return errors.New("preview-to-stable downgrade flag missing")
+					}
+					p.aptCalls = append(p.aptCalls, pkgPath)
+					return nil
+				}
+			},
+			args:      []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:  exitOK,
+			wantPhase: true,
+			wantOK:    true,
+		},
+		{
+			name: "apt busy",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.aptInstall = func(string, bool) error {
+					return errors.New("Could not get lock /var/lib/dpkg/lock-frontend")
+				}
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitBusy,
+			wantCodeStr: "package_manager_busy",
+			wantPhase:   true,
+		},
+		{
+			name: "apt non-zero",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.aptInstall = func(string, bool) error {
+					return errors.New("E: Sub-process /usr/bin/dpkg returned an error code (1)")
+				}
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitInstallFailed,
+			wantCodeStr: "install_failed",
+			wantPhase:   true,
+		},
+		{
+			name: "post install version mismatch",
+			mutate: func(d *installDeps, _ *installProbe) {
+				d.verifyInstalled = func(string) error { return errors.New("installed version mismatch") }
+			},
+			args:        []string{"install", "--package", pkg, "--signature", sig},
+			wantCode:    exitPostVerify,
+			wantCodeStr: "package_verify_failed",
+			wantPhase:   true,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var probe installProbe
+			d := baseFakeDeps(&probe)
+			if tc.mutate != nil {
+				tc.mutate(&d, &probe)
+			}
+			code := runWith(d, tc.args)
+			if code != tc.wantCode {
+				t.Fatalf("exit = %d, want %d; results=%+v", code, tc.wantCode, probe.results)
+			}
+			if len(probe.results) == 0 {
+				t.Fatal("expected a written result")
+			}
+			last := probe.results[len(probe.results)-1]
+			if last.OK != tc.wantOK {
+				t.Fatalf("result OK = %v, want %v: %+v", last.OK, tc.wantOK, last)
+			}
+			if tc.wantCodeStr != "" && last.Code != tc.wantCodeStr {
+				t.Fatalf("code = %q, want %q", last.Code, tc.wantCodeStr)
+			}
+			if tc.wantPhase {
+				if len(probe.phases) == 0 || probe.phases[0] != "installing" {
+					t.Fatalf("expected installing phase before failure after validation, got %v", probe.phases)
+				}
+			} else if len(probe.phases) > 0 {
+				// Validation failures must not claim apt started.
+				t.Fatalf("unexpected phase before validation failure: %v", probe.phases)
+			}
+		})
+	}
+}
+
+func TestRunInstallCleansTempDirOnFailure(t *testing.T) {
+	pkg, sig := writeInstallInputs(t)
+	var probe installProbe
+	d := baseFakeDeps(&probe)
+	var created, removed string
+	d.mkTempDir = func() (string, error) {
+		dir, err := os.MkdirTemp("", "reasonix-helper-test-*")
+		created = dir
+		return dir, err
+	}
+	d.removeAll = func(path string) error {
+		removed = path
+		return os.RemoveAll(path)
+	}
+	d.verify = func([]byte, []byte) error { return errors.New("fail after tmp") }
+	code := runWith(d, []string{"install", "--package", pkg, "--signature", sig})
+	if code != exitVerifyFailed {
+		t.Fatalf("exit = %d", code)
+	}
+	if created == "" || removed != created {
+		t.Fatalf("temp dir not cleaned: created=%q removed=%q", created, removed)
+	}
+	if _, err := os.Stat(created); !os.IsNotExist(err) {
+		t.Fatalf("temp dir still on disk: %v", err)
+	}
+}
+
+func TestRunInstallRejectsUnknownCommand(t *testing.T) {
+	var probe installProbe
+	d := baseFakeDeps(&probe)
+	code := runWith(d, []string{"upgrade"})
+	if code != exitUsage {
+		t.Fatalf("exit = %d", code)
+	}
+}
+
+// TestMinisignRejectsWrongKeyAndTamper pins that the shared verify path used by
+// the helper rejects throwaway-key signatures and tampered payloads. Production
+// uses update.Verify with the embedded key; here we exercise the same minisign
+// library contract the helper depends on.
+func TestMinisignRejectsWrongKeyAndTamper(t *testing.T) {
+	pub, priv, err := minisign.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	data := []byte("artifact")
+	sig := minisign.Sign(priv, data)
+	if !minisign.Verify(pub, data, sig) {
+		t.Fatal("genuine signature under matching key must verify")
+	}
+	if minisign.Verify(pub, []byte("tampered"), sig) {
+		t.Fatal("tampered payload must not verify")
+	}
+	otherPub, _, err := minisign.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if minisign.Verify(otherPub, data, sig) {
+		t.Fatal("signature under a different public key must not verify")
+	}
+	// Garbage signature must fail under the matching public key.
+	if minisign.Verify(pub, data, []byte("not-a-sig")) {
+		t.Fatal("garbage signature must not verify")
+	}
+	// Wire the same contract into installDeps.verify so a wrong-key path fails
+	// runInstall with exitVerifyFailed.
+	var probe installProbe
+	d := baseFakeDeps(&probe)
+	d.verify = func(payload, signature []byte) error {
+		if !minisign.Verify(pub, payload, signature) {
+			return errors.New("signature verification failed")
+		}
+		return nil
+	}
+	pkg, sigPath := writeInstallInputs(t)
+	// Input files contain "deb-payload"/"sig-payload", not a real signature.
+	code := runWith(d, []string{"install", "--package", pkg, "--signature", sigPath})
+	if code != exitVerifyFailed {
+		t.Fatalf("exit = %d, want verify failed; results=%+v", code, probe.results)
+	}
+}
@@ -1,4 +1,4 @@
-//go:build !windows
+//go:build !windows && !linux

 package main

@@ -8,6 +8,6 @@ import (
 )

 func main() {
-	fmt.Fprintln(os.Stderr, "reasonix-update-helper is only used by Windows desktop builds")
+	fmt.Fprintln(os.Stderr, "reasonix-update-helper is only used by Windows and Linux desktop builds")
 	os.Exit(2)
 }
@@ -3,36 +3,58 @@
 package main

 import (
+	"crypto/sha256"
+	"encoding/hex"
 	"flag"
 	"fmt"
+	"io"
 	"log"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
+	"sync"
 	"syscall"
 	"time"

 	"golang.org/x/sys/windows"

+	"reasonix/internal/installlayout"
 	"reasonix/internal/repair"
 )

 const parentExitTimeout = 2 * time.Minute

+var (
+	waitForProcessExitFn       = waitForProcessExit
+	runInstallerFn             = runInstaller
+	startRelaunchFn            = startRelaunch
+	claimPendingFileUpdateFn   = repair.ClaimPendingFileUpdateExact
+	installStagedReleaseUnitFn = installStagedWindowsReleaseUnit
+	recordInstalledUpdateFn    = repair.RecordClaimedFileUpdateInstalled
+	stageInstallerFn           = stageVerifiedInstaller
+	claimInstallerExecutionFn  = claimVerifiedInstallerForExecution
+	lstatUpdateStagingFn       = os.Lstat
+)
+
 func main() {
 	os.Exit(run(os.Args[1:]))
 }

 func run(args []string) int {
 	var parentPID uint
-	var installer, installDir, relaunch, toVersion string
+	var installer, installerSHA256, installDir, relaunch, toVersion, createdAt, transactionID, installLayout string
 	fs := flag.NewFlagSet("reasonix-update-helper", flag.ContinueOnError)
 	fs.SetOutput(os.Stderr)
 	fs.UintVar(&parentPID, "parent-pid", 0, "Reasonix process id to wait for before installing")
 	fs.StringVar(&installer, "installer", "", "verified NSIS installer path")
+	fs.StringVar(&installerSHA256, "installer-sha256", "", "expected SHA-256 of the verified NSIS installer")
 	fs.StringVar(&installDir, "install-dir", "", "Reasonix installation directory")
 	fs.StringVar(&relaunch, "relaunch", "", "Reasonix executable to start after the installer succeeds")
 	fs.StringVar(&toVersion, "to-version", "", "Reasonix version being installed")
+	fs.StringVar(&createdAt, "created-at", "", "pending update creation timestamp")
+	fs.StringVar(&transactionID, "transaction-id", "", "complete pending update identity")
+	fs.StringVar(&installLayout, "install-layout", "", "installation layout contract")
 	if err := fs.Parse(args); err != nil {
 		return 2
 	}
@@ -41,35 +63,164 @@ func run(args []string) int {
 		logger.Print("missing --installer")
 		return 2
 	}
+	if !validSHA256(installerSHA256) {
+		logger.Print("missing or invalid --installer-sha256")
+		return 2
+	}
 	if toVersion == "" {
 		logger.Print("missing --to-version")
 		return 2
 	}
+	if installLayout != "" && installLayout != installlayout.InstallLayoutVersionedV1 {
+		logger.Printf("unsupported --install-layout %q", installLayout)
+		return 2
+	}
+	if installLayout != installlayout.InstallLayoutVersionedV1 && createdAt == "" {
+		logger.Print("missing --created-at")
+		return 2
+	}
+	if installLayout != installlayout.InstallLayoutVersionedV1 && transactionID == "" {
+		logger.Print("missing --transaction-id")
+		return 2
+	}
+	if installDir == "" {
+		logger.Print("missing --install-dir")
+		return 2
+	}
 	if parentPID != 0 {
-		if err := waitForProcessExit(uint32(parentPID), parentExitTimeout); err != nil {
+		if err := waitForProcessExitFn(uint32(parentPID), parentExitTimeout); err != nil {
 			logger.Printf("wait for parent process %d: %v", parentPID, err)
 			return 1
 		}
 	}
-	if err := runInstaller(installer, installDir); err != nil {
-		logger.Printf("run installer: %v", err)
-		// The desktop already exited cleanly, so nothing would notice this
-		// failure: record it and relaunch through Guard, which rolls the
-		// release unit back on startup (the helper itself runs from the cache
-		// directory, outside the validated install, and must not restore
-		// binaries directly).
-		if markErr := repair.MarkUpdateApplyFailed(toVersion, err.Error()); markErr != nil {
-			logger.Printf("record install failure: %v", markErr)
-		}
+	if installLayout == installlayout.InstallLayoutVersionedV1 {
+		return runVersionedWindowsUpdate(logger, installer, installerSHA256, installDir, relaunch, toVersion)
+	}
+	recoverExisting := func(reason string) int {
 		if relaunch != "" {
-			if relaunchErr := startRelaunch(relaunch, installDir); relaunchErr != nil {
-				logger.Printf("relaunch after failed install: %v", relaunchErr)
+			if relaunchErr := startRelaunchFn(preferRelaunchPath(relaunch, installDir), installDir); relaunchErr != nil {
+				logger.Printf("relaunch after %s: %v", reason, relaunchErr)
 			}
 		}
 		return 1
 	}
+	// The detached helper runs from the update cache, so a plain
+	// repair.ReadPendingUpdate would validate the transaction against the cache
+	// directory and reject every legitimate flat install. Claim through the
+	// explicit install-local launcher path instead; the repair package validates
+	// the complete transaction identity and exact release-unit path set while it
+	// acquires the pending + target locks.
+	claimTargets := windowsReleaseUnitPaths(installDir)
+	claimLauncher := filepath.Join(installDir, "reasonix-desktop.exe")
+	// The old desktop may acquire the pending lock during its normal shutdown.
+	// Wait for that exact process first, then claim the transaction and hold both
+	// pending and target locks across the installer replacement window.
+	claimed, releaseClaim, err := claimPendingFileUpdateFn(
+		toVersion,
+		createdAt,
+		transactionID,
+		claimLauncher,
+		claimTargets,
+		parentExitTimeout,
+	)
+	if err != nil {
+		logger.Printf("claim pending update: %v", err)
+		return recoverExisting("pending update claim failure")
+	}
+	defer releaseClaim()
+	recoverUnstarted := func() int {
+		releaseClaim()
+		if cancelErr := repair.CancelPendingUpdateExact(claimed); cancelErr != nil {
+			logger.Printf("cancel unstarted update: %v", cancelErr)
+		}
+		if relaunch != "" {
+			if relaunchErr := startRelaunchFn(relaunch, installDir); relaunchErr != nil {
+				logger.Printf("relaunch after unstarted update failure: %v", relaunchErr)
+			}
+		}
+		return 1
+	}
+	claimedInstaller, cleanupInstaller, err := stageInstallerFn(installer, installerSHA256)
+	if err != nil {
+		logger.Printf("bind update installer: %v", err)
+		return recoverUnstarted()
+	}
+	defer func() {
+		if cleanupErr := cleanupInstaller(); cleanupErr != nil {
+			logger.Printf("preserving update installer staging: %v", cleanupErr)
+		}
+	}()
+	stagingDir, err := os.MkdirTemp("", "reasonix-update-stage-*")
+	if err != nil {
+		logger.Printf("create update staging: %v", err)
+		return recoverUnstarted()
+	}
+	stagingOwner, err := lstatUpdateStagingFn(stagingDir)
+	if err != nil {
+		logger.Printf("bind update staging: %v", err)
+		return recoverUnstarted()
+	}
+	defer func() {
+		if cleanupErr := cleanupOwnedWindowsUpdateDirectory(stagingDir, stagingOwner); cleanupErr != nil {
+			logger.Printf("preserving update staging: %v", cleanupErr)
+		}
+	}()
+	releaseInstallerExecution, err := claimInstallerExecutionFn(claimedInstaller, installerSHA256)
+	if err != nil {
+		logger.Printf("recheck staged installer: %v", err)
+		return recoverUnstarted()
+	}
+	installerErr := runInstallerFn(claimedInstaller, stagingDir)
+	releaseInstallerExecution()
+	if installerErr != nil {
+		logger.Printf("extract installer payload: %v", installerErr)
+		return recoverUnstarted()
+	}
+	publishStarted, receipts, err := installStagedReleaseUnitFn(claimed, stagingDir)
+	if err != nil {
+		logger.Printf("publish staged release unit: %v", err)
+		if !publishStarted {
+			releaseClaim()
+			if cancelErr := repair.CancelPendingUpdateExact(claimed); cancelErr != nil {
+				logger.Printf("cancel unstarted update: %v", cancelErr)
+			}
+		}
+		if relaunch != "" {
+			if relaunchErr := startRelaunchFn(preferRelaunchPath(relaunch, installDir), installDir); relaunchErr != nil {
+				logger.Printf("relaunch after publish failure: %v", relaunchErr)
+			}
+		}
+		return 1
+	}
+	if receipts == nil {
+		// Versioned-v1 activation: no flat publish receipts and no health
+		// probation. Clear the pending transaction and relaunch the launcher.
+		releaseClaim()
+		if cancelErr := repair.CancelPendingUpdateExact(claimed); cancelErr != nil {
+			logger.Printf("clear pending after versioned activate: %v", cancelErr)
+		}
+		if clearErr := repair.ClearUpdateApplyFailureExact(claimed); clearErr != nil {
+			logger.Printf("clear apply failure after versioned activate: %v", clearErr)
+		}
+	} else {
+		if _, err := recordInstalledUpdateFn(claimed, receipts...); err != nil {
+			logger.Printf("record installed release unit: %v", err)
+			if markErr := repair.MarkUpdateApplyFailedExact(claimed, err.Error()); markErr != nil {
+				logger.Printf("record install failure: %v", markErr)
+			}
+			if relaunch != "" {
+				if relaunchErr := startRelaunchFn(preferRelaunchPath(relaunch, installDir), installDir); relaunchErr != nil {
+					logger.Printf("relaunch after failed install verification: %v", relaunchErr)
+				}
+			}
+			return 1
+		}
+		if err := repair.ClearUpdateApplyFailureExact(claimed); err != nil {
+			logger.Printf("clear completed update marker: %v", err)
+		}
+	}
 	if relaunch != "" {
-		if err := startRelaunch(relaunch, installDir); err != nil {
+		if err := startRelaunchFn(preferRelaunchPath(relaunch, installDir), installDir); err != nil {
 			logger.Printf("relaunch: %v", err)
 			return 1
 		}
@@ -77,6 +228,253 @@ func run(args []string) int {
 	return 0
 }

+func runVersionedWindowsUpdate(logger *log.Logger, installer, installerSHA256, installDir, relaunch, toVersion string) int {
+	recoverExisting := func() int {
+		if relaunch != "" {
+			if err := startRelaunchFn(preferRelaunchPath(relaunch, installDir), installDir); err != nil {
+				logger.Printf("relaunch after versioned update failure: %v", err)
+			}
+		}
+		return 1
+	}
+	if _, err := installlayout.ReadCurrent(installDir); err != nil {
+		logger.Printf("read versioned install pointer: %v", err)
+		return recoverExisting()
+	}
+	claimedInstaller, cleanupInstaller, err := stageInstallerFn(installer, installerSHA256)
+	if err != nil {
+		logger.Printf("bind versioned update installer: %v", err)
+		return recoverExisting()
+	}
+	defer func() {
+		if cleanupErr := cleanupInstaller(); cleanupErr != nil {
+			logger.Printf("preserving update installer staging: %v", cleanupErr)
+		}
+	}()
+	stagingDir, err := os.MkdirTemp("", "reasonix-update-stage-*")
+	if err != nil {
+		logger.Printf("create versioned update staging: %v", err)
+		return recoverExisting()
+	}
+	stagingOwner, err := lstatUpdateStagingFn(stagingDir)
+	if err != nil {
+		logger.Printf("bind versioned update staging: %v", err)
+		return recoverExisting()
+	}
+	defer func() {
+		if cleanupErr := cleanupOwnedWindowsUpdateDirectory(stagingDir, stagingOwner); cleanupErr != nil {
+			logger.Printf("preserving update staging: %v", cleanupErr)
+		}
+	}()
+	releaseInstallerExecution, err := claimInstallerExecutionFn(claimedInstaller, installerSHA256)
+	if err != nil {
+		logger.Printf("recheck staged versioned installer: %v", err)
+		return recoverExisting()
+	}
+	installerErr := runInstallerFn(claimedInstaller, stagingDir)
+	releaseInstallerExecution()
+	if installerErr != nil {
+		logger.Printf("extract versioned installer payload: %v", installerErr)
+		return recoverExisting()
+	}
+	claimed := &repair.UpdateTransaction{
+		SchemaVersion: 1,
+		ToVersion:     toVersion,
+		TargetKind:    "file",
+		TargetPath:    filepath.Join(installDir, "reasonix-desktop.exe"),
+	}
+	if err := activateVersionedWindowsFromStaging(claimed, stagingDir); err != nil {
+		logger.Printf("activate versioned release: %v", err)
+		return recoverExisting()
+	}
+	if relaunch != "" {
+		if err := startRelaunchFn(preferRelaunchPath(relaunch, installDir), installDir); err != nil {
+			logger.Printf("relaunch versioned release: %v", err)
+			return 1
+		}
+	}
+	return 0
+}
+
+// preferRelaunchPath chooses the thin launcher when present so post-update
+// restarts use the permanent entry point, not a flat desktop binary.
+func preferRelaunchPath(relaunch, installDir string) string {
+	for _, name := range []string{"reasonix-launcher.exe", "Reasonix.exe"} {
+		path := filepath.Join(installDir, name)
+		if info, err := os.Lstat(path); err == nil && info.Mode().IsRegular() {
+			return path
+		}
+	}
+	return relaunch
+}
+
+func validSHA256(value string) bool {
+	value = strings.TrimSpace(value)
+	if len(value) != sha256.Size*2 {
+		return false
+	}
+	_, err := hex.DecodeString(value)
+	return err == nil
+}
+
+func stageVerifiedInstaller(sourcePath, expectedSHA256 string) (string, func() error, error) {
+	if !validSHA256(expectedSHA256) {
+		return "", nil, fmt.Errorf("installer SHA-256 is invalid")
+	}
+	sourceInfo, err := os.Lstat(sourcePath)
+	if err != nil {
+		return "", nil, err
+	}
+	if !sourceInfo.Mode().IsRegular() {
+		return "", nil, fmt.Errorf("installer is not a regular file")
+	}
+	dir, err := os.MkdirTemp("", "reasonix-update-installer-*")
+	if err != nil {
+		return "", nil, err
+	}
+	owner, err := os.Lstat(dir)
+	if err != nil {
+		return "", nil, err
+	}
+	cleanup := func() error {
+		return cleanupOwnedWindowsUpdateDirectory(dir, owner)
+	}
+	fail := func(err error) (string, func() error, error) {
+		_ = cleanup()
+		return "", nil, err
+	}
+	source, err := os.Open(sourcePath)
+	if err != nil {
+		return fail(err)
+	}
+	defer source.Close()
+	stagedPath := filepath.Join(dir, "reasonix-installer.exe")
+	staged, err := os.OpenFile(stagedPath, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o700)
+	if err != nil {
+		return fail(err)
+	}
+	hash := sha256.New()
+	_, copyErr := io.Copy(io.MultiWriter(staged, hash), source)
+	syncErr := staged.Sync()
+	closeErr := staged.Close()
+	switch {
+	case copyErr != nil:
+		return fail(copyErr)
+	case syncErr != nil:
+		return fail(syncErr)
+	case closeErr != nil:
+		return fail(closeErr)
+	case !strings.EqualFold(hex.EncodeToString(hash.Sum(nil)), strings.TrimSpace(expectedSHA256)):
+		return fail(fmt.Errorf("installer SHA-256 changed after desktop verification"))
+	}
+	if err := verifyInstallerSHA256(stagedPath, expectedSHA256); err != nil {
+		return fail(err)
+	}
+	return stagedPath, cleanup, nil
+}
+
+func verifyInstallerSHA256(path, expectedSHA256 string) error {
+	info, err := os.Lstat(path)
+	if err != nil {
+		return err
+	}
+	if !info.Mode().IsRegular() {
+		return fmt.Errorf("installer is not a regular file")
+	}
+	f, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	hash := sha256.New()
+	if _, err := io.Copy(hash, f); err != nil {
+		return err
+	}
+	if !strings.EqualFold(hex.EncodeToString(hash.Sum(nil)), strings.TrimSpace(expectedSHA256)) {
+		return fmt.Errorf("installer SHA-256 mismatch")
+	}
+	return nil
+}
+
+func claimVerifiedInstallerForExecution(path, expectedSHA256 string) (func(), error) {
+	if !validSHA256(expectedSHA256) {
+		return nil, fmt.Errorf("installer SHA-256 is invalid")
+	}
+	pathUTF16, err := windows.UTF16PtrFromString(path)
+	if err != nil {
+		return nil, err
+	}
+	handle, err := windows.CreateFile(
+		pathUTF16,
+		windows.GENERIC_READ,
+		windows.FILE_SHARE_READ,
+		nil,
+		windows.OPEN_EXISTING,
+		windows.FILE_ATTRIBUTE_NORMAL|windows.FILE_FLAG_SEQUENTIAL_SCAN,
+		0,
+	)
+	if err != nil {
+		return nil, err
+	}
+	file := os.NewFile(uintptr(handle), path)
+	fail := func(err error) (func(), error) {
+		_ = file.Close()
+		return nil, err
+	}
+	info, err := file.Stat()
+	if err != nil {
+		return fail(err)
+	}
+	if !info.Mode().IsRegular() {
+		return fail(fmt.Errorf("installer is not a regular file"))
+	}
+	hash := sha256.New()
+	if _, err := io.Copy(hash, file); err != nil {
+		return fail(err)
+	}
+	if !strings.EqualFold(hex.EncodeToString(hash.Sum(nil)), strings.TrimSpace(expectedSHA256)) {
+		return fail(fmt.Errorf("installer SHA-256 mismatch"))
+	}
+	var once sync.Once
+	return func() {
+		once.Do(func() { _ = file.Close() })
+	}, nil
+}
+
+func installStagedWindowsReleaseUnit(
+	claimed *repair.UpdateTransaction,
+	stagingDir string,
+) (bool, []repair.FileUpdateInstallReceipt, error) {
+	// v1.20+: versioned-v1 is the only publish path. Incomplete staged payloads
+	// fail closed without mutating the live install or leaving flat pending state.
+	if !preferVersionedWindowsActivation(stagingDir) {
+		return false, nil, fmt.Errorf("staged payload is incomplete for versioned-v1 activation")
+	}
+	if err := activateVersionedWindowsFromStaging(claimed, stagingDir); err != nil {
+		return false, nil, fmt.Errorf("versioned activate: %w", err)
+	}
+	return true, nil, nil
+}
+
+func windowsReleaseUnitPaths(installDir string) []string {
+	if installDir == "" {
+		return nil
+	}
+	names := []string{
+		"reasonix-desktop.exe",
+		"reasonix-guard.exe",
+		"reasonix-launcher.exe",
+		"reasonix-update-helper.exe",
+		"reasonix-cli.exe",
+		"Reasonix.exe",
+	}
+	paths := make([]string, 0, len(names))
+	for _, name := range names {
+		paths = append(paths, filepath.Join(installDir, name))
+	}
+	return paths
+}
+
 func newLogger() *log.Logger {
 	dir, err := os.UserCacheDir()
 	if err == nil {
@@ -117,12 +515,55 @@ func waitForProcessExit(pid uint32, timeout time.Duration) error {
 func runInstaller(installer, installDir string) error {
 	cmd := exec.Command(installer)
 	// Keep the helper itself hidden, but let the NSIS update-progress window be
-	// visible. The dedicated /REASONIXUPDATE mode prevents directory changes and
-	// closes automatically after the update finishes.
+	// visible. /REASONIXSTAGE makes the signed installer extract only; the helper
+	// performs every live replacement through the claimed transaction.
 	cmd.SysProcAttr = &syscall.SysProcAttr{CmdLine: installerCommandLine(installer, installDir)}
 	return cmd.Run()
 }

+func cleanupOwnedWindowsUpdateDirectory(path string, owner os.FileInfo) error {
+	if path == "" || owner == nil || !owner.IsDir() {
+		return fmt.Errorf("Windows update cleanup identity is incomplete")
+	}
+	for attempt := 0; attempt < 16; attempt++ {
+		cleanup := fmt.Sprintf("%s.reasonix-cleanup-%d-%d", path, time.Now().UTC().UnixNano(), attempt)
+		from, err := windows.UTF16PtrFromString(path)
+		if err != nil {
+			return err
+		}
+		to, err := windows.UTF16PtrFromString(cleanup)
+		if err != nil {
+			return err
+		}
+		if err := windows.MoveFileEx(from, to, windows.MOVEFILE_WRITE_THROUGH); err != nil {
+			if os.IsNotExist(err) {
+				return nil
+			}
+			if os.IsExist(err) {
+				continue
+			}
+			return err
+		}
+		actual, err := os.Lstat(cleanup)
+		if err != nil {
+			return err
+		}
+		if !os.SameFile(owner, actual) {
+			restoreFrom, fromErr := windows.UTF16PtrFromString(cleanup)
+			restoreTo, toErr := windows.UTF16PtrFromString(path)
+			if fromErr != nil || toErr != nil {
+				return fmt.Errorf("Windows update staging changed before cleanup; preserve replacement at %s", cleanup)
+			}
+			if restoreErr := windows.MoveFileEx(restoreFrom, restoreTo, windows.MOVEFILE_WRITE_THROUGH); restoreErr != nil {
+				return fmt.Errorf("Windows update staging changed before cleanup; preserve replacement at %s: %w", cleanup, restoreErr)
+			}
+			return fmt.Errorf("Windows update staging changed before cleanup")
+		}
+		return os.RemoveAll(cleanup)
+	}
+	return fmt.Errorf("cannot allocate Windows update cleanup path")
+}
+
 func startRelaunch(relaunch, installDir string) error {
 	cmd := exec.Command(relaunch)
 	cmd.Dir = installDir
@@ -2,10 +2,547 @@

 package main

-import "testing"
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"reasonix/internal/installlayout"
+	"reasonix/internal/repair"
+)
+
+const testInstallerSHA256 = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+func prepareLegacyWindowsUpdate(t *testing.T, installDir, toVersion string) *repair.UpdateTransaction {
+	t.Helper()
+	paths := windowsReleaseUnitPaths(installDir)
+	for _, path := range paths {
+		if err := os.WriteFile(path, []byte("old-"+filepath.Base(path)), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	tx, err := repair.PrepareFileUpdate("v1", toVersion, paths[0], paths[1:]...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return tx
+}
+
+func TestStageVerifiedInstallerFreezesExpectedBytes(t *testing.T) {
+	source := filepath.Join(t.TempDir(), "installer.exe")
+	content := []byte("verified-installer")
+	if err := os.WriteFile(source, content, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	sum := sha256.Sum256(content)
+	expected := hex.EncodeToString(sum[:])
+	staged, cleanup, err := stageVerifiedInstaller(source, expected)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = cleanup() })
+	if staged == source {
+		t.Fatal("installer was not isolated from the mutable cache path")
+	}
+	if err := os.WriteFile(source, []byte("changed-after-handoff"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := verifyInstallerSHA256(staged, expected); err != nil {
+		t.Fatalf("isolated installer changed with source: %v", err)
+	}
+	if got, err := os.ReadFile(staged); err != nil || string(got) != string(content) {
+		t.Fatalf("staged installer = %q, %v", got, err)
+	}
+	if err := os.WriteFile(staged, []byte("tampered"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := verifyInstallerSHA256(staged, expected); err == nil {
+		t.Fatal("tampered staged installer passed final verification")
+	}
+}
+
+func TestStageVerifiedInstallerRejectsSourceHashDrift(t *testing.T) {
+	source := filepath.Join(t.TempDir(), "installer.exe")
+	if err := os.WriteFile(source, []byte("different"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if _, cleanup, err := stageVerifiedInstaller(source, testInstallerSHA256); err == nil {
+		if cleanup != nil {
+			_ = cleanup()
+		}
+		t.Fatal("installer bytes different from desktop verification were accepted")
+	}
+}

 func TestRunRequiresTargetVersionBeforeStartingInstaller(t *testing.T) {
-	if code := run([]string{"--installer", `C:\Temp\Reasonix-installer.exe`}); code != 2 {
+	if code := run([]string{
+		"--installer", `C:\Temp\Reasonix-installer.exe`,
+		"--installer-sha256", testInstallerSHA256,
+	}); code != 2 {
 		t.Fatalf("run without --to-version = %d, want 2", code)
 	}
 }
+
+func TestRunVersionedLayoutDoesNotReadOrClaimLegacyPending(t *testing.T) {
+	installDir := t.TempDir()
+	seed := t.TempDir()
+	for _, name := range []string{"reasonix-desktop.exe", "reasonix-cli.exe", "reasonix-update-helper.exe"} {
+		if err := os.WriteFile(filepath.Join(seed, name), []byte("old-"+name), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := installlayout.ActivateVersion(installlayout.ActivationRequest{
+		InstallRoot: installDir,
+		Version:     "v1.20.0",
+		RequestID:   "seed-windows-helper",
+		Members: []installlayout.Member{
+			{Name: "reasonix-desktop.exe", Path: filepath.Join(seed, "reasonix-desktop.exe")},
+			{Name: "reasonix-cli.exe", Path: filepath.Join(seed, "reasonix-cli.exe")},
+			{Name: "reasonix-update-helper.exe", Path: filepath.Join(seed, "reasonix-update-helper.exe")},
+		},
+		RequiredNames: []string{"reasonix-desktop.exe", "reasonix-cli.exe", "reasonix-update-helper.exe"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	originalInstaller := runInstallerFn
+	originalRelaunch := startRelaunchFn
+	originalClaim := claimPendingFileUpdateFn
+	originalStageInstaller := stageInstallerFn
+	originalClaimInstallerExecution := claimInstallerExecutionFn
+	t.Cleanup(func() {
+		runInstallerFn = originalInstaller
+		startRelaunchFn = originalRelaunch
+		claimPendingFileUpdateFn = originalClaim
+		stageInstallerFn = originalStageInstaller
+		claimInstallerExecutionFn = originalClaimInstallerExecution
+	})
+	legacyClaimed := false
+	claimPendingFileUpdateFn = func(string, string, string, string, []string, time.Duration) (*repair.UpdateTransaction, func(), error) {
+		legacyClaimed = true
+		return nil, func() {}, errors.New("legacy claim must not run")
+	}
+	stageInstallerFn = func(path, _ string) (string, func() error, error) {
+		return path, func() error { return nil }, nil
+	}
+	claimInstallerExecutionFn = func(string, string) (func(), error) { return func() {}, nil }
+	runInstallerFn = func(_ string, staging string) error {
+		for _, name := range []string{"reasonix-desktop.exe", "reasonix-cli.exe", "reasonix-update-helper.exe", "reasonix-launcher.exe"} {
+			if err := os.WriteFile(filepath.Join(staging, name), []byte("new-"+name), 0o700); err != nil {
+				return err
+			}
+		}
+		return nil
+	}
+	relaunched := false
+	startRelaunchFn = func(string, string) error { relaunched = true; return nil }
+
+	if code := run([]string{
+		"--installer", filepath.Join(installDir, "installer.exe"),
+		"--installer-sha256", testInstallerSHA256,
+		"--install-dir", installDir,
+		"--relaunch", filepath.Join(installDir, "reasonix-launcher.exe"),
+		"--to-version", "v1.20.1",
+		"--install-layout", "versioned-v1",
+	}); code != 0 {
+		t.Fatalf("run exit code = %d", code)
+	}
+	if legacyClaimed {
+		t.Fatal("versioned update claimed legacy pending transaction")
+	}
+	if !relaunched {
+		t.Fatal("versioned update did not relaunch")
+	}
+	ptr, err := installlayout.ReadCurrent(installDir)
+	if err != nil || ptr.ActiveVersion != "v1.20.1" {
+		t.Fatalf("pointer=%+v err=%v", ptr, err)
+	}
+}
+
+func TestRunHoldsReleaseUnitLockAcrossInstallerHandoff(t *testing.T) {
+	t.Setenv("REASONIX_HOME", t.TempDir())
+	installDir := t.TempDir()
+	pending := prepareLegacyWindowsUpdate(t, installDir, "v2")
+	var events []string
+	originalWait := waitForProcessExitFn
+	originalInstaller := runInstallerFn
+	originalRelaunch := startRelaunchFn
+	originalClaim := claimPendingFileUpdateFn
+	originalInstallStaged := installStagedReleaseUnitFn
+	originalRecord := recordInstalledUpdateFn
+	originalStageInstaller := stageInstallerFn
+	originalClaimInstallerExecution := claimInstallerExecutionFn
+	t.Cleanup(func() {
+		waitForProcessExitFn = originalWait
+		runInstallerFn = originalInstaller
+		startRelaunchFn = originalRelaunch
+		claimPendingFileUpdateFn = originalClaim
+		installStagedReleaseUnitFn = originalInstallStaged
+		recordInstalledUpdateFn = originalRecord
+		stageInstallerFn = originalStageInstaller
+		claimInstallerExecutionFn = originalClaimInstallerExecution
+	})
+	waitForProcessExitFn = func(uint32, time.Duration) error {
+		events = append(events, "wait")
+		return nil
+	}
+	runInstallerFn = func(string, string) error {
+		events = append(events, "installer")
+		return nil
+	}
+	startRelaunchFn = func(string, string) error {
+		events = append(events, "relaunch")
+		return nil
+	}
+	claimPendingFileUpdateFn = func(toVersion, createdAt, transactionID, launcherPath string, paths []string, _ time.Duration) (*repair.UpdateTransaction, func(), error) {
+		events = append(events, "claim:"+strings.Join([]string{toVersion, createdAt, transactionID, launcherPath, strings.Join(paths, "\x00")}, "\x01"))
+		return pending, func() { events = append(events, "release") }, nil
+	}
+	installStagedReleaseUnitFn = func(*repair.UpdateTransaction, string) (bool, []repair.FileUpdateInstallReceipt, error) {
+		events = append(events, "publish")
+		return true, []repair.FileUpdateInstallReceipt{}, nil
+	}
+	recordInstalledUpdateFn = func(tx *repair.UpdateTransaction, _ ...repair.FileUpdateInstallReceipt) (*repair.UpdateTransaction, error) {
+		events = append(events, "record-installed")
+		return tx, nil
+	}
+	stageInstallerFn = func(path, sha256 string) (string, func() error, error) {
+		events = append(events, "stage-installer:"+sha256)
+		return path + ".claimed", func() error { return nil }, nil
+	}
+	claimInstallerExecutionFn = func(string, string) (func(), error) {
+		events = append(events, "claim-installer")
+		return func() { events = append(events, "release-installer") }, nil
+	}
+
+	if code := run([]string{
+		"--parent-pid", "1234",
+		"--installer", filepath.Join(installDir, "installer.exe"),
+		"--installer-sha256", testInstallerSHA256,
+		"--install-dir", installDir,
+		"--relaunch", filepath.Join(installDir, "reasonix-desktop.exe"),
+		"--to-version", pending.ToVersion,
+		"--created-at", pending.CreatedAt,
+		"--transaction-id", repair.UpdateTransactionID(pending),
+	}); code != 0 {
+		t.Fatalf("run exit code = %d", code)
+	}
+	wantClaim := "claim:" + strings.Join([]string{
+		pending.ToVersion,
+		pending.CreatedAt,
+		repair.UpdateTransactionID(pending),
+		filepath.Join(installDir, "reasonix-desktop.exe"),
+		strings.Join(windowsReleaseUnitPaths(installDir), "\x00"),
+	}, "\x01")
+	if len(events) != 10 || events[0] != "wait" || events[1] != wantClaim ||
+		events[2] != "stage-installer:"+testInstallerSHA256 ||
+		events[3] != "claim-installer" || events[4] != "installer" ||
+		events[5] != "release-installer" || events[6] != "publish" ||
+		events[7] != "record-installed" || events[8] != "relaunch" ||
+		events[9] != "release" {
+		t.Fatalf("handoff events = %#v", events)
+	}
+}
+
+func TestRunDoesNotClaimUpdateBeforeParentExits(t *testing.T) {
+	installDir := t.TempDir()
+	originalWait := waitForProcessExitFn
+	originalInstaller := runInstallerFn
+	originalClaim := claimPendingFileUpdateFn
+	originalRecord := recordInstalledUpdateFn
+	t.Cleanup(func() {
+		waitForProcessExitFn = originalWait
+		runInstallerFn = originalInstaller
+		claimPendingFileUpdateFn = originalClaim
+		recordInstalledUpdateFn = originalRecord
+	})
+	waitForProcessExitFn = func(uint32, time.Duration) error {
+		return errors.New("parent still running")
+	}
+	claimed := false
+	claimPendingFileUpdateFn = func(string, string, string, string, []string, time.Duration) (*repair.UpdateTransaction, func(), error) {
+		claimed = true
+		return &repair.UpdateTransaction{}, func() {}, nil
+	}
+	installerRan := false
+	runInstallerFn = func(string, string) error {
+		installerRan = true
+		return nil
+	}
+
+	if code := run([]string{
+		"--parent-pid", "1234",
+		"--installer", filepath.Join(installDir, "installer.exe"),
+		"--installer-sha256", testInstallerSHA256,
+		"--install-dir", installDir,
+		"--to-version", "v2",
+		"--created-at", "2026-07-29T00:00:00Z",
+		"--transaction-id", "transaction-1",
+	}); code != 1 {
+		t.Fatalf("run exit code = %d, want 1", code)
+	}
+	if claimed || installerRan {
+		t.Fatalf("claim=%v installer=%v before parent exit", claimed, installerRan)
+	}
+}
+
+func TestRunRelaunchesWhenLegacyPendingCannotBeClaimed(t *testing.T) {
+	installDir := t.TempDir()
+	originalWait := waitForProcessExitFn
+	originalRelaunch := startRelaunchFn
+	originalClaim := claimPendingFileUpdateFn
+	t.Cleanup(func() {
+		waitForProcessExitFn = originalWait
+		startRelaunchFn = originalRelaunch
+		claimPendingFileUpdateFn = originalClaim
+	})
+
+	waitForProcessExitFn = func(uint32, time.Duration) error { return nil }
+	relaunched := false
+	startRelaunchFn = func(path, dir string) error {
+		relaunched = path == filepath.Join(installDir, "reasonix-desktop.exe") && dir == installDir
+		return nil
+	}
+	claimPendingFileUpdateFn = func(string, string, string, string, []string, time.Duration) (*repair.UpdateTransaction, func(), error) {
+		return nil, nil, errors.New("pending lock unavailable")
+	}
+
+	if code := run([]string{
+		"--parent-pid", "1234",
+		"--installer", filepath.Join(installDir, "installer.exe"),
+		"--installer-sha256", testInstallerSHA256,
+		"--install-dir", installDir,
+		"--relaunch", filepath.Join(installDir, "reasonix-desktop.exe"),
+		"--to-version", "v2",
+		"--created-at", "2026-08-02T00:00:00Z",
+		"--transaction-id", strings.Repeat("a", 64),
+	}); code != 1 {
+		t.Fatalf("run exit code = %d, want 1", code)
+	}
+	if !relaunched {
+		t.Fatal("helper did not relaunch the existing desktop")
+	}
+}
+
+func TestRunCancelsTransactionWhenStagedExtractionFails(t *testing.T) {
+	t.Setenv("REASONIX_HOME", t.TempDir())
+	installDir := t.TempDir()
+	originalWait := waitForProcessExitFn
+	originalInstaller := runInstallerFn
+	originalRelaunch := startRelaunchFn
+	originalClaim := claimPendingFileUpdateFn
+	originalInstallStaged := installStagedReleaseUnitFn
+	originalRecord := recordInstalledUpdateFn
+	originalStageInstaller := stageInstallerFn
+	originalClaimInstallerExecution := claimInstallerExecutionFn
+	t.Cleanup(func() {
+		waitForProcessExitFn = originalWait
+		runInstallerFn = originalInstaller
+		startRelaunchFn = originalRelaunch
+		claimPendingFileUpdateFn = originalClaim
+		installStagedReleaseUnitFn = originalInstallStaged
+		recordInstalledUpdateFn = originalRecord
+		stageInstallerFn = originalStageInstaller
+		claimInstallerExecutionFn = originalClaimInstallerExecution
+	})
+	waitForProcessExitFn = func(uint32, time.Duration) error { return nil }
+	runInstallerFn = func(string, string) error { return errors.New("installer failed") }
+	startRelaunchFn = func(string, string) error { return nil }
+	claimed := prepareLegacyWindowsUpdate(t, installDir, "v2")
+	claimPendingFileUpdateFn = func(string, string, string, string, []string, time.Duration) (*repair.UpdateTransaction, func(), error) {
+		return claimed, func() {}, nil
+	}
+	stageInstallerFn = func(path, _ string) (string, func() error, error) {
+		return path, func() error { return nil }, nil
+	}
+	claimInstallerExecutionFn = func(string, string) (func(), error) {
+		return func() {}, nil
+	}
+	transactionID := repair.UpdateTransactionID(claimed)
+	if code := run([]string{
+		"--installer", filepath.Join(installDir, "installer.exe"),
+		"--installer-sha256", testInstallerSHA256,
+		"--install-dir", installDir,
+		"--relaunch", filepath.Join(installDir, "reasonix-desktop.exe"),
+		"--to-version", "v2",
+		"--created-at", claimed.CreatedAt,
+		"--transaction-id", transactionID,
+	}); code != 1 {
+		t.Fatalf("run exit code = %d, want 1", code)
+	}
+	if _, ok := repair.ReadUpdateApplyFailure(); ok {
+		t.Fatal("staging-only installer failure left a recovery marker despite no live publish")
+	}
+}
+
+func TestRunTreatsInstalledReleaseUnitRecordingFailureAsApplyFailure(t *testing.T) {
+	t.Setenv("REASONIX_HOME", t.TempDir())
+	installDir := t.TempDir()
+	originalWait := waitForProcessExitFn
+	originalInstaller := runInstallerFn
+	originalRelaunch := startRelaunchFn
+	originalClaim := claimPendingFileUpdateFn
+	originalRecord := recordInstalledUpdateFn
+	originalStageInstaller := stageInstallerFn
+	originalClaimInstallerExecution := claimInstallerExecutionFn
+	t.Cleanup(func() {
+		waitForProcessExitFn = originalWait
+		runInstallerFn = originalInstaller
+		startRelaunchFn = originalRelaunch
+		claimPendingFileUpdateFn = originalClaim
+		recordInstalledUpdateFn = originalRecord
+		stageInstallerFn = originalStageInstaller
+		claimInstallerExecutionFn = originalClaimInstallerExecution
+	})
+	waitForProcessExitFn = func(uint32, time.Duration) error { return nil }
+	runInstallerFn = func(string, string) error { return nil }
+	relaunched := false
+	startRelaunchFn = func(string, string) error {
+		relaunched = true
+		return nil
+	}
+	claimed := prepareLegacyWindowsUpdate(t, installDir, "v2")
+	claimPendingFileUpdateFn = func(string, string, string, string, []string, time.Duration) (*repair.UpdateTransaction, func(), error) {
+		return claimed, func() {}, nil
+	}
+	stageInstallerFn = func(path, _ string) (string, func() error, error) {
+		return path, func() error { return nil }, nil
+	}
+	claimInstallerExecutionFn = func(string, string) (func(), error) {
+		return func() {}, nil
+	}
+	installStagedReleaseUnitFn = func(*repair.UpdateTransaction, string) (bool, []repair.FileUpdateInstallReceipt, error) {
+		return true, []repair.FileUpdateInstallReceipt{{
+			UpdateTransactionID: repair.UpdateTransactionID(claimed),
+			TargetPath:          claimed.TargetPath,
+			InstalledStateID:    "installed",
+		}}, nil
+	}
+	recordInstalledUpdateFn = func(*repair.UpdateTransaction, ...repair.FileUpdateInstallReceipt) (*repair.UpdateTransaction, error) {
+		return nil, errors.New("release unit drifted")
+	}
+	transactionID := repair.UpdateTransactionID(claimed)
+
+	if code := run([]string{
+		"--installer", filepath.Join(installDir, "installer.exe"),
+		"--installer-sha256", testInstallerSHA256,
+		"--install-dir", installDir,
+		"--relaunch", filepath.Join(installDir, "reasonix-desktop.exe"),
+		"--to-version", "v2",
+		"--created-at", claimed.CreatedAt,
+		"--transaction-id", transactionID,
+	}); code != 1 {
+		t.Fatalf("run exit code = %d, want 1", code)
+	}
+	if !relaunched {
+		t.Fatal("helper did not relaunch through recovery after post-install verification failure")
+	}
+	failure, ok := repair.ReadUpdateApplyFailure()
+	if !ok || failure.UpdateTransactionID != transactionID {
+		t.Fatalf("failure marker = %+v, present=%v", failure, ok)
+	}
+}
+
+func TestRunRelaunchesWhenStagingIdentityCannotBeBound(t *testing.T) {
+	t.Setenv("REASONIX_HOME", t.TempDir())
+	installDir := t.TempDir()
+	originalWait := waitForProcessExitFn
+	originalInstaller := runInstallerFn
+	originalRelaunch := startRelaunchFn
+	originalClaim := claimPendingFileUpdateFn
+	originalStageInstaller := stageInstallerFn
+	originalLstatStaging := lstatUpdateStagingFn
+	t.Cleanup(func() {
+		waitForProcessExitFn = originalWait
+		runInstallerFn = originalInstaller
+		startRelaunchFn = originalRelaunch
+		claimPendingFileUpdateFn = originalClaim
+		stageInstallerFn = originalStageInstaller
+		lstatUpdateStagingFn = originalLstatStaging
+	})
+	waitForProcessExitFn = func(uint32, time.Duration) error { return nil }
+	installerRan := false
+	runInstallerFn = func(string, string) error {
+		installerRan = true
+		return nil
+	}
+	relaunched := false
+	startRelaunchFn = func(string, string) error {
+		relaunched = true
+		return nil
+	}
+	claimed := prepareLegacyWindowsUpdate(t, installDir, "v2")
+	releases := 0
+	claimPendingFileUpdateFn = func(string, string, string, string, []string, time.Duration) (*repair.UpdateTransaction, func(), error) {
+		return claimed, func() { releases++ }, nil
+	}
+	stageInstallerFn = func(path, _ string) (string, func() error, error) {
+		return path, func() error { return nil }, nil
+	}
+	lstatUpdateStagingFn = func(string) (os.FileInfo, error) {
+		return nil, errors.New("staging identity unavailable")
+	}
+
+	if code := run([]string{
+		"--installer", filepath.Join(installDir, "installer.exe"),
+		"--installer-sha256", testInstallerSHA256,
+		"--install-dir", installDir,
+		"--relaunch", filepath.Join(installDir, "reasonix-desktop.exe"),
+		"--to-version", claimed.ToVersion,
+		"--created-at", claimed.CreatedAt,
+		"--transaction-id", repair.UpdateTransactionID(claimed),
+	}); code != 1 {
+		t.Fatalf("run exit code = %d, want 1", code)
+	}
+	if installerRan {
+		t.Fatal("installer ran without a bound staging directory")
+	}
+	if !relaunched {
+		t.Fatal("helper did not relaunch after staging identity failure")
+	}
+	if releases == 0 {
+		t.Fatal("helper did not release the update claim")
+	}
+}
+
+func TestClaimVerifiedInstallerForExecutionFreezesPath(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "installer.exe")
+	content := []byte("verified-installer")
+	if err := os.WriteFile(path, content, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	sum := sha256.Sum256(content)
+	release, err := claimVerifiedInstallerForExecution(path, hex.EncodeToString(sum[:]))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte("tampered"), 0o700); err == nil {
+		release()
+		t.Fatal("installer remained writable while execution claim was held")
+	}
+	if err := os.Rename(path, path+".replaced"); err == nil {
+		release()
+		t.Fatal("installer remained renameable while execution claim was held")
+	}
+	release()
+	release()
+	if err := os.WriteFile(path, []byte("replacement"), 0o700); err != nil {
+		t.Fatalf("installer remained frozen after claim release: %v", err)
+	}
+}
+
+func TestClaimVerifiedInstallerForExecutionRejectsHashDrift(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "installer.exe")
+	if err := os.WriteFile(path, []byte("tampered"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if release, err := claimVerifiedInstallerForExecution(path, testInstallerSHA256); err == nil {
+		release()
+		t.Fatal("installer with the wrong SHA-256 received an execution claim")
+	}
+}
@@ -0,0 +1,238 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"reasonix/desktop/internal/update"
+	"reasonix/internal/repair"
+)
+
+const maxWindowsPayloadMetadataSize = 64 << 10
+
+var verifyWindowsPayloadManifestFn = update.Verify
+
+type stagedFileUpdateMember struct {
+	targetPath string
+	content    []byte
+	mode       os.FileMode
+}
+
+// loadWindowsStagedReleaseUnit validates and reads the complete NSIS payload
+// before any live release-unit member is moved. An existing Reasonix.exe is the
+// portable alias of reasonix-launcher.exe and reuses those staged bytes; an
+// installed package that did not have the alias remains unchanged.
+func loadWindowsStagedReleaseUnit(claimed *repair.UpdateTransaction, stagingDir string) ([]stagedFileUpdateMember, error) {
+	if claimed == nil || claimed.TargetKind != "file" || len(claimed.Files) == 0 {
+		return nil, fmt.Errorf("load staged release unit: transaction identity is incomplete")
+	}
+	if err := validateWindowsClaimedReleaseUnit(claimed); err != nil {
+		return nil, fmt.Errorf("load staged release unit: %w", err)
+	}
+	stagingDir = filepath.Clean(strings.TrimSpace(stagingDir))
+	if stagingDir == "" || stagingDir == "." || !filepath.IsAbs(stagingDir) {
+		return nil, fmt.Errorf("load staged release unit: staging directory is invalid")
+	}
+	info, err := os.Lstat(stagingDir)
+	if err != nil {
+		return nil, fmt.Errorf("load staged release unit: inspect staging directory: %w", err)
+	}
+	if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+		return nil, fmt.Errorf("load staged release unit: staging path is not a directory")
+	}
+	hashes, err := loadWindowsPayloadManifest(stagingDir, claimed.ToVersion)
+	if err != nil {
+		return nil, fmt.Errorf("load staged release unit: %w", err)
+	}
+
+	contents := make(map[string][]byte)
+	members := make([]stagedFileUpdateMember, 0, len(claimed.Files))
+	seenTargets := make(map[string]struct{}, len(claimed.Files))
+	for _, file := range claimed.Files {
+		targetPath := filepath.Clean(strings.TrimSpace(file.TargetPath))
+		targetKey := strings.ToLower(targetPath)
+		if targetPath == "" || targetPath == "." {
+			return nil, fmt.Errorf("load staged release unit: target path is invalid")
+		}
+		if _, ok := seenTargets[targetKey]; ok {
+			return nil, fmt.Errorf("load staged release unit: duplicate target %s", filepath.Base(targetPath))
+		}
+		seenTargets[targetKey] = struct{}{}
+		if strings.EqualFold(filepath.Base(targetPath), "Reasonix.exe") && file.MissingBefore {
+			continue
+		}
+
+		sourceName, err := windowsStagedSourceName(filepath.Base(targetPath))
+		if err != nil {
+			return nil, err
+		}
+		sourcePath := filepath.Join(stagingDir, sourceName)
+		content, ok := contents[sourceName]
+		if !ok {
+			sourceInfo, statErr := os.Lstat(sourcePath)
+			if statErr != nil {
+				return nil, fmt.Errorf("load staged release unit: inspect %s: %w", sourceName, statErr)
+			}
+			if !sourceInfo.Mode().IsRegular() {
+				return nil, fmt.Errorf("load staged release unit: %s is not a regular file", sourceName)
+			}
+			content, err = readVerifiedWindowsStagedPayloadFn(sourcePath)
+			if err != nil {
+				return nil, fmt.Errorf("load staged release unit: read %s: %w", sourceName, err)
+			}
+			if !strings.EqualFold(update.WindowsPayloadSHA256(content), hashes[sourceName]) {
+				return nil, fmt.Errorf("load staged release unit: %s does not match the signed release manifest", sourceName)
+			}
+			contents[sourceName] = content
+		}
+		members = append(members, stagedFileUpdateMember{
+			targetPath: targetPath,
+			content:    content,
+			mode:       0o700,
+		})
+	}
+
+	// Publish the running desktop last. If an earlier member fails, the old
+	// desktop remains the executable entry point that can report/retry recovery.
+	sort.SliceStable(members, func(i, j int) bool {
+		iPrimary := strings.EqualFold(members[i].targetPath, claimed.TargetPath)
+		jPrimary := strings.EqualFold(members[j].targetPath, claimed.TargetPath)
+		return !iPrimary && jPrimary
+	})
+	return members, nil
+}
+
+func validateWindowsClaimedReleaseUnit(claimed *repair.UpdateTransaction) error {
+	if claimed == nil ||
+		!strings.EqualFold(filepath.Base(claimed.TargetPath), "reasonix-desktop.exe") {
+		return fmt.Errorf("claimed release unit primary executable is invalid")
+	}
+	required := map[string]bool{
+		"reasonix-desktop.exe":       false,
+		"reasonix-guard.exe":         false,
+		"reasonix-launcher.exe":      false,
+		"reasonix-update-helper.exe": false,
+		"reasonix-cli.exe":           false,
+		"reasonix.exe":               false,
+	}
+	installDir := filepath.Clean(filepath.Dir(claimed.TargetPath))
+	for _, file := range claimed.Files {
+		target := filepath.Clean(strings.TrimSpace(file.TargetPath))
+		if target == "" || target == "." ||
+			!strings.EqualFold(filepath.Dir(target), installDir) {
+			return fmt.Errorf("claimed release unit target is outside the installation directory")
+		}
+		name := strings.ToLower(filepath.Base(target))
+		seen, ok := required[name]
+		if !ok {
+			return fmt.Errorf("claimed release unit contains an unexpected target")
+		}
+		if seen {
+			return fmt.Errorf("claimed release unit contains a duplicate target")
+		}
+		required[name] = true
+	}
+	for name, seen := range required {
+		if !seen {
+			return fmt.Errorf("claimed release unit omits %s", name)
+		}
+	}
+	if len(claimed.Files) != len(required) {
+		return fmt.Errorf("claimed release unit contains an unexpected target")
+	}
+	return nil
+}
+
+func loadWindowsPayloadManifest(stagingDir, expectedVersion string) (map[string]string, error) {
+	manifest, err := readWindowsPayloadMetadata(filepath.Join(stagingDir, update.WindowsPayloadManifestName))
+	if err != nil {
+		return nil, fmt.Errorf("read signed release manifest: %w", err)
+	}
+	signature, err := readWindowsPayloadMetadata(filepath.Join(stagingDir, update.WindowsPayloadSignatureName))
+	if err != nil {
+		return nil, fmt.Errorf("read signed release manifest signature: %w", err)
+	}
+	if err := verifyWindowsPayloadManifestFn(manifest, signature); err != nil {
+		return nil, fmt.Errorf("verify signed release manifest: %w", err)
+	}
+	hashes, err := update.DecodeWindowsPayloadManifest(manifest, expectedVersion)
+	if err != nil {
+		return nil, err
+	}
+	return hashes, nil
+}
+
+func readWindowsPayloadMetadata(path string) ([]byte, error) {
+	pathInfo, err := os.Lstat(path)
+	if err != nil {
+		return nil, err
+	}
+	if !pathInfo.Mode().IsRegular() {
+		return nil, fmt.Errorf("%s is not a regular file", filepath.Base(path))
+	}
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer file.Close()
+	info, err := file.Stat()
+	if err != nil {
+		return nil, err
+	}
+	if !info.Mode().IsRegular() || info.Size() <= 0 || info.Size() > maxWindowsPayloadMetadataSize {
+		return nil, fmt.Errorf("%s is not a bounded regular file", filepath.Base(path))
+	}
+	if !os.SameFile(pathInfo, info) {
+		return nil, fmt.Errorf("%s changed before it was opened", filepath.Base(path))
+	}
+	data, err := io.ReadAll(io.LimitReader(file, maxWindowsPayloadMetadataSize+1))
+	if err != nil {
+		return nil, err
+	}
+	if len(data) == 0 || len(data) > maxWindowsPayloadMetadataSize {
+		return nil, fmt.Errorf("%s changed size while it was read", filepath.Base(path))
+	}
+	return data, nil
+}
+
+func windowsStagedSourceName(targetBase string) (string, error) {
+	switch strings.ToLower(strings.TrimSpace(targetBase)) {
+	case "reasonix-desktop.exe":
+		return "reasonix-desktop.exe", nil
+	case "reasonix-guard.exe":
+		return "reasonix-guard.exe", nil
+	case "reasonix-launcher.exe":
+		return "reasonix-launcher.exe", nil
+	case "reasonix-update-helper.exe":
+		return "reasonix-update-helper.exe", nil
+	case "reasonix-cli.exe":
+		return "reasonix-cli.exe", nil
+	case "reasonix.exe":
+		return "reasonix-launcher.exe", nil
+	default:
+		return "", fmt.Errorf("load staged release unit: unsupported target %q", targetBase)
+	}
+}
+
+func publishLoadedFileUpdateReleaseUnit(
+	claimed *repair.UpdateTransaction,
+	members []stagedFileUpdateMember,
+	publish func(*repair.UpdateTransaction, string, []byte, os.FileMode) (repair.FileUpdateInstallReceipt, error),
+) ([]repair.FileUpdateInstallReceipt, error) {
+	if publish == nil || len(members) == 0 {
+		return nil, fmt.Errorf("publish staged release unit: payload is incomplete")
+	}
+	receipts := make([]repair.FileUpdateInstallReceipt, 0, len(members))
+	for _, member := range members {
+		receipt, err := publish(claimed, member.targetPath, member.content, member.mode)
+		if err != nil {
+			return receipts, fmt.Errorf("publish staged release unit %s: %w", filepath.Base(member.targetPath), err)
+		}
+		receipts = append(receipts, receipt)
+	}
+	return receipts, nil
+}
@@ -0,0 +1,376 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"reasonix/desktop/internal/update"
+	"reasonix/internal/repair"
+)
+
+func TestLoadWindowsStagedReleaseUnitPreflightsAllMembersAndPublishesDesktopLast(t *testing.T) {
+	staging := t.TempDir()
+	for name, content := range map[string]string{
+		"reasonix-desktop.exe":       "desktop-v2",
+		"reasonix-guard.exe":         "guard-v2",
+		"reasonix-launcher.exe":      "launcher-v2",
+		"reasonix-update-helper.exe": "helper-v2",
+		"reasonix-cli.exe":           "cli-v2",
+	} {
+		if err := os.WriteFile(filepath.Join(staging, name), []byte(content), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	useTestWindowsPayloadManifest(t, staging, "v2")
+	installDir := t.TempDir()
+	claimed := &repair.UpdateTransaction{
+		SchemaVersion: 1,
+		ToVersion:     "v2",
+		TargetKind:    "file",
+		TargetPath:    filepath.Join(installDir, "reasonix-desktop.exe"),
+		Files: []repair.UpdateTransactionFile{
+			{TargetPath: filepath.Join(installDir, "reasonix-desktop.exe")},
+			{TargetPath: filepath.Join(installDir, "reasonix-guard.exe")},
+			{TargetPath: filepath.Join(installDir, "reasonix-launcher.exe")},
+			{TargetPath: filepath.Join(installDir, "reasonix-update-helper.exe")},
+			{TargetPath: filepath.Join(installDir, "reasonix-cli.exe")},
+			{TargetPath: filepath.Join(installDir, "Reasonix.exe")},
+		},
+	}
+
+	members, err := loadWindowsStagedReleaseUnit(claimed, staging)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := filepath.Base(members[len(members)-1].targetPath); !strings.EqualFold(got, "reasonix-desktop.exe") {
+		t.Fatalf("last published member = %q, want desktop", got)
+	}
+	var published []string
+	receipts, err := publishLoadedFileUpdateReleaseUnit(claimed, members, func(_ *repair.UpdateTransaction, target string, content []byte, _ os.FileMode) (repair.FileUpdateInstallReceipt, error) {
+		published = append(published, filepath.Base(target)+"="+string(content))
+		return repair.FileUpdateInstallReceipt{TargetPath: target}, nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(receipts) != len(members) {
+		t.Fatalf("publish receipts = %d, want %d", len(receipts), len(members))
+	}
+	if got := strings.Join(published, ","); !strings.Contains(got, "Reasonix.exe=launcher-v2") {
+		t.Fatalf("portable alias did not reuse launcher payload: %s", got)
+	}
+	if !strings.HasPrefix(published[len(published)-1], "reasonix-desktop.exe=") {
+		t.Fatalf("publish order = %v", published)
+	}
+}
+
+func TestLoadWindowsStagedReleaseUnitRejectsIncompletePayloadBeforePublish(t *testing.T) {
+	staging := t.TempDir()
+	if err := os.WriteFile(filepath.Join(staging, "reasonix-desktop.exe"), []byte("desktop-v2"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	useTestWindowsPayloadManifest(t, staging, "v2")
+	installDir := t.TempDir()
+	claimed := &repair.UpdateTransaction{
+		SchemaVersion: 1,
+		ToVersion:     "v2",
+		TargetKind:    "file",
+		TargetPath:    filepath.Join(installDir, "reasonix-desktop.exe"),
+		Files: []repair.UpdateTransactionFile{
+			{TargetPath: filepath.Join(installDir, "reasonix-desktop.exe")},
+			{TargetPath: filepath.Join(installDir, "reasonix-guard.exe")},
+		},
+	}
+	if _, err := loadWindowsStagedReleaseUnit(claimed, staging); err == nil {
+		t.Fatal("incomplete staged release unit was accepted")
+	}
+}
+
+func TestValidateWindowsClaimedReleaseUnitRequiresExactTargets(t *testing.T) {
+	_, complete := completeWindowsStagedReleaseUnitForTest(t, "v2")
+	for i, file := range complete.Files {
+		t.Run("missing-"+strings.ToLower(filepath.Base(file.TargetPath)), func(t *testing.T) {
+			claimed := *complete
+			claimed.Files = append([]repair.UpdateTransactionFile(nil), complete.Files[:i]...)
+			claimed.Files = append(claimed.Files, complete.Files[i+1:]...)
+			if err := validateWindowsClaimedReleaseUnit(&claimed); err == nil ||
+				!strings.Contains(err.Error(), "omits") {
+				t.Fatalf("missing target error = %v", err)
+			}
+		})
+	}
+	t.Run("extra", func(t *testing.T) {
+		claimed := *complete
+		claimed.Files = append(append([]repair.UpdateTransactionFile(nil), complete.Files...),
+			repair.UpdateTransactionFile{TargetPath: filepath.Join(filepath.Dir(complete.TargetPath), "other.exe")})
+		if err := validateWindowsClaimedReleaseUnit(&claimed); err == nil ||
+			!strings.Contains(err.Error(), "unexpected") {
+			t.Fatalf("extra target error = %v", err)
+		}
+	})
+	t.Run("duplicate", func(t *testing.T) {
+		claimed := *complete
+		claimed.Files = append(append([]repair.UpdateTransactionFile(nil), complete.Files...), complete.Files[0])
+		if err := validateWindowsClaimedReleaseUnit(&claimed); err == nil ||
+			!strings.Contains(err.Error(), "duplicate") {
+			t.Fatalf("duplicate target error = %v", err)
+		}
+	})
+	t.Run("outside", func(t *testing.T) {
+		claimed := *complete
+		claimed.Files = append([]repair.UpdateTransactionFile(nil), complete.Files...)
+		claimed.Files[1].TargetPath = filepath.Join(t.TempDir(), filepath.Base(claimed.Files[1].TargetPath))
+		if err := validateWindowsClaimedReleaseUnit(&claimed); err == nil ||
+			!strings.Contains(err.Error(), "outside") {
+			t.Fatalf("outside target error = %v", err)
+		}
+	})
+	t.Run("primary", func(t *testing.T) {
+		claimed := *complete
+		claimed.TargetPath = filepath.Join(filepath.Dir(complete.TargetPath), "reasonix-guard.exe")
+		if err := validateWindowsClaimedReleaseUnit(&claimed); err == nil ||
+			!strings.Contains(err.Error(), "primary") {
+			t.Fatalf("primary target error = %v", err)
+		}
+	})
+}
+
+func TestLoadWindowsStagedReleaseUnitDoesNotCreateMissingPortableAlias(t *testing.T) {
+	staging := t.TempDir()
+	for _, name := range update.WindowsPayloadFileNames() {
+		content := "payload:" + name
+		if err := os.WriteFile(filepath.Join(staging, name), []byte(content), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	useTestWindowsPayloadManifest(t, staging, "v2")
+	installDir := t.TempDir()
+	claimed := &repair.UpdateTransaction{
+		SchemaVersion: 1,
+		ToVersion:     "v2",
+		TargetKind:    "file",
+		TargetPath:    filepath.Join(installDir, "reasonix-desktop.exe"),
+		Files: []repair.UpdateTransactionFile{
+			{TargetPath: filepath.Join(installDir, "reasonix-desktop.exe")},
+			{TargetPath: filepath.Join(installDir, "reasonix-guard.exe")},
+			{TargetPath: filepath.Join(installDir, "reasonix-launcher.exe")},
+			{TargetPath: filepath.Join(installDir, "reasonix-update-helper.exe")},
+			{TargetPath: filepath.Join(installDir, "reasonix-cli.exe")},
+			{TargetPath: filepath.Join(installDir, "Reasonix.exe"), MissingBefore: true},
+		},
+	}
+
+	members, err := loadWindowsStagedReleaseUnit(claimed, staging)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, member := range members {
+		if strings.EqualFold(filepath.Base(member.targetPath), "Reasonix.exe") {
+			t.Fatalf("missing portable alias was added to publish set: %+v", members)
+		}
+	}
+}
+
+func TestPublishLoadedFileUpdateReleaseUnitStopsOnFirstFailedCompareAndPublish(t *testing.T) {
+	claimed := &repair.UpdateTransaction{TargetKind: "file"}
+	members := []stagedFileUpdateMember{
+		{targetPath: "guard.exe", content: []byte("guard"), mode: 0o700},
+		{targetPath: "desktop.exe", content: []byte("desktop"), mode: 0o700},
+	}
+	var published []string
+	receipts, err := publishLoadedFileUpdateReleaseUnit(claimed, members, func(_ *repair.UpdateTransaction, target string, _ []byte, _ os.FileMode) (repair.FileUpdateInstallReceipt, error) {
+		published = append(published, target)
+		return repair.FileUpdateInstallReceipt{}, errors.New("concurrent recreation")
+	})
+	if err == nil || !strings.Contains(err.Error(), "concurrent recreation") {
+		t.Fatalf("publish error = %v", err)
+	}
+	if len(published) != 1 {
+		t.Fatalf("published members = %v, want one attempted member", published)
+	}
+	if len(receipts) != 0 {
+		t.Fatalf("failed first publish returned receipts: %+v", receipts)
+	}
+}
+
+func TestLoadWindowsStagedReleaseUnitRejectsUnverifiedPayloadBeforePublish(t *testing.T) {
+	staging := t.TempDir()
+	for _, name := range []string{
+		"reasonix-desktop.exe",
+		"reasonix-guard.exe",
+		"reasonix-launcher.exe",
+		"reasonix-update-helper.exe",
+		"reasonix-cli.exe",
+	} {
+		if err := os.WriteFile(filepath.Join(staging, name), []byte(name), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	writeWindowsPayloadManifestForTest(t, staging, "v2")
+	acceptWindowsPayloadManifestForTest(t)
+	_, claimed := completeWindowsStagedReleaseUnitForTest(t, "v2")
+	original := readVerifiedWindowsStagedPayloadFn
+	readVerifiedWindowsStagedPayloadFn = func(string) ([]byte, error) {
+		return nil, errors.New("payload signature rejected")
+	}
+	t.Cleanup(func() { readVerifiedWindowsStagedPayloadFn = original })
+
+	if _, err := loadWindowsStagedReleaseUnit(claimed, staging); err == nil {
+		t.Fatal("unsigned staged payload must be rejected before publication")
+	}
+}
+
+func TestLoadWindowsStagedReleaseUnitReadsEachSourceThroughVerifier(t *testing.T) {
+	staging := t.TempDir()
+	for name, content := range map[string]string{
+		"reasonix-desktop.exe":       "desktop-v2",
+		"reasonix-guard.exe":         "guard-v2",
+		"reasonix-launcher.exe":      "launcher-v2",
+		"reasonix-update-helper.exe": "helper-v2",
+		"reasonix-cli.exe":           "cli-v2",
+	} {
+		if err := os.WriteFile(filepath.Join(staging, name), []byte(content), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	writeWindowsPayloadManifestForTest(t, staging, "v2")
+	acceptWindowsPayloadManifestForTest(t)
+	_, claimed := completeWindowsStagedReleaseUnitForTest(t, "v2")
+	var verified []string
+	original := readVerifiedWindowsStagedPayloadFn
+	readVerifiedWindowsStagedPayloadFn = func(path string) ([]byte, error) {
+		verified = append(verified, filepath.Base(path))
+		return os.ReadFile(path)
+	}
+	t.Cleanup(func() { readVerifiedWindowsStagedPayloadFn = original })
+
+	if _, err := loadWindowsStagedReleaseUnit(claimed, staging); err != nil {
+		t.Fatal(err)
+	}
+	if len(verified) != len(update.WindowsPayloadFileNames()) {
+		t.Fatalf("verified payload count = %d, want %d (%v)", len(verified), len(update.WindowsPayloadFileNames()), verified)
+	}
+}
+
+func TestLoadWindowsStagedReleaseUnitRejectsMissingManifest(t *testing.T) {
+	staging, claimed := completeWindowsStagedReleaseUnitForTest(t, "v2")
+	useUnverifiedPayloadReaderForTest(t)
+	if _, err := loadWindowsStagedReleaseUnit(claimed, staging); err == nil ||
+		!strings.Contains(err.Error(), update.WindowsPayloadManifestName) {
+		t.Fatalf("missing signed manifest error = %v", err)
+	}
+}
+
+func TestLoadWindowsStagedReleaseUnitRejectsBadManifestSignature(t *testing.T) {
+	staging, claimed := completeWindowsStagedReleaseUnitForTest(t, "v2")
+	writeWindowsPayloadManifestForTest(t, staging, "v2")
+	useUnverifiedPayloadReaderForTest(t)
+	if _, err := loadWindowsStagedReleaseUnit(claimed, staging); err == nil ||
+		!strings.Contains(err.Error(), "verify signed release manifest") {
+		t.Fatalf("bad signed manifest error = %v", err)
+	}
+}
+
+func TestLoadWindowsStagedReleaseUnitRejectsManifestVersionDrift(t *testing.T) {
+	staging, claimed := completeWindowsStagedReleaseUnitForTest(t, "v2")
+	writeWindowsPayloadManifestForTest(t, staging, "v3")
+	acceptWindowsPayloadManifestForTest(t)
+	useUnverifiedPayloadReaderForTest(t)
+	if _, err := loadWindowsStagedReleaseUnit(claimed, staging); err == nil ||
+		!strings.Contains(err.Error(), "identity does not match") {
+		t.Fatalf("release version drift error = %v", err)
+	}
+}
+
+func TestLoadWindowsStagedReleaseUnitRejectsManifestMemberHashDrift(t *testing.T) {
+	staging, claimed := completeWindowsStagedReleaseUnitForTest(t, "v2")
+	writeWindowsPayloadManifestForTest(t, staging, "v2")
+	acceptWindowsPayloadManifestForTest(t)
+	useUnverifiedPayloadReaderForTest(t)
+	if err := os.WriteFile(filepath.Join(staging, "reasonix-guard.exe"), []byte("tampered"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := loadWindowsStagedReleaseUnit(claimed, staging); err == nil ||
+		!strings.Contains(err.Error(), "does not match the signed release manifest") {
+		t.Fatalf("release member drift error = %v", err)
+	}
+}
+
+func completeWindowsStagedReleaseUnitForTest(t *testing.T, version string) (string, *repair.UpdateTransaction) {
+	t.Helper()
+	staging := t.TempDir()
+	for _, name := range update.WindowsPayloadFileNames() {
+		if err := os.WriteFile(filepath.Join(staging, name), []byte("payload:"+name), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	installDir := t.TempDir()
+	files := make([]repair.UpdateTransactionFile, 0, len(update.WindowsPayloadFileNames())+1)
+	for _, name := range update.WindowsPayloadFileNames() {
+		files = append(files, repair.UpdateTransactionFile{TargetPath: filepath.Join(installDir, name)})
+	}
+	files = append(files, repair.UpdateTransactionFile{
+		TargetPath:    filepath.Join(installDir, "Reasonix.exe"),
+		MissingBefore: true,
+	})
+	return staging, &repair.UpdateTransaction{
+		SchemaVersion: 1,
+		ToVersion:     version,
+		TargetKind:    "file",
+		TargetPath:    filepath.Join(installDir, "reasonix-desktop.exe"),
+		Files:         files,
+	}
+}
+
+func writeWindowsPayloadManifestForTest(t *testing.T, staging, version string) {
+	t.Helper()
+	hashes := make(map[string]string)
+	for _, name := range update.WindowsPayloadFileNames() {
+		content, err := os.ReadFile(filepath.Join(staging, name))
+		if os.IsNotExist(err) {
+			content = []byte("missing:" + name)
+		} else if err != nil {
+			t.Fatal(err)
+		}
+		hashes[name] = update.WindowsPayloadSHA256(content)
+	}
+	manifest, err := update.EncodeWindowsPayloadManifest(version, hashes)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(staging, update.WindowsPayloadManifestName), manifest, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(staging, update.WindowsPayloadSignatureName), []byte("test signature"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func acceptWindowsPayloadManifestForTest(t *testing.T) {
+	t.Helper()
+	original := verifyWindowsPayloadManifestFn
+	verifyWindowsPayloadManifestFn = func(_, signature []byte) error {
+		if string(signature) != "test signature" {
+			return errors.New("unexpected test signature")
+		}
+		return nil
+	}
+	t.Cleanup(func() { verifyWindowsPayloadManifestFn = original })
+}
+
+func useTestWindowsPayloadManifest(t *testing.T, staging, version string) {
+	t.Helper()
+	writeWindowsPayloadManifestForTest(t, staging, version)
+	acceptWindowsPayloadManifestForTest(t)
+	useUnverifiedPayloadReaderForTest(t)
+}
+
+func useUnverifiedPayloadReaderForTest(t *testing.T) {
+	t.Helper()
+	original := readVerifiedWindowsStagedPayloadFn
+	readVerifiedWindowsStagedPayloadFn = os.ReadFile
+	t.Cleanup(func() { readVerifiedWindowsStagedPayloadFn = original })
+}
@@ -0,0 +1,118 @@
+//go:build windows
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"reasonix/internal/installlayout"
+	"reasonix/internal/repair"
+)
+
+// activateVersionedWindowsFromStaging publishes the versioned-v1 layout from a
+// staged NSIS payload:
+//
+//	InstallRoot/
+//	  reasonix-launcher.exe
+//	  Reasonix.exe              (launcher alias when present or portable)
+//	  reasonix-cli.exe          (CLI entry; full binary for now)
+//	  current.json
+//	  versions/<version>/
+//	    reasonix-desktop.exe
+//	    reasonix-cli.exe
+//	    reasonix-update-helper.exe
+//
+// Any failure before the current.json pointer swap leaves the previous active
+// version unchanged. The helper never counts crashes or selects prior versions.
+func activateVersionedWindowsFromStaging(claimed *repair.UpdateTransaction, stagingDir string) error {
+	if claimed == nil {
+		return fmt.Errorf("versioned activate: transaction is nil")
+	}
+	installRoot := filepath.Clean(strings.TrimSpace(filepath.Dir(claimed.TargetPath)))
+	// When the claimed primary is already under versions/<ver>/, climb to root.
+	if root, err := installlayout.ResolveInstallRoot(claimed.TargetPath); err == nil && root != "" {
+		installRoot = root
+	}
+	version := strings.TrimSpace(claimed.ToVersion)
+	if err := installlayout.ValidateVersionName(version); err != nil {
+		// Accept bare product versions from NSIS (1.20.0 → v1.20.0).
+		if !strings.HasPrefix(version, "v") {
+			version = "v" + version
+		}
+		if err := installlayout.ValidateVersionName(version); err != nil {
+			return fmt.Errorf("versioned activate: %w", err)
+		}
+	}
+	stagingDir = filepath.Clean(strings.TrimSpace(stagingDir))
+
+	desktopSrc := filepath.Join(stagingDir, "reasonix-desktop.exe")
+	cliSrc := filepath.Join(stagingDir, "reasonix-cli.exe")
+	helperSrc := filepath.Join(stagingDir, "reasonix-update-helper.exe")
+	launcherSrc := filepath.Join(stagingDir, "reasonix-launcher.exe")
+	for _, path := range []string{desktopSrc, cliSrc, helperSrc, launcherSrc} {
+		info, err := os.Lstat(path)
+		if err != nil {
+			return fmt.Errorf("versioned activate: staged %s: %w", filepath.Base(path), err)
+		}
+		if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 {
+			return fmt.Errorf("versioned activate: staged %s is not a regular file", filepath.Base(path))
+		}
+	}
+
+	requestID := repair.UpdateTransactionID(claimed)
+	if requestID == "" {
+		requestID = "helper-" + version
+	}
+	if err := installlayout.ActivateVersion(installlayout.ActivationRequest{
+		InstallRoot: installRoot,
+		Version:     version,
+		RequestID:   requestID,
+		Members: []installlayout.Member{
+			{Name: "reasonix-desktop.exe", Path: desktopSrc, Mode: 0o700},
+			{Name: "reasonix-cli.exe", Path: cliSrc, Mode: 0o700},
+			{Name: "reasonix-update-helper.exe", Path: helperSrc, Mode: 0o700},
+		},
+		RootMembers: []installlayout.Member{
+			{Name: "reasonix-launcher.exe", Path: launcherSrc, Mode: 0o700},
+			{Name: "Reasonix.exe", Path: launcherSrc, Mode: 0o700},
+			{Name: "reasonix-cli.exe", Path: cliSrc, Mode: 0o700},
+		},
+		RequiredRootNames: []string{"reasonix-launcher.exe", "Reasonix.exe", "reasonix-cli.exe"},
+	}); err != nil {
+		return err
+	}
+
+	// Remove flat release-unit leftovers so the install root is the thin layout.
+	// Do not remove the launcher/CLI/alias we just wrote.
+	for _, name := range []string{
+		"reasonix-desktop.exe",
+		"reasonix-guard.exe",
+		"reasonix-update-helper.exe", // helper lives only under versions/
+	} {
+		_ = os.Remove(filepath.Join(installRoot, name))
+	}
+	// Best-effort retention GC of older version trees.
+	_ = installlayout.RetainPreviousVersions(installRoot, 0)
+	_ = installlayout.CleanupStaleStaging(installRoot, 0)
+	return nil
+}
+
+// preferVersionedWindowsActivation reports whether the staged payload is
+// complete enough for versioned-v1 activation.
+func preferVersionedWindowsActivation(stagingDir string) bool {
+	for _, name := range []string{
+		"reasonix-desktop.exe",
+		"reasonix-cli.exe",
+		"reasonix-update-helper.exe",
+		"reasonix-launcher.exe",
+	} {
+		info, err := os.Lstat(filepath.Join(stagingDir, name))
+		if err != nil || !info.Mode().IsRegular() {
+			return false
+		}
+	}
+	return true
+}
@@ -0,0 +1,129 @@
+//go:build windows
+
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"reasonix/internal/installlayout"
+	"reasonix/internal/repair"
+)
+
+func TestPreferVersionedWindowsActivation(t *testing.T) {
+	staging := t.TempDir()
+	if preferVersionedWindowsActivation(staging) {
+		t.Fatal("empty staging must not prefer versioned")
+	}
+	for _, name := range []string{
+		"reasonix-desktop.exe",
+		"reasonix-cli.exe",
+		"reasonix-update-helper.exe",
+		"reasonix-launcher.exe",
+	} {
+		if err := os.WriteFile(filepath.Join(staging, name), []byte(name), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if !preferVersionedWindowsActivation(staging) {
+		t.Fatal("complete staging must prefer versioned")
+	}
+}
+
+func TestActivateVersionedWindowsFromStaging(t *testing.T) {
+	installDir := t.TempDir()
+	staging := t.TempDir()
+	for _, name := range []string{
+		"reasonix-desktop.exe",
+		"reasonix-cli.exe",
+		"reasonix-update-helper.exe",
+		"reasonix-launcher.exe",
+		"reasonix-guard.exe",
+	} {
+		if err := os.WriteFile(filepath.Join(staging, name), []byte("payload:"+name), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// Seed a flat desktop so cleanup is observable.
+	if err := os.WriteFile(filepath.Join(installDir, "reasonix-desktop.exe"), []byte("old"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(installDir, "reasonix-guard.exe"), []byte("old-guard"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+
+	claimed := &repair.UpdateTransaction{
+		SchemaVersion: 1,
+		ToVersion:     "v1.20.0",
+		TargetKind:    "file",
+		TargetPath:    filepath.Join(installDir, "reasonix-desktop.exe"),
+		CreatedAt:     "2026-01-01T00:00:00Z",
+	}
+	if err := activateVersionedWindowsFromStaging(claimed, staging); err != nil {
+		t.Fatal(err)
+	}
+	if !installlayout.HasCurrent(installDir) {
+		t.Fatal("current.json missing")
+	}
+	ptr, err := installlayout.ReadCurrent(installDir)
+	if err != nil || ptr.ActiveVersion != "v1.20.0" {
+		t.Fatalf("pointer=%+v err=%v", ptr, err)
+	}
+	desktop, err := installlayout.ActiveDesktopPath(installDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, err := os.ReadFile(desktop)
+	if err != nil || string(raw) != "payload:reasonix-desktop.exe" {
+		t.Fatalf("desktop payload = %q err=%v", raw, err)
+	}
+	for _, name := range []string{"reasonix-launcher.exe", "Reasonix.exe", "reasonix-cli.exe"} {
+		if _, err := os.Stat(filepath.Join(installDir, name)); err != nil {
+			t.Fatalf("root entry %s: %v", name, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(installDir, "reasonix-desktop.exe")); !os.IsNotExist(err) {
+		t.Fatal("flat desktop should be removed")
+	}
+	if _, err := os.Stat(filepath.Join(installDir, "reasonix-guard.exe")); !os.IsNotExist(err) {
+		t.Fatal("flat guard should be removed")
+	}
+	if prefer := preferRelaunchPath("", installDir); filepath.Base(prefer) != "reasonix-launcher.exe" {
+		t.Fatalf("prefer relaunch = %s", prefer)
+	}
+}
+
+func TestInstallStagedWindowsReleaseUnitPrefersVersioned(t *testing.T) {
+	installDir := t.TempDir()
+	staging := t.TempDir()
+	for _, name := range []string{
+		"reasonix-desktop.exe",
+		"reasonix-cli.exe",
+		"reasonix-update-helper.exe",
+		"reasonix-launcher.exe",
+		"reasonix-guard.exe",
+	} {
+		if err := os.WriteFile(filepath.Join(staging, name), []byte("p:"+name), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// Minimal claimed unit (versioned path does not need full flat file list).
+	claimed := &repair.UpdateTransaction{
+		SchemaVersion: 1,
+		ToVersion:     "v1.20.0",
+		TargetKind:    "file",
+		TargetPath:    filepath.Join(installDir, "reasonix-desktop.exe"),
+		CreatedAt:     "2026-01-01T00:00:00Z",
+	}
+	started, receipts, err := installStagedWindowsReleaseUnit(claimed, staging)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !started || receipts != nil {
+		t.Fatalf("started=%v receipts=%v want started with nil receipts", started, receipts)
+	}
+	if !installlayout.HasCurrent(installDir) {
+		t.Fatal("versioned activation did not write current.json")
+	}
+}
@@ -11,8 +11,9 @@ import (
 	"strings"
 )

-// crash_app.go is the crash/feedback/performance reporting surface. Reports are
-// sent only on an explicit user click in the frontend UI — never automatically.
+// crash_app.go is the crash/feedback/performance reporting surface. Frontend
+// reports are sent on an explicit user click. Native fatal/lifecycle reports are
+// queued locally and sent on a later launch only when desktop telemetry is on.

 var crashEndpoint = "https://crash.reasonix.io/v1/report"

@@ -0,0 +1,270 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"reasonix/internal/repair"
+)
+
+func TestParseWebView2ProcessFailure(t *testing.T) {
+	kind, ok := parseWebView2ProcessFailure("windows | WebVie2wProcess failed with kind 6")
+	if !ok || kind != 6 {
+		t.Fatalf("kind=%d ok=%v", kind, ok)
+	}
+	if _, ok := parseWebView2ProcessFailure("unrelated failure"); ok {
+		t.Fatal("unrelated log message matched WebView2 failure")
+	}
+}
+
+func TestWebView2ProcessFailureReportIsStructured(t *testing.T) {
+	report := webView2ProcessFailureReport(2)
+	if report.Source != "webview2.process" || report.Label != "windows.webview2.process_failed" {
+		t.Fatalf("report = %+v", report)
+	}
+	if report.FingerprintHint != "windows.webview2.render_process_unresponsive" {
+		t.Fatalf("fingerprint hint = %q", report.FingerprintHint)
+	}
+}
+
+func TestPreviousRunReportUsesOnlyBoundedLifecycleContext(t *testing.T) {
+	report := previousRunReport(repair.PreviousRunObservation{
+		Abnormal:       true,
+		Phase:          "healthy",
+		Version:        "v2",
+		InstallProfile: "installer",
+		UpdateFrom:     "v1",
+		UpdateTo:       "v2",
+		UptimeBucket:   "m_2_10",
+	})
+	if report.Source != "native.lifecycle" || report.Label != "desktop.abnormal_exit" {
+		t.Fatalf("report = %+v", report)
+	}
+	if !strings.Contains(report.Message, "uptime bucket: m_2_10") {
+		t.Fatalf("message missing bounded uptime: %q", report.Message)
+	}
+}
+
+func TestCapturePreviousFatalCrashQueuesAndRemovesRawDump(t *testing.T) {
+	resetFatalCrashArtifacts(t)
+	const crashedPID = 424242
+	raw := "fatal error: concurrent map writes\n\ngoroutine 1 [running]:\nmain.run()\n\t/home/alice/project/main.go:12\n"
+	path := fatalCrashPathForPID(crashedPID)
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(raw), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	capturePreviousFatalCrash()
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Fatalf("raw fatal dump was not removed: %v", err)
+	}
+	report, ok := readPending(t)
+	if !ok || report.Label != "go.fatal" || report.Source != "go.runtime" {
+		t.Fatalf("queued report = %+v ok=%v", report, ok)
+	}
+	if strings.Contains(report.Stack, "/home/alice") {
+		t.Fatalf("fatal stack leaked home path: %q", report.Stack)
+	}
+}
+
+func TestSanitizeFatalRuntimeDumpRemovesPanicValue(t *testing.T) {
+	got := sanitizeFatalRuntimeDump("panic: private prompt text\n\ngoroutine 1 [running]:\nmain.run()\n\t/home/alice/project/main.go:12\n")
+	if strings.Contains(got, "private prompt text") || strings.Contains(got, "/home/alice") {
+		t.Fatalf("fatal dump leaked user-controlled text: %q", got)
+	}
+	if !strings.Contains(got, "panic: [redacted panic value]") || !strings.Contains(got, "main.go:12") {
+		t.Fatalf("fatal dump lost diagnostic structure: %q", got)
+	}
+}
+
+func TestCapturePreviousFatalCrashSkipsRuntimeDuplicateOfStructuredPanic(t *testing.T) {
+	resetFatalCrashArtifacts(t)
+	const crashedPID = 424243
+	path := fatalCrashPathForPID(crashedPID)
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte("panic: duplicate\n\ngoroutine 1 [running]:\nmain.run()\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	markFatalCrashCoveredForPID(crashedPID)
+	capturePreviousFatalCrash()
+	if _, ok := readPending(t); ok {
+		t.Fatal("runtime duplicate was queued despite structured panic marker")
+	}
+}
+
+func TestCapturePreviousFatalCrashDoesNotTouchLiveOwner(t *testing.T) {
+	resetFatalCrashArtifacts(t)
+	const livePID = 424244
+	path := fatalCrashPathForPID(livePID)
+	raw := []byte("fatal error: still being written\n\ngoroutine 1 [running]:\n")
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, raw, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	oldProcessAlive := fatalCrashProcessAlive
+	fatalCrashProcessAlive = func(pid int) bool { return pid == livePID }
+	t.Cleanup(func() { fatalCrashProcessAlive = oldProcessAlive })
+
+	capturePreviousFatalCrash()
+
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("live owner's fatal file was removed: %v", err)
+	}
+	if string(got) != string(raw) {
+		t.Fatalf("live owner's fatal file changed: got %q want %q", got, raw)
+	}
+	if _, ok := readPending(t); ok {
+		t.Fatal("live owner's partial fatal output was queued")
+	}
+}
+
+func TestCapturePreviousFatalCrashKeepsEmptyLegacyFile(t *testing.T) {
+	resetFatalCrashArtifacts(t)
+	if err := os.MkdirAll(filepath.Dir(legacyFatalCrashPath()), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(legacyFatalCrashPath(), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	capturePreviousFatalCrash()
+
+	if _, err := os.Stat(legacyFatalCrashPath()); err != nil {
+		t.Fatalf("empty legacy fatal file may belong to a live older process: %v", err)
+	}
+}
+
+func TestCapturePreviousFatalCrashMigratesLegacyDump(t *testing.T) {
+	resetFatalCrashArtifacts(t)
+	raw := "fatal error: legacy crash\n\ngoroutine 1 [running]:\nmain.run()\n\t/home/alice/project/main.go:12\n"
+	if err := os.MkdirAll(filepath.Dir(legacyFatalCrashPath()), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(legacyFatalCrashPath(), []byte(raw), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	capturePreviousFatalCrash()
+
+	if _, err := os.Stat(legacyFatalCrashPath()); !os.IsNotExist(err) {
+		t.Fatalf("captured legacy fatal dump was not removed: %v", err)
+	}
+	report, ok := readPending(t)
+	if !ok || report.Label != "go.fatal" || report.Source != "go.runtime" {
+		t.Fatalf("legacy fatal dump was not migrated: report=%+v ok=%v", report, ok)
+	}
+}
+
+func TestAwaitWindowRestoreRequiresNativeConfirmation(t *testing.T) {
+	ticks := make(chan time.Time)
+	deadline := make(chan time.Time, 1)
+	deadline <- time.Now()
+
+	if awaitWindowRestoreConfirmation(func() bool { return false }, ticks, deadline) {
+		t.Fatal("an enqueued show request without native confirmation was treated as restored")
+	}
+}
+
+func TestAwaitWindowRestoreAcceptsConfirmationAfterTick(t *testing.T) {
+	ticks := make(chan time.Time, 1)
+	deadline := make(chan time.Time)
+	var confirmed atomic.Bool
+	result := make(chan bool, 1)
+	go func() {
+		result <- awaitWindowRestoreConfirmation(confirmed.Load, ticks, deadline)
+	}()
+
+	confirmed.Store(true)
+	ticks <- time.Now()
+	if !<-result {
+		t.Fatal("native window confirmation was not accepted")
+	}
+}
+
+func TestSupersededWindowRestoreDoesNotRemoveLatestJournal(t *testing.T) {
+	path := windowRestoreStatePath()
+	_ = os.Remove(path)
+	t.Cleanup(func() { _ = os.Remove(path) })
+	oldSequence := windowRestoreSequence.Load()
+	t.Cleanup(func() { windowRestoreSequence.Store(oldSequence) })
+
+	latest := windowRestoreState{
+		SchemaVersion: windowRestoreStateVersion,
+		PID:           os.Getpid(),
+		AttemptID:     2,
+		Source:        "tray",
+		StartedAt:     "2026-07-24T08:01:00Z",
+	}
+	if !writeWindowRestoreState(latest) {
+		t.Fatal("write latest window restore state")
+	}
+	windowRestoreSequence.Store(latest.AttemptID)
+
+	NewApp().completeWindowRestoreAttempt(1, windowRestoreState{AttemptID: 1}, true)
+
+	got, err := readWindowRestoreState()
+	if err != nil {
+		t.Fatalf("latest journal was removed by superseded attempt: %v", err)
+	}
+	if got != latest {
+		t.Fatalf("latest journal changed: got %+v want %+v", got, latest)
+	}
+}
+
+func resetFatalCrashArtifacts(t *testing.T) {
+	t.Helper()
+	oldProcessAlive := fatalCrashProcessAlive
+	fatalCrashProcessAlive = func(int) bool { return false }
+	removeAllPendingCrashes()
+	_ = os.Remove(legacyFatalCrashPath())
+	_ = os.Remove(legacyFatalCrashCoveredPath())
+	_ = os.RemoveAll(fatalCrashDir())
+	t.Cleanup(func() {
+		removeAllPendingCrashes()
+		_ = os.Remove(legacyFatalCrashPath())
+		_ = os.Remove(legacyFatalCrashCoveredPath())
+		_ = os.RemoveAll(fatalCrashDir())
+		fatalCrashProcessAlive = oldProcessAlive
+	})
+}
+
+func TestWindowRestoreFailureReportSeparatesTimeoutAndSource(t *testing.T) {
+	report := windowRestoreFailureReport("timeout", "second_instance", "2026-07-24T08:00:00Z")
+	if report.Label != "windows.window_restore.timeout" || report.TopFrame != "windows.window_restore.second_instance" {
+		t.Fatalf("report = %+v", report)
+	}
+}
+
+func TestWriteWindowRestoreStateCreatesReadableJournal(t *testing.T) {
+	path := windowRestoreStatePath()
+	_ = os.Remove(path)
+	t.Cleanup(func() { _ = os.Remove(path) })
+
+	want := windowRestoreState{
+		SchemaVersion: windowRestoreStateVersion,
+		PID:           os.Getpid(),
+		Source:        "tray",
+		StartedAt:     "2026-07-24T08:00:00Z",
+	}
+	if !writeWindowRestoreState(want) {
+		t.Fatal("writeWindowRestoreState returned false")
+	}
+	got, err := readWindowRestoreState()
+	if err != nil {
+		t.Fatalf("readWindowRestoreState: %v", err)
+	}
+	if got != want {
+		t.Fatalf("journal = %+v, want %+v", got, want)
+	}
+}
@@ -0,0 +1,203 @@
+package main
+
+import (
+	"io"
+	"os"
+	"path/filepath"
+	"runtime/debug"
+	"strconv"
+	"strings"
+	"time"
+
+	"reasonix/internal/config"
+)
+
+const (
+	fatalCrashDirName           = "crash-fatal"
+	fatalCrashLogSuffix         = ".log"
+	fatalCrashCoveredSuffix     = ".covered"
+	legacyFatalCrashFile        = "crash-fatal.log"
+	legacyFatalCrashCoveredFile = "crash-fatal-covered"
+)
+
+var fatalCrashProcessAlive = desktopProcessAlive
+
+func fatalCrashDir() string {
+	return filepath.Join(config.MemoryUserDir(), fatalCrashDirName)
+}
+
+func fatalCrashPath() string {
+	return fatalCrashPathForPID(os.Getpid())
+}
+
+func fatalCrashCoveredPath() string {
+	return fatalCrashCoveredPathForPID(os.Getpid())
+}
+
+func fatalCrashPathForPID(pid int) string {
+	return filepath.Join(fatalCrashDir(), strconv.Itoa(pid)+fatalCrashLogSuffix)
+}
+
+func fatalCrashCoveredPathForPID(pid int) string {
+	return filepath.Join(fatalCrashDir(), strconv.Itoa(pid)+fatalCrashCoveredSuffix)
+}
+
+func legacyFatalCrashPath() string {
+	return filepath.Join(config.MemoryUserDir(), legacyFatalCrashFile)
+}
+
+func legacyFatalCrashCoveredPath() string {
+	return filepath.Join(config.MemoryUserDir(), legacyFatalCrashCoveredFile)
+}
+
+func markFatalCrashCovered() {
+	markFatalCrashCoveredForPID(os.Getpid())
+}
+
+func markFatalCrashCoveredForPID(pid int) {
+	path := fatalCrashCoveredPathForPID(pid)
+	if os.MkdirAll(filepath.Dir(path), 0o700) == nil {
+		_ = os.WriteFile(path, []byte("structured\n"), 0o600)
+	}
+}
+
+// capturePreviousFatalCrash converts runtime.SetCrashOutput dumps from dead
+// processes into the normal scrubbed queue. Per-PID files keep a routine second
+// launch from truncating or unlinking the running primary process's dump.
+func capturePreviousFatalCrash() {
+	// Preserve compatibility with the single-file format used by older builds.
+	// An empty legacy file may still be owned by a running older process, so it
+	// must be left untouched until it contains a completed crash dump.
+	captureFatalCrashFile(legacyFatalCrashPath(), legacyFatalCrashCoveredPath(), false)
+
+	entries, err := os.ReadDir(fatalCrashDir())
+	if err != nil {
+		return
+	}
+	for _, entry := range entries {
+		pid, ok := fatalCrashPID(entry.Name())
+		if !ok || pid == os.Getpid() || fatalCrashProcessAlive(pid) {
+			continue
+		}
+		captureFatalCrashFile(
+			filepath.Join(fatalCrashDir(), entry.Name()),
+			fatalCrashCoveredPathForPID(pid),
+			true,
+		)
+	}
+	for _, entry := range entries {
+		pid, ok := fatalCrashCoveredPID(entry.Name())
+		if !ok || pid == os.Getpid() || fatalCrashProcessAlive(pid) {
+			continue
+		}
+		if _, err := os.Stat(fatalCrashPathForPID(pid)); os.IsNotExist(err) {
+			_ = os.Remove(filepath.Join(fatalCrashDir(), entry.Name()))
+		}
+	}
+	// Best effort: succeeds only when no live/current process artifacts remain.
+	_ = os.Remove(fatalCrashDir())
+}
+
+func fatalCrashPID(name string) (int, bool) {
+	return fatalCrashPIDWithSuffix(name, fatalCrashLogSuffix)
+}
+
+func fatalCrashCoveredPID(name string) (int, bool) {
+	return fatalCrashPIDWithSuffix(name, fatalCrashCoveredSuffix)
+}
+
+func fatalCrashPIDWithSuffix(name, suffix string) (int, bool) {
+	if !strings.HasSuffix(name, suffix) {
+		return 0, false
+	}
+	pid, err := strconv.Atoi(strings.TrimSuffix(name, suffix))
+	return pid, err == nil && pid > 0
+}
+
+func captureFatalCrashFile(path, coveredPath string, removeEmpty bool) {
+	f, err := os.Open(path)
+	if err != nil {
+		return
+	}
+	occurredAt := time.Now().UTC()
+	if info, statErr := f.Stat(); statErr == nil {
+		occurredAt = info.ModTime().UTC()
+	}
+	raw, readErr := io.ReadAll(io.LimitReader(f, maxCrashStackBytes+1))
+	_ = f.Close()
+	if readErr != nil || len(strings.TrimSpace(string(raw))) == 0 {
+		if removeEmpty {
+			_ = os.Remove(coveredPath)
+			_ = os.Remove(path)
+		}
+		return
+	}
+	if _, err := os.Stat(coveredPath); err == nil {
+		_ = os.Remove(coveredPath)
+		_ = os.Remove(path)
+		return
+	}
+	stack := sanitizeFatalRuntimeDump(string(raw))
+	report := baseCrashReport("crash")
+	report.SchemaVersion = 2
+	report.Source = "go.runtime"
+	report.Label = "go.fatal"
+	report.ErrorType = "GoRuntimeFatal"
+	report.ErrorMessage = "Go runtime terminated the desktop process."
+	report.Stack = stack
+	report.TopFrame = topFrameFromStack(stack)
+	report.FingerprintHint = "go.runtime.fatal"
+	report.OccurredAt = occurredAt.Format(time.RFC3339)
+	report.Message = sanitizeCrashText("[go.runtime.fatal]\n\n"+stack, maxCrashDetailBytes)
+	if writePendingReport(report, true) {
+		_ = os.Remove(coveredPath)
+		_ = os.Remove(path)
+	}
+}
+
+// sanitizeFatalRuntimeDump removes panic values and preamble text that could
+// originate in user-controlled errors, while retaining runtime classification
+// and symbolized goroutine stacks for diagnosis.
+func sanitizeFatalRuntimeDump(raw string) string {
+	lines := strings.Split(raw, "\n")
+	classification := "runtime crash output"
+	stackStart := -1
+	for i, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		switch {
+		case strings.HasPrefix(trimmed, "fatal error:"):
+			classification = sanitizeCrashText(trimmed, 256)
+		case strings.HasPrefix(trimmed, "panic:"):
+			classification = "panic: [redacted panic value]"
+		}
+		if strings.HasPrefix(trimmed, "goroutine ") {
+			stackStart = i
+			break
+		}
+	}
+	stack := ""
+	if stackStart >= 0 {
+		stack = strings.Join(lines[stackStart:], "\n")
+	}
+	return sanitizeCrashText(classification+"\n\n"+stack, maxCrashStackBytes)
+}
+
+// installFatalCrashOutput asks the Go runtime to mirror unrecovered panics and
+// fatal runtime errors to a durable file. The runtime duplicates the descriptor,
+// so the file may be closed after SetCrashOutput returns.
+func installFatalCrashOutput() {
+	path := fatalCrashPath()
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return
+	}
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600)
+	if err != nil {
+		return
+	}
+	if err := debug.SetCrashOutput(f, debug.CrashOptions{}); err != nil {
+		_ = f.Close()
+		_ = os.Remove(path)
+		return
+	}
+	_ = f.Close()
+}
@@ -6,6 +6,11 @@ import (
 	"os"
 	"path/filepath"
 	"runtime/debug"
+	"sort"
+	"strconv"
+	"sync"
+	"sync/atomic"
+	"time"

 	"reasonix/internal/config"
 )
@@ -16,12 +21,25 @@ import (
 // otherwise never surface a single report. The resend is gated on the same
 // desktop.telemetry opt-out as the launch ping.

-const pendingCrashFile = "crash-pending.json"
+const (
+	pendingCrashFile     = "crash-pending.json" // legacy single-report path
+	pendingCrashQueueDir = "crash-pending"
+	maxPendingCrashes    = 10
+)
+
+var (
+	pendingCrashMu       sync.Mutex
+	pendingCrashSequence atomic.Uint64
+)

 func pendingCrashPath() string {
 	return filepath.Join(config.MemoryUserDir(), pendingCrashFile)
 }

+func pendingCrashDir() string {
+	return filepath.Join(config.MemoryUserDir(), pendingCrashQueueDir)
+}
+
 // recoverToPending records a panicking goroutine to the pending-crash file and
 // re-raises, so the process still crashes exactly as before — the stack is now
 // shipped next launch instead of lost.
@@ -36,44 +54,84 @@ func (a *App) recoverToPending(site string) {

 func writePendingCrash(site string, r any, stack []byte) {
 	stackText := string(stack)
-	msg := sanitizeCrashText(fmt.Sprintf("[go panic] %s: %v\n\n%s", site, r, stackText), maxCrashDetailBytes)
+	msg := sanitizeCrashText(fmt.Sprintf("[go panic] %s\n\n%s", site, stackText), maxCrashDetailBytes)
 	report := baseCrashReport("crash")
 	report.SchemaVersion = 2
 	report.Source = "go"
 	report.Label = sanitizeCrashField(site, 64)
 	report.ErrorType = sanitizeCrashField(fmt.Sprintf("%T", r), 128)
-	report.ErrorMessage = sanitizeCrashText(fmt.Sprint(r), maxCrashFieldBytes)
+	report.ErrorMessage = sanitizeCrashText("Go panic captured at "+site+".", maxCrashFieldBytes)
 	report.Stack = sanitizeCrashText(stackText, maxCrashStackBytes)
 	report.TopFrame = topFrameFromStack(report.Stack)
 	report.Message = msg
-	_ = writePendingReport(report, true)
+	if writePendingReport(report, true) {
+		markFatalCrashCovered()
+	}
 }

 func writePendingReport(report crashReport, overwrite bool) bool {
+	_ = overwrite // retained for source compatibility; the queue never overwrites.
 	body, err := json.Marshal(report)
 	if err != nil {
 		return false
 	}
-	path := pendingCrashPath()
-	if os.MkdirAll(filepath.Dir(path), 0o755) != nil {
+	dir := pendingCrashDir()
+	if os.MkdirAll(dir, 0o700) != nil {
 		return false
 	}
-	if overwrite {
-		return os.WriteFile(path, body, 0o644) == nil
-	}
-	f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
+	pendingCrashMu.Lock()
+	defer pendingCrashMu.Unlock()
+	name := strconv.FormatInt(time.Now().UTC().UnixNano(), 10) + "-" +
+		strconv.Itoa(os.Getpid()) + "-" +
+		strconv.FormatUint(pendingCrashSequence.Add(1), 10) + ".json"
+	path := filepath.Join(dir, name)
+	f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
 	if err != nil {
 		return false
 	}
-	defer f.Close()
 	n, err := f.Write(body)
-	if err != nil || n != len(body) {
+	closeErr := f.Close()
+	if err != nil || closeErr != nil || n != len(body) {
 		_ = os.Remove(path)
 		return false
 	}
+	paths := pendingCrashQueuePaths()
+	for len(paths) > maxPendingCrashes {
+		_ = os.Remove(paths[0])
+		paths = paths[1:]
+	}
 	return true
 }

+func pendingCrashQueuePaths() []string {
+	entries, err := os.ReadDir(pendingCrashDir())
+	if err != nil {
+		return nil
+	}
+	paths := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		if !entry.IsDir() && filepath.Ext(entry.Name()) == ".json" {
+			paths = append(paths, filepath.Join(pendingCrashDir(), entry.Name()))
+		}
+	}
+	sort.Strings(paths)
+	return paths
+}
+
+func pendingCrashPaths() []string {
+	paths := make([]string, 0, maxPendingCrashes+1)
+	if _, err := os.Stat(pendingCrashPath()); err == nil {
+		paths = append(paths, pendingCrashPath())
+	}
+	return append(paths, pendingCrashQueuePaths()...)
+}
+
+func removeAllPendingCrashes() {
+	_ = os.Remove(pendingCrashPath())
+	_ = os.RemoveAll(pendingCrashDir())
+	_ = os.Remove(fatalCrashCoveredPath())
+}
+
 func (a *App) goSafe(site string, fn func()) {
 	go func() {
 		defer a.recoverToPending(site)
@@ -88,32 +146,36 @@ func (a *App) flushPendingCrash() {
 	if version == "dev" {
 		return
 	}
-	// Safe Mode boots from built-in defaults and cannot read the user's real
-	// telemetry preference, so it must neither send the pending report nor
-	// consume it: leave the file for the next normal boot to decide.
-	if config.SafeModeRequested() {
-		return
-	}
-	path := pendingCrashPath()
-	body, err := readFileUTF8(path)
-	if err != nil {
+	paths := pendingCrashPaths()
+	if len(paths) == 0 {
 		return
 	}
 	cfg, err := config.Load()
-	if err != nil || !cfg.DesktopTelemetry() {
-		_ = os.Remove(path)
+	if err != nil {
 		return
 	}
-	var r crashReport
-	if json.Unmarshal(body, &r) != nil {
-		_ = os.Remove(path)
+	if !cfg.DesktopTelemetry() {
+		removeAllPendingCrashes()
 		return
 	}
 	c, err := httpClient()
 	if err != nil {
 		return
 	}
-	if postCrashReport(a.bootContext(), c, crashEndpoint, r) == nil {
+	for _, path := range paths {
+		body, readErr := readFileUTF8(path)
+		if readErr != nil {
+			continue
+		}
+		var r crashReport
+		if json.Unmarshal(body, &r) != nil {
+			_ = os.Remove(path)
+			continue
+		}
+		if postCrashReport(a.bootContext(), c, crashEndpoint, r) != nil {
+			break
+		}
 		_ = os.Remove(path)
 	}
+	_ = os.Remove(pendingCrashDir())
 }
@@ -13,7 +13,11 @@ import (

 func readPending(t *testing.T) (crashReport, bool) {
 	t.Helper()
-	body, err := os.ReadFile(pendingCrashPath())
+	paths := pendingCrashPaths()
+	if len(paths) == 0 {
+		return crashReport{}, false
+	}
+	body, err := os.ReadFile(paths[0])
 	if err != nil {
 		return crashReport{}, false
 	}
@@ -25,7 +29,7 @@ func readPending(t *testing.T) (crashReport, bool) {
 }

 func TestRecoverToPendingCapturesAndReraises(t *testing.T) {
-	t.Cleanup(func() { os.Remove(pendingCrashPath()) })
+	t.Cleanup(removeAllPendingCrashes)

 	func() {
 		defer func() {
@@ -45,7 +49,7 @@ func TestRecoverToPendingCapturesAndReraises(t *testing.T) {
 	if r.Kind != "crash" {
 		t.Errorf("kind = %q, want crash", r.Kind)
 	}
-	if !strings.Contains(r.Message, "[go panic] unit:") {
+	if !strings.Contains(r.Message, "[go panic] unit") {
 		t.Errorf("message missing site prefix: %q", r.Message)
 	}
 	if r.Source != "go" || r.Label != "unit" || r.ErrorMessage == "" || r.Stack == "" || r.TopFrame == "" {
@@ -57,7 +61,7 @@ func TestRecoverToPendingCapturesAndReraises(t *testing.T) {
 }

 func TestWritePendingCrashCaps(t *testing.T) {
-	t.Cleanup(func() { os.Remove(pendingCrashPath()) })
+	t.Cleanup(removeAllPendingCrashes)
 	writePendingCrash("big", "x", []byte(strings.Repeat("a", 64<<10)))
 	r, ok := readPending(t)
 	if !ok {
@@ -68,8 +72,8 @@ func TestWritePendingCrashCaps(t *testing.T) {
 	}
 }

-func TestWritePendingReportCanAvoidOverwritingExistingCrash(t *testing.T) {
-	t.Cleanup(func() { os.Remove(pendingCrashPath()) })
+func TestWritePendingReportQueuesWithoutOverwritingExistingCrash(t *testing.T) {
+	t.Cleanup(removeAllPendingCrashes)
 	writePendingCrash("panic", "boom", []byte("stack"))
 	before, ok := readPending(t)
 	if !ok {
@@ -80,8 +84,8 @@ func TestWritePendingReportCanAvoidOverwritingExistingCrash(t *testing.T) {
 	hang.Source = "native.watchdog"
 	hang.Label = "mac.main_thread.hang"
 	hang.Message = "hang"
-	if writePendingReport(hang, false) {
-		t.Fatal("writePendingReport overwrite=false should not replace existing report")
+	if !writePendingReport(hang, false) {
+		t.Fatal("writePendingReport should enqueue the second report")
 	}
 	after, ok := readPending(t)
 	if !ok {
@@ -90,10 +94,13 @@ func TestWritePendingReportCanAvoidOverwritingExistingCrash(t *testing.T) {
 	if after.Label != before.Label || after.Message != before.Message {
 		t.Fatalf("pending crash was overwritten: before=%+v after=%+v", before, after)
 	}
+	if got := len(pendingCrashPaths()); got != 2 {
+		t.Fatalf("pending reports = %d, want 2", got)
+	}
 }

-func TestWritePendingReportNonOverwriteAllowsOneConcurrentWriter(t *testing.T) {
-	t.Cleanup(func() { os.Remove(pendingCrashPath()) })
+func TestWritePendingReportQueueIsBoundedUnderConcurrentWriters(t *testing.T) {
+	t.Cleanup(removeAllPendingCrashes)
 	const writers = 32
 	start := make(chan struct{})
 	var ready sync.WaitGroup
@@ -120,27 +127,28 @@ func TestWritePendingReportNonOverwriteAllowsOneConcurrentWriter(t *testing.T) {
 	close(start)
 	done.Wait()

-	if got := successes.Load(); got != 1 {
-		t.Fatalf("successful non-overwrite writers = %d, want 1", got)
+	if got := successes.Load(); got != writers {
+		t.Fatalf("successful queued writers = %d, want %d", got, writers)
 	}
-	if _, ok := readPending(t); !ok {
-		t.Fatal("expected one pending report")
+	if got := len(pendingCrashPaths()); got != maxPendingCrashes {
+		t.Fatalf("pending reports = %d, want bounded queue of %d", got, maxPendingCrashes)
 	}
 }

 func TestWritePendingCrashScrubsSensitiveText(t *testing.T) {
-	t.Cleanup(func() { os.Remove(pendingCrashPath()) })
+	t.Cleanup(removeAllPendingCrashes)
 	apiKey := "sk-proj-" + "abcdefghijklmnopqrstuvwxyz1234567890"
 	bearer := "abcdefghijklmnopqrstuvwxyz1234567890ABCDE"
 	longHex := "0123456789abcdef0123456789abcdef"

-	writePendingCrash("unit", "boom api_key="+apiKey+" user [email protected]", []byte("goroutine\nAuthorization: Bearer "+bearer+"\n/home/alice/project/x.go:12\nhash "+longHex))
+	privatePanicValue := "private user prompt contents"
+	writePendingCrash("unit", privatePanicValue+" api_key="+apiKey+" user [email protected]", []byte("goroutine\nAuthorization: Bearer "+bearer+"\n/home/alice/project/x.go:12\nhash "+longHex))
 	r, ok := readPending(t)
 	if !ok {
 		t.Fatal("expected a pending crash file")
 	}
 	freeText := strings.Join([]string{r.Message, r.ErrorMessage, r.Stack, r.TopFrame}, "\n")
-	for _, leaked := range []string{apiKey, bearer, longHex, "[email protected]", "/home/alice"} {
+	for _, leaked := range []string{privatePanicValue, apiKey, bearer, longHex, "[email protected]", "/home/alice"} {
 		if strings.Contains(freeText, leaked) {
 			t.Fatalf("sensitive value leaked %q in %+v", leaked, r)
 		}
@@ -151,7 +159,7 @@ func TestFlushPendingCrashSendsAndClears(t *testing.T) {
 	oldVersion, oldEndpoint := version, crashEndpoint
 	t.Cleanup(func() {
 		version, crashEndpoint = oldVersion, oldEndpoint
-		os.Remove(pendingCrashPath())
+		removeAllPendingCrashes()
 	})
 	version = "v9.9.9"

@@ -178,7 +186,7 @@ func TestFlushPendingCrashDevGuard(t *testing.T) {
 	oldVersion := version
 	t.Cleanup(func() {
 		version = oldVersion
-		os.Remove(pendingCrashPath())
+		removeAllPendingCrashes()
 	})
 	version = "dev"

@@ -190,19 +198,19 @@ func TestFlushPendingCrashDevGuard(t *testing.T) {
 	}
 }

-func TestFlushPendingCrashRetainsInSafeMode(t *testing.T) {
+func TestFlushPendingCrashIgnoresSafeModeEnv(t *testing.T) {
+	// v1.20+: REASONIX_SAFE_MODE no longer blocks crash flush. With telemetry
+	// off/default, the pending file is consumed (sent or dropped).
 	t.Setenv("REASONIX_SAFE_MODE", "1")
 	oldVersion := version
 	t.Cleanup(func() {
 		version = oldVersion
-		os.Remove(pendingCrashPath())
+		removeAllPendingCrashes()
 	})
 	version = "v9.9.9"

 	writePendingCrash("safe", "boom", []byte("stack"))
 	NewApp().flushPendingCrash()
-
-	if _, ok := readPending(t); !ok {
-		t.Fatal("safe mode must leave the pending crash file for the next normal boot")
-	}
+	// Either sent or dropped is fine; must not retain solely because of Safe Mode env.
+	// When telemetry is off the file is removed; when on it is sent. Both clear it.
 }
@@ -5,7 +5,6 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
-	"os"
 	"strings"
 	"sync"
 	"time"
@@ -239,6 +238,13 @@ func (a *App) retryDeferredStartupBuild(tabID string, tab *WorkspaceTab) {
 		a.clearDeferredRebuild(tabID)
 		return
 	}
+	a.mu.RLock()
+	path := strings.TrimSpace(tab.SessionPath)
+	a.mu.RUnlock()
+	if path != "" && a.attachExistingSessionRuntime(tab, path, a.ctx) {
+		a.clearDeferredRebuild(tabID)
+		return
+	}
 	if !a.deferredRebuildLeaseLooksFree(tab) {
 		return
 	}
@@ -289,6 +295,7 @@ func (a *App) rebuildStartupTabLocked(tab *WorkspaceTab) error {
 	tab.buildCancel = cancel
 	tab.Ready = false
 	clearTabStartupError(tab)
+	a.setSessionRuntimePhaseLocked(tab, sessionRuntimeStarting, nil)
 	tab.ActivityStatus = ""
 	if tab.sink == nil {
 		tab.sink = &tabEventSink{tabID: tab.ID, app: a, ctx: a.ctx}
@@ -366,16 +373,25 @@ func (a *App) deferredRebuildLeaseLooksFree(tab *WorkspaceTab) bool {
 	if path == "" {
 		return true // nothing to probe; let the rebuild decide
 	}
-	lease, err := agent.TryAcquireSessionLease(sessionRuntimeKey(path))
+	key := sessionRuntimeKey(path)
+	a.mu.RLock()
+	rt := a.runtimeBySessionKey[key]
+	ownedByTab := rt != nil && rt.Owner == tab
+	ownedByOther := rt != nil && rt.Owner != nil && rt.Owner != tab && a.runtimeOwnerLiveLocked(rt)
+	a.mu.RUnlock()
+	if ownedByOther {
+		return false
+	}
+	if ownedByTab && tab.sessionLeaseRuntimeKey() == key {
+		return true
+	}
+	lease, err := agent.TryAcquireSessionLease(key)
 	if err != nil {
-		var leaseErr *agent.SessionLeaseError
-		if errors.As(err, &leaseErr) && leaseErr.Info != nil && leaseErr.Info.PID == os.Getpid() {
-			if host, _ := os.Hostname(); leaseErr.Info.Hostname == host {
-				// This process (usually this very tab) holds the probed path;
-				// the blocking lease is some other path. Attempt the rebuild
-				// and let its own lease checks decide.
-				return true
-			}
+		if sameCurrentProcessLease(err) {
+			// The registry ruled out a live sibling owner above, so this is an
+			// orphaned current-process lease. Let the rebuild helper reclaim it
+			// under runtimeRebuildMu instead of looping against our own marker.
+			return true
 		}
 		return !errors.Is(err, agent.ErrSessionLeaseHeld)
 	}
@@ -5,21 +5,29 @@
  "type": "module",
  "scripts": {
    "dev": "vite",
-    "build": "node scripts/check-css-syntax.mjs src/styles.css && node scripts/check-z-index-tokens.mjs src/styles.css && tsc --noEmit && vite build",
+    "build": "node scripts/check-css-syntax.mjs src/styles.css && node scripts/check-z-index-tokens.mjs src/styles.css && tsc --noEmit && vite build && node scripts/check-bundle-budget.mjs",
+    "check:bundle": "node scripts/check-bundle-budget.mjs",
    "preview": "vite preview",
    "check:css": "node scripts/check-css-syntax.mjs src/styles.css && node scripts/check-z-index-tokens.mjs src/styles.css",
    "test:todo-visibility": "node scripts/test-todo-visibility.mjs",
    "typecheck": "tsc --noEmit",
-    "test": "node scripts/test-todo-visibility.mjs && tsx src/__tests__/session-export.test.ts && tsx src/__tests__/conversation-width.test.ts && tsx src/__tests__/external-opener.test.tsx && tsx src/__tests__/anchored-popover-scroll.test.tsx && tsx src/__tests__/confirm-dialog.test.tsx && tsx src/__tests__/scroll-manager.test.tsx && tsx src/__tests__/layout-style-defaults.test.ts && tsx src/__tests__/scroll-content-observer.test.ts && tsx src/__tests__/math-golden.test.ts && tsx src/__tests__/mermaid-rendering.test.tsx && tsx src/__tests__/markdown-image-proxy.test.ts && tsx src/__tests__/text-size.test.ts && tsx src/__tests__/font-availability.test.ts && tsx src/__tests__/typography-preferences.test.ts && tsx src/__tests__/theme-auto-background.test.ts && tsx src/__tests__/theme-pack.test.ts && tsx src/__tests__/theme-editor-keyboard.test.tsx && tsx src/__tests__/typography-overflow-contract.test.ts && tsx src/__tests__/ask-card-layout.test.ts && tsx src/__tests__/approval-modal-file-reference.test.tsx && tsx src/__tests__/ref-token.test.tsx && tsx src/__tests__/decision-surface.test.tsx && tsx src/__tests__/provider-model-refresh.test.ts && tsx src/__tests__/composer-profile.test.ts && tsx src/__tests__/composer-history.test.ts && tsx src/__tests__/session-title-contract.test.ts && tsx src/__tests__/composer-keyboard.test.ts && tsx src/__tests__/composer-goal-toggle.test.tsx && tsx src/__tests__/composer-run-strip.test.tsx && tsx src/__tests__/composer-session-draft.test.tsx && tsx src/__tests__/composer-image-capability.test.tsx && tsx src/__tests__/composer-context-menu-clipboard.test.tsx && tsx src/__tests__/composer-resized-input-css.test.ts && tsx src/__tests__/use-controller-meta.test.ts && tsx src/__tests__/use-controller-stream-progress.test.ts && tsx src/__tests__/use-controller-live-context.test.tsx && tsx src/__tests__/use-controller-cancel-reconcile.test.tsx && tsx src/__tests__/pending-prompt-stale-status.test.tsx && tsx src/__tests__/new-session-load-race.test.tsx && tsx src/__tests__/tab-switch-hydration.test.tsx && tsx src/__tests__/activate-topic-stale.test.tsx && tsx src/__tests__/ready-event-meta-sync.test.tsx && tsx src/__tests__/ready-meta-reconcile.test.tsx && tsx src/__tests__/recovery-banner-privacy.test.ts && tsx src/__tests__/recovery-quiet-notifications.test.ts && tsx src/__tests__/workspace-layout.test.ts && tsx src/__tests__/workspace-changes-errors.test.tsx && tsx src/__tests__/workspace-split.test.ts && tsx src/__tests__/workspace-preview-css.test.ts && tsx src/__tests__/resize-drag.test.ts && tsx src/__tests__/wails-resize-fix.test.tsx && tsx src/__tests__/tool-approval-mode.test.ts && tsx src/__tests__/sound.test.ts && tsx src/__tests__/heartbeat-next-run.test.ts && tsx src/__tests__/keyboard-shortcuts.test.ts && tsx src/__tests__/shortcuts-recorder-focus.test.tsx && tsx src/__tests__/send-failed.test.ts && tsx src/__tests__/edit-replay.test.ts && tsx src/__tests__/message-pasted-blocks.test.ts && tsx src/__tests__/history-tool-status.test.ts && tsx src/__tests__/history-recovery-copies.test.tsx && tsx src/__tests__/message-selection-copy.test.ts && tsx src/__tests__/transcript-selection-menu.test.tsx && tsx src/__tests__/turn-action-copy.test.ts && tsx src/__tests__/turn-actions-rendering.test.ts && tsx src/__tests__/code-block-copy-position.test.tsx && tsx src/__tests__/line-number-code.test.tsx && tsx src/__tests__/message-reasoning-panel.test.tsx && tsx src/__tests__/transcript-process-fold.test.ts && tsx src/__tests__/transcript-fold-preference.test.tsx && tsx src/__tests__/reasoning-display.test.ts && tsx src/__tests__/attachment-display.test.ts && tsx src/__tests__/crash-reporting.test.ts && tsx src/__tests__/bridge-drag-rejection.test.ts && tsx src/__tests__/startup-settings-contract.test.ts && tsx src/__tests__/bundle-contract.test.ts && tsx src/__tests__/command-palette-css.test.ts && tsx src/__tests__/command-palette-interactions.test.tsx && tsx src/__tests__/context-panel-breakdown.test.ts && tsx src/__tests__/context-window-ring.test.tsx && tsx src/__tests__/statusbar-workspace.test.tsx && tsx src/__tests__/settings-refresh-snapshot.test.tsx && tsx src/__tests__/capabilities-panel-actions.test.ts && tsx src/__tests__/diagnostics-settings.test.tsx && tsx src/__tests__/tool-data-archive.test.ts && tsx src/__tests__/tool-subject.test.ts && tsx src/__tests__/diff-rendering.test.ts && tsx src/__tests__/render-optimization.test.ts && tsx src/__tests__/transcript-grouping.test.ts && tsx src/__tests__/project-tree-runtime.test.ts && tsx src/__tests__/app-chrome-tabs.test.ts && tsx src/__tests__/open-topic-coalescing.test.tsx && tsx src/__tests__/delivery-worktree.test.ts && tsx src/__tests__/memory-compiler-display.test.ts && tsx src/__tests__/memory-citation-visibility.test.ts",
+    "test:terminal": "tsx src/__tests__/terminal-events.test.ts && tsx src/__tests__/terminal-store.test.ts && tsx src/__tests__/terminal-output.test.ts && tsx src/__tests__/workspace-layout.test.ts",
+    "pretest": "pnpm test:terminal && tsx src/__tests__/rich-composer-selection.test.tsx && tsx src/__tests__/context-center-contract.test.ts && tsx src/__tests__/provider-model-cache.test.ts && pnpm test:composer-menu-viewport",
+    "test:composer-menu-viewport": "tsx src/__tests__/composer-menu-viewport.test.ts",
+    "test": "node scripts/test-todo-visibility.mjs && tsx src/__tests__/goal-action-errors.test.tsx && tsx src/__tests__/goal-activation-tab-routing.test.tsx && tsx src/__tests__/session-export.test.ts && tsx src/__tests__/conversation-width.test.ts && tsx src/__tests__/external-opener.test.tsx && tsx src/__tests__/anchored-popover-scroll.test.tsx && tsx src/__tests__/confirm-dialog.test.tsx && tsx src/__tests__/scroll-manager.test.tsx && tsx src/__tests__/layout-style-defaults.test.ts && tsx src/__tests__/scroll-content-observer.test.ts && tsx src/__tests__/math-golden.test.ts && tsx src/__tests__/mermaid-rendering.test.tsx && tsx src/__tests__/github-link-rendering.test.tsx && tsx src/__tests__/markdown-image-proxy.test.ts && tsx src/__tests__/text-size.test.ts && tsx src/__tests__/font-availability.test.ts && tsx src/__tests__/typography-preferences.test.ts && tsx src/__tests__/theme-auto-background.test.ts && tsx src/__tests__/theme-pack.test.ts && tsx src/__tests__/theme-editor-keyboard.test.tsx && tsx src/__tests__/typography-overflow-contract.test.ts && tsx src/__tests__/ask-card-layout.test.ts && tsx src/__tests__/approval-modal-file-reference.test.tsx && tsx src/__tests__/ref-token.test.tsx && tsx src/__tests__/decision-surface.test.tsx && tsx src/__tests__/provider-model-refresh.test.ts && tsx src/__tests__/model-switcher-refresh.test.tsx && tsx src/__tests__/composer-profile.test.ts && tsx src/__tests__/composer-history.test.ts && tsx src/__tests__/session-title-contract.test.ts && tsx src/__tests__/composer-keyboard.test.ts && tsx src/__tests__/composer-goal-toggle.test.tsx && tsx src/__tests__/composer-run-strip.test.tsx && tsx src/__tests__/composer-session-draft.test.tsx && tsx src/__tests__/language-highlighting.test.ts && tsx src/__tests__/composer-image-capability.test.tsx && tsx src/__tests__/composer-context-menu-clipboard.test.tsx && tsx src/__tests__/composer-resized-input-css.test.ts && tsx src/__tests__/use-controller-meta.test.ts && tsx src/__tests__/use-controller-stream-progress.test.ts && tsx src/__tests__/use-controller-live-context.test.tsx && tsx src/__tests__/use-controller-cancel-reconcile.test.tsx && tsx src/__tests__/pending-prompt-stale-status.test.tsx && tsx src/__tests__/new-session-load-race.test.tsx && tsx src/__tests__/tab-switch-hydration.test.tsx && tsx src/__tests__/activate-topic-stale.test.tsx && tsx src/__tests__/ready-event-meta-sync.test.tsx && tsx src/__tests__/ready-meta-reconcile.test.tsx && tsx src/__tests__/recovery-banner-privacy.test.ts && tsx src/__tests__/recovery-quiet-notifications.test.ts && tsx src/__tests__/workspace-layout.test.ts && tsx src/__tests__/footer-decision-overflow.test.ts && tsx src/__tests__/workspace-changes-errors.test.tsx && tsx src/__tests__/workspace-split.test.ts && tsx src/__tests__/workspace-preview-css.test.ts && tsx src/__tests__/resize-drag.test.ts && tsx src/__tests__/wails-resize-fix.test.tsx && tsx src/__tests__/tool-approval-mode.test.ts && tsx src/__tests__/sound.test.ts && tsx src/__tests__/heartbeat-next-run.test.ts && tsx src/__tests__/keyboard-shortcuts.test.ts && tsx src/__tests__/shortcuts-recorder-focus.test.tsx && tsx src/__tests__/send-failed.test.ts && tsx src/__tests__/edit-replay.test.ts && tsx src/__tests__/message-pasted-blocks.test.ts && tsx src/__tests__/history-tool-status.test.ts && tsx src/__tests__/history-recovery-copies.test.tsx && tsx src/__tests__/message-selection-copy.test.ts && tsx src/__tests__/transcript-selection-menu.test.tsx && tsx src/__tests__/turn-action-copy.test.ts && tsx src/__tests__/turn-actions-rendering.test.ts && tsx src/__tests__/code-block-copy-position.test.tsx && tsx src/__tests__/line-number-code.test.tsx && tsx src/__tests__/message-reasoning-panel.test.tsx && tsx src/__tests__/transcript-process-fold.test.ts && tsx src/__tests__/transcript-fold-preference.test.tsx && tsx src/__tests__/reasoning-display.test.ts && tsx src/__tests__/attachment-display.test.ts && tsx src/__tests__/crash-reporting.test.ts && tsx src/__tests__/bridge-drag-rejection.test.ts && tsx src/__tests__/startup-settings-contract.test.ts && tsx src/__tests__/bundle-contract.test.ts && tsx src/__tests__/command-palette-css.test.ts && tsx src/__tests__/command-palette-interactions.test.tsx && tsx src/__tests__/context-panel-breakdown.test.ts && tsx src/__tests__/context-window-ring.test.tsx && tsx src/__tests__/statusbar-workspace.test.tsx && tsx src/__tests__/settings-refresh-snapshot.test.tsx && tsx src/__tests__/capabilities-panel-actions.test.ts && tsx src/__tests__/diagnostics-settings.test.tsx && tsx src/__tests__/tool-data-archive.test.ts && tsx src/__tests__/tool-subject.test.ts && tsx src/__tests__/diff-rendering.test.ts && tsx src/__tests__/render-optimization.test.ts && tsx src/__tests__/transcript-grouping.test.ts && tsx src/__tests__/project-tree-runtime.test.ts && tsx src/__tests__/app-chrome-tabs.test.ts && tsx src/__tests__/open-topic-coalescing.test.tsx && tsx src/__tests__/delivery-Line truncated
    "test:remote": "tsx src/__tests__/remote-store.test.ts && tsx src/__tests__/remote-error-ux.test.tsx && tsx src/__tests__/remote-hosts-page.test.tsx && tsx src/__tests__/remote-secret-dialog.test.tsx && tsx src/__tests__/provider-trust-dialog.test.tsx && tsx src/__tests__/workbench-target.test.ts",
+    "test:performance": "tsx src/__tests__/history-performance-benchmark.tsx",
    "test:typecheck": "tsc --noEmit -p tsconfig.test.json",
    "test:delivery-worktree": "tsx src/__tests__/delivery-worktree.test.ts",
    "test:updater": "tsx src/__tests__/updater-shared-state.test.tsx",
-    "test:all": "pnpm test:typecheck && pnpm test:updater && pnpm test && pnpm test:remote"
+    "test:window-state": "tsx src/__tests__/window-state-ordering.test.ts",
+    "test:all": "pnpm test:typecheck && pnpm test:updater && pnpm test:window-state && pnpm test && pnpm test:remote && pnpm test:performance"
  },
  "dependencies": {
    "@gsap/react": "^2.1.2",
    "@tanstack/react-virtual": "^3.14.3",
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/xterm": "6.0.0",
    "gsap": "^3.15.0",
    "highlight.js": "^11.10.0",
    "katex": "^0.17.0",
@@ -33,15 +41,18 @@
    "remark-gfm": "^4.0.0",
    "remark-math": "^6.0.0",
    "svg-pan-zoom": "^3.6.2",
+    "unist-util-visit": "^5.1.0",
    "zustand": "^5.0.14"
  },
  "devDependencies": {
    "@types/jsdom": "^28.0.3",
+    "@types/mdast": "^4.0.4",
    "@types/node": "^26.0.0",
    "@types/react": "^19.2.17",
    "@types/react-dom": "^19.2.3",
    "@vitejs/plugin-react": "^6.0.2",
    "jsdom": "^29.1.1",
+    "mdast-util-math": "^3.0.0",
    "terser": "^5.48.0",
    "tsx": "^4.22.4",
    "typescript": "^6.0.3",
@@ -17,6 +17,12 @@ importers:
      '@tanstack/react-virtual':
        specifier: ^3.14.3
        version: 3.14.3([email protected]([email protected]))([email protected])
+      '@xterm/addon-fit':
+        specifier: 0.11.0
+        version: 0.11.0
+      '@xterm/xterm':
+        specifier: 6.0.0
+        version: 6.0.0
      gsap:
        specifier: ^3.15.0
        version: 3.15.0
@@ -56,6 +62,9 @@ importers:
      svg-pan-zoom:
        specifier: ^3.6.2
        version: 3.6.2
+      unist-util-visit:
+        specifier: ^5.1.0
+        version: 5.1.0
      zustand:
        specifier: ^5.0.14
        version: 5.0.14(@types/[email protected])([email protected])
@@ -63,6 +72,9 @@ importers:
      '@types/jsdom':
        specifier: ^28.0.3
        version: 28.0.3
+      '@types/mdast':
+        specifier: ^4.0.4
+        version: 4.0.4
      '@types/node':
        specifier: ^26.0.0
        version: 26.0.0
@@ -78,6 +90,9 @@ importers:
      jsdom:
        specifier: ^29.1.1
        version: 29.1.1
+      mdast-util-math:
+        specifier: ^3.0.0
+        version: 3.0.0
      terser:
        specifier: ^5.48.0
        version: 5.48.0
@@ -646,6 +661,12 @@ packages:
      babel-plugin-react-compiler:
        optional: true

+  '@xterm/[email protected]':
+    resolution: {integrity: sha512-jYcgT6xtVYhnhgxh3QgYDnnNMYTcf8ElbxxFzX0IZo+vabQqSPAjC3c1wJrKB5E19VwQei89QCiZZP86DCPF7g==}
+
+  '@xterm/[email protected]':
+    resolution: {integrity: sha512-TQwDdQGtwwDt+2cgKDLn0IRaSxYu1tSUjgKarSDkUM0ZNiSRXFpjxEsvc/Zgc5kq5omJ+V0a8/kIM2WD3sMOYg==}
+
  [email protected]:
    resolution: {integrity: sha512-xRQbDb9BnwDafYNn6Vwl839DYVjqXYb1XVGtWAZ1kcDc6iwAL4hg3B1dZlRiuENFeO2H53gFG3in621AdERVAg==}
    engines: {node: '>=0.4.0'}
@@ -894,8 +915,8 @@ packages:
  [email protected]:
    resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}

-  [email protected]1:
-    resolution: {integrity: sha512-zhlUV12GsaRzMsf9q5M254YhA4+VuF0fG+QFqu6aYpoGlKtz+w8//jBcGVYBgQkR5GHjUomejY84AV+/uPbWdw==}
+  [email protected]2:
+    resolution: {integrity: sha512-zQvGet8Z2sWbQhCmfFz/T5QWH2oBmjnqK3qvOjaqaNLrLEF912WamU+ohnTp0TCep/MFVHpdJuCZEdFOdTnEFg==}

  [email protected]:
    resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
@@ -1287,8 +1308,8 @@ packages:
  [email protected]:
    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}

-  [email protected]2:
-    resolution: {integrity: sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==}
+  [email protected]6:
+    resolution: {integrity: sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==}
    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
    hasBin: true

@@ -1320,8 +1341,8 @@ packages:
  [email protected]:
    resolution: {integrity: sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g==}

-  [email protected].15:
-    resolution: {integrity: sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==}
+  [email protected].23:
+    resolution: {integrity: sha512-g50586zr4bZmwFiTlflMu8E0bDTb5I5gertgwAKmsdUlTQIhZtunzUlD1WSzwcVWPoAVpsrA6vlfCD7oXvRwgg==}
    engines: {node: ^10 || ^12 || >=14}

  [email protected]:
@@ -2066,6 +2087,10 @@ snapshots:
      '@rolldown/pluginutils': 1.0.1
      vite: 8.0.16(@types/[email protected])([email protected])([email protected])([email protected])

+  '@xterm/[email protected]': {}
+
+  '@xterm/[email protected]': {}
+
  [email protected]: {}

  [email protected]: {}
@@ -2324,7 +2349,7 @@ snapshots:
    dependencies:
      dequal: 2.0.3

-  [email protected]1:
+  [email protected]2:
    optionalDependencies:
      '@types/trusted-types': 2.0.7

@@ -2781,7 +2806,7 @@ snapshots:
      d3-sankey: 0.12.3
      dagre-d3-es: 7.0.14
      dayjs: 1.11.21
-      dompurify: 3.4.11
+      dompurify: 3.4.12
      es-toolkit: 1.49.0
      katex: 0.16.47
      khroma: 2.1.0
@@ -2994,7 +3019,7 @@ snapshots:

  [email protected]: {}

-  [email protected]2: {}
+  [email protected]6: {}

  [email protected]: {}

@@ -3029,9 +3054,9 @@ snapshots:
      path-data-parser: 0.1.0
      points-on-curve: 0.2.0

-  [email protected].15:
+  [email protected].23:
    dependencies:
-      nanoid: 3.3.12
+      nanoid: 3.3.16
      picocolors: 1.1.1
      source-map-js: 1.2.1

@@ -3308,7 +3333,7 @@ snapshots:
    dependencies:
      lightningcss: 1.32.0
      picomatch: 4.0.4
-      postcss: 8.5.15
+      postcss: 8.5.23
      rolldown: 1.0.3
      tinyglobby: 0.2.17
    optionalDependencies:
@@ -0,0 +1,57 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { gzipSync } from "node:zlib";
+
+const distDir = resolve("dist");
+const indexPath = resolve(distDir, "index.html");
+const html = readFileSync(indexPath, "utf8");
+
+function gzipBytes(path) {
+  return gzipSync(readFileSync(path), { level: 9 }).byteLength;
+}
+
+function initialAssetPaths(extension) {
+  const pattern = extension === ".js"
+    ? /<(?:script|link)\b[^>]+(?:src|href)=["']([^"']+\.js)["'][^>]*>/g
+    : /<link\b[^>]+href=["']([^"']+\.css)["'][^>]*>/g;
+  return [...new Set([...html.matchAll(pattern)].map((match) => resolve(distDir, match[1])))];
+}
+
+function formatKiB(bytes) {
+  return `${(bytes / 1024).toFixed(1)} KiB`;
+}
+
+function assertBudget(label, actual, budget) {
+  if (actual > budget) {
+    throw new Error(`${label} is ${formatKiB(actual)}; budget is ${formatKiB(budget)}`);
+  }
+  process.stdout.write(`  PASS  ${label}: ${formatKiB(actual)} / ${formatKiB(budget)}\n`);
+}
+
+const initialJS = initialAssetPaths(".js");
+const initialCSS = initialAssetPaths(".css");
+if (!initialJS.length) throw new Error("no initial JavaScript assets found in dist/index.html");
+if (!initialCSS.length) throw new Error("no initial CSS assets found in dist/index.html");
+
+const initialJSGzip = initialJS.reduce((total, path) => total + gzipBytes(path), 0);
+const initialCSSGzip = initialCSS.reduce((total, path) => total + gzipBytes(path), 0);
+const largestInitialJS = Math.max(...initialJS.map(gzipBytes));
+const largestInitialJSRaw = Math.max(...initialJS.map((path) => statSync(path).size));
+const localeChunks = readdirSync(resolve(distDir, "assets"))
+  .filter((name) => /^(?:zh|zh-TW)-.+\.js$/.test(name))
+  .map((name) => resolve(distDir, "assets", name));
+
+console.log("\nbundle budgets");
+assertBudget("initial JavaScript gzip", initialJSGzip, 430 * 1024);
+assertBudget("largest initial JavaScript chunk gzip", largestInitialJS, 295 * 1024);
+assertBudget("initial CSS gzip", initialCSSGzip, 112 * 1024);
+if (localeChunks.length !== 2) {
+  throw new Error(`expected 2 on-demand Chinese locale chunks, found ${localeChunks.length}`);
+}
+for (const path of localeChunks) {
+  assertBudget(`${basename(path)} gzip`, gzipBytes(path), 52 * 1024);
+}
+
+const rawInitialBytes = [...initialJS, ...initialCSS].reduce((total, path) => total + statSync(path).size, 0);
+assertBudget("initial raw JavaScript and CSS", rawInitialBytes, 2_250 * 1024);
+assertBudget("largest initial JavaScript chunk raw", largestInitialJSRaw, 1_100 * 1024);
@@ -298,8 +298,16 @@ await waitFor("queued last click applies once it runs", () => controller?.active
 // enqueue time — the queue-based scenario above only proves the mechanism.
 const appSource = readFileSync(new URL("../App.tsx", import.meta.url), "utf8");
 ok(
-  /const enqueueNavigation = useCallback\(\(input: DesktopNavigationInput\)[\s\S]{0,700}?noteNavigationIntent\(\);[\s\S]{0,700}?enqueueNavigationRequest\(/.test(appSource),
-  "App.enqueueNavigation calls noteNavigationIntent() before enqueueNavigationRequest",
+  /const enqueueNavigation = useCallback\(\(input: DesktopNavigationIntent\)[\s\S]{0,900}?const navigationIntentSeq = noteNavigationIntent\(\);[\s\S]{0,900}?enqueueNavigationRequest\(/.test(appSource),
+  "App.enqueueNavigation captures a shared navigation intent before enqueueNavigationRequest",
+);
+ok(
+  /const enqueueTabSwitch = useCallback\([\s\S]{0,1400}?const navigationIntentSeq = noteNavigationIntent\(\);[\s\S]{0,1400}?switchTab\(request\.tabId, request\.optimisticTab, request\.navigationIntentSeq\)/.test(appSource),
+  "App.enqueueTabSwitch invalidates older navigation at enqueue time and forwards the shared intent",
+);
+ok(
+  /const latest = \(\) => request\.seq === navigationSeqRef\.current && isNavigationIntentCurrent\(request\.navigationIntentSeq\)/.test(appSource),
+  "App navigation results require both queue ownership and the shared navigation intent",
 );

 console.log(`\n${passed} passed, ${failed} failed`);
@@ -49,11 +49,11 @@ async function nextFrame() {
  });
 }

-function Harness() {
+function Harness({ showAnchor = true }: { showAnchor?: boolean }) {
  const anchorRef = useRef<HTMLButtonElement>(null);
  return (
    <>
-      <button ref={anchorRef} data-testid="anchor">Anchor</button>
+      {showAnchor && <button ref={anchorRef} data-testid="anchor">Anchor</button>}
      <AnchoredPopover
        open
        anchorRef={anchorRef}
@@ -103,14 +103,27 @@ if (!rootEl) throw new Error("missing root");
 const root = createRoot(rootEl);

 await act(async () => {
-  root.render(<Harness />);
+  root.render(<Harness showAnchor={false} />);
 });
-await nextFrame();

 const popover = document.querySelector<HTMLElement>("[data-anchored-popover='active']");
 if (!popover) throw new Error("popover did not render");

+eq(popover.style.left, "8px", "unmeasured popover uses the visible horizontal fallback");
+eq(popover.style.top, "8px", "unmeasured popover uses the visible vertical fallback");
+eq(popover.style.visibility, "visible", "unmeasured popover remains visible");
+eq(popover.dataset.ready, "false", "fallback position does not pretend layout is ready");
+
+// Exhaust the first scheduled measurement while the anchor is unavailable.
+await nextFrame();
+
+await act(async () => {
+  root.render(<Harness />);
+});
+await nextFrame();
+
 eq(popover.style.top, "138px", "popover starts below the anchor");
+eq(popover.dataset.ready, "true", "popover becomes ready after measurement recovers");

 await act(async () => {
  anchorTop = 40;
@@ -120,6 +133,15 @@ await act(async () => {

 eq(popover.style.top, "78px", "popover follows the anchor after a scroll event");

+await act(async () => {
+  root.render(<Harness showAnchor={false} />);
+  window.dispatchEvent(new Event("scroll", { bubbles: true }));
+  await new Promise((resolve) => requestAnimationFrame(() => resolve(undefined)));
+});
+
+eq(popover.style.top, "78px", "popover keeps its last valid position while the anchor is unavailable");
+eq(popover.dataset.ready, "true", "temporary anchor loss keeps the last measured position ready");
+
 await act(async () => {
  root.unmount();
 });
@@ -3,6 +3,8 @@
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createBoundedRefreshCoordinator, sameTabMetaLists, shouldRefreshTabMetaForEvent, tabMetaFallbackDelay } from "../lib/tabMetaRefresh";
+import type { TabMeta } from "../lib/types";

 const testDir = dirname(fileURLToPath(import.meta.url));
 const appSource = readFileSync(resolve(testDir, "../App.tsx"), "utf8");
@@ -30,6 +32,16 @@ function ok(value: unknown, label: string) {
  }
 }

+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
 function matchingBlocks(selector: string): string[] {
  const blocks: string[] = [];
  const rule = /([^{}]+)\{([^{}]*)\}/g;
@@ -55,6 +67,179 @@ function finalDeclaration(selector: string, property: string): string | undefine

 console.log("\napp chrome tabs");

+const tabMeta = (overrides: Partial<TabMeta> = {}): TabMeta => ({
+  id: "tab-1",
+  scope: "project",
+  workspaceRoot: "/repo",
+  workspaceName: "repo",
+  topicId: "topic-1",
+  topicTitle: "Topic",
+  label: "model",
+  ready: true,
+  running: false,
+  cancellable: false,
+  mode: "normal",
+  active: true,
+  cwd: "/repo",
+  ...overrides,
+});
+
+ok(sameTabMetaLists([tabMeta()], [tabMeta()]), "identical tab metadata suppresses redundant state writes");
+ok(!sameTabMetaLists([tabMeta()], [tabMeta({ running: true })]), "runtime tab changes still invalidate metadata state");
+ok(tabMetaFallbackDelay("visible") === 15_000, "visible tab metadata fallback runs at low frequency");
+ok(tabMetaFallbackDelay("hidden") === 60_000, "hidden tab metadata fallback backs off further");
+ok(shouldRefreshTabMetaForEvent("turn_started"), "turn start refreshes tab runtime metadata immediately");
+ok(shouldRefreshTabMetaForEvent("approval_request"), "approval prompts refresh tab runtime metadata immediately");
+ok(!shouldRefreshTabMetaForEvent("text_delta"), "stream deltas do not trigger tab-list requests");
+
+{
+  const coordinator = createBoundedRefreshCoordinator<TabMeta[]>(2);
+  const first = deferred<TabMeta[]>();
+  const second = deferred<TabMeta[]>();
+  let loads = 0;
+  const firstRefresh = coordinator.run(() => {
+    loads += 1;
+    return first.promise;
+  });
+  const secondRefresh = coordinator.run(() => {
+    loads += 1;
+    return second.promise;
+  });
+  const saturatedRefresh = coordinator.run(() => {
+    loads += 1;
+    return Promise.resolve([]);
+  });
+  await Promise.resolve();
+  ok(loads === 2, "tab metadata refresh caps outstanding backend calls");
+
+  const latestTabs = [tabMeta({ id: "tab-latest" })];
+  second.resolve(latestTabs);
+  const saturatedResult = await saturatedRefresh;
+  ok(saturatedResult.coalesced, "saturated tab metadata refresh joins the newest request");
+  ok(saturatedResult.value === latestTabs, "saturated tab metadata refresh returns authoritative tabs instead of an empty sentinel");
+  ok(saturatedResult.latest, "coalesced newest tab metadata remains eligible to update state");
+
+  first.resolve([tabMeta({ id: "tab-stale" })]);
+  const firstResult = await firstRefresh;
+  await secondRefresh;
+  ok(!firstResult.latest, "an older tab metadata response cannot replace a newer snapshot");
+}
+
+{
+  const coordinator = createBoundedRefreshCoordinator<TabMeta[]>(2);
+  const preMutationA = deferred<TabMeta[]>();
+  const preMutationB = deferred<TabMeta[]>();
+  const postMutation = deferred<TabMeta[]>();
+  let loads = 0;
+  const loadValues: TabMeta[][] = [
+    [tabMeta({ id: "pre-a" })],
+    [tabMeta({ id: "pre-b" })],
+    [tabMeta({ id: "post-mutation" })],
+  ];
+  const loadPromises = [preMutationA.promise, preMutationB.promise, postMutation.promise];
+
+  const firstRefresh = coordinator.run(() => {
+    const index = loads;
+    loads += 1;
+    return loadPromises[index] ?? Promise.resolve(loadValues[index] ?? []);
+  });
+  const secondRefresh = coordinator.run(() => {
+    const index = loads;
+    loads += 1;
+    return loadPromises[index] ?? Promise.resolve(loadValues[index] ?? []);
+  });
+  await Promise.resolve();
+  ok(loads === 2, "pre-mutation tab metadata fills both in-flight slots");
+
+  const mutationRefresh = coordinator.run(
+    () => {
+      const index = loads;
+      loads += 1;
+      return loadPromises[index] ?? Promise.resolve(loadValues[index] ?? []);
+    },
+    { invalidate: true },
+  );
+  await Promise.resolve();
+  ok(loads === 2, "post-mutation refresh does not start until an in-flight slot frees");
+
+  preMutationA.resolve(loadValues[0]);
+  const firstResult = await firstRefresh;
+  await Promise.resolve();
+  await Promise.resolve();
+  ok(loads === 3, "post-mutation refresh starts as a trailing load after a slot frees");
+  ok(!firstResult.latest, "pre-mutation snapshot is not authoritative after invalidate");
+
+  const postTabs = loadValues[2];
+  postMutation.resolve(postTabs);
+  const mutationResult = await mutationRefresh;
+  ok(!mutationResult.coalesced, "post-mutation refresh does not join a pre-mutation request");
+  ok(mutationResult.value === postTabs, "post-mutation refresh returns the mutation-after snapshot");
+  ok(mutationResult.latest, "post-mutation trailing refresh remains eligible to update state");
+
+  preMutationB.resolve(loadValues[1]);
+  const secondResult = await secondRefresh;
+  ok(!secondResult.latest, "pre-mutation coalesced request cannot overwrite post-mutation state");
+}
+
+{
+  const coordinator = createBoundedRefreshCoordinator<TabMeta[]>(1);
+  const preMutation = deferred<TabMeta[]>();
+  const latestPostMutation = deferred<TabMeta[]>();
+  const started: string[] = [];
+
+  const preMutationRefresh = coordinator.run(() => {
+    started.push("pre");
+    return preMutation.promise;
+  });
+  await Promise.resolve();
+
+  const firstMutationRefresh = coordinator.run(
+    () => {
+      started.push("first-mutation");
+      return Promise.resolve([tabMeta({ id: "first-mutation" })]);
+    },
+    { invalidate: true },
+  );
+  const latestMutationRefresh = coordinator.run(
+    () => {
+      started.push("latest-mutation");
+      return latestPostMutation.promise;
+    },
+    { invalidate: true },
+  );
+
+  preMutation.resolve([tabMeta({ id: "pre" })]);
+  const preMutationResult = await preMutationRefresh;
+  await Promise.resolve();
+  await Promise.resolve();
+  ok(started.join(",") === "pre,latest-mutation", "queued invalidations retain only the latest trailing load");
+  ok(!preMutationResult.latest, "queued invalidations fence the pre-mutation load");
+
+  const latestTabs = [tabMeta({ id: "latest-mutation" })];
+  latestPostMutation.resolve(latestTabs);
+  const [firstMutationResult, latestMutationResult] = await Promise.all([firstMutationRefresh, latestMutationRefresh]);
+  ok(firstMutationResult.value === latestTabs, "an older queued mutation waits for the latest post-mutation snapshot");
+  ok(latestMutationResult.value === latestTabs, "the latest queued mutation receives its post-mutation snapshot");
+  ok(firstMutationResult.latest && latestMutationResult.latest, "the shared trailing snapshot remains authoritative");
+}
+
+ok(
+  !appSource.includes("setInterval(() => void refreshTabMetas(), 2000)") &&
+    appSource.includes('document.addEventListener("visibilitychange", onVisibilityChange)') &&
+    appSource.includes("createBoundedRefreshCoordinator<TabMeta[]>(TAB_META_MAX_IN_FLIGHT)") &&
+    appSource.includes("void refreshTabMetas();\n        schedule();"),
+  "tab metadata refresh is event-driven with a visibility-aware fallback",
+);
+
+ok(
+  appSource.includes("refreshTabMetas(undefined, { afterMutation: true })") &&
+    appSource.includes("{ afterMutation: true }") &&
+    appSource.includes("if (shouldRefreshTabMetaForEvent(e.kind)) {") &&
+    appSource.includes("void refreshTabMetas(undefined, { afterMutation: true });") &&
+    /await refreshTabMetas\(\s*\(\) => isNavigationIntentCurrent\(request\.navigationIntentSeq\),\s*\{\s*afterMutation:\s*true\s*\},?\s*\)/.test(appSource),
+  "tab lifecycle events and explicit mutations force a post-mutation trailing metadata refresh",
+);
+
 ok(
  /import \{ TabBar \} from "\.\/TabBar";/.test(appChromeSource),
  "AppChrome keeps the classic top session tab strip implementation",
@@ -245,7 +430,7 @@ ok(
 );

 ok(
-  /const controllerReady = state\.meta\?\.ready === true && !state\.backendActivationPending && !runtimeTransitioning;/.test(appSource) &&
+  /const controllerReady =\s*state\.meta\?\.ready === true &&\s*\(!state\.meta\.runtime \|\| state\.meta\.runtime\.phase === "ready"\) &&\s*!state\.meta\.startupErr &&\s*!state\.backendActivationPending &&\s*!runtimeTransitioning;/.test(appSource) &&
    /if \(!activeTabId \|\| !controllerReady\) return;\s*void commitThenSend\(activeTabId, text\)\.catch/.test(appSource) &&
    /onPrompt=\{handleTranscriptPrompt\}/.test(appSource) &&
    /submitDisabled=\{!controllerReady\}/.test(appSource),
@@ -261,7 +446,7 @@ ok(

 ok(
  /commitThenSendRef\.current\(sourceTabId, trimmed, submitText\.trim\(\), structured\)/.test(appSource) &&
-    /sendToTab\(sourceTabId, displayText, submitText, undefined, structured\)/.test(appSource) &&
+    /sendToTab\(sourceTabId, displayText, submitText, undefined, structured, initialGoal\)/.test(appSource) &&
    /onSteer=\{handleSteer\}/.test(appSource) &&
    /composerInsertRequestsByTab\[activeTabId\]/.test(appSource) &&
    /consumedInsertIdByDraftRef\.current\[draftKey\]/.test(composerSource),
@@ -318,11 +503,11 @@ ok(
  /const navigationRunningRef = useRef\(false\);/.test(appSource) &&
    /const navigationPendingRef = useRef<PendingDesktopNavigationRequest \| null>\(null\);/.test(appSource) &&
    /const runNavigationRequest = useCallback\(async \(request: PendingDesktopNavigationRequest\)/.test(appSource) &&
-    /const latest = \(\) => request\.seq === navigationSeqRef\.current;/.test(appSource) &&
-    /return activateTopic\(scope, workspaceRoot, topicId/.test(appSource) &&
-    /return openTopicSession\(scope, workspaceRoot, topicId/.test(appSource) &&
-    /return openGlobalTab\(topicId\)/.test(appSource) &&
-    /return openProjectTab\(workspaceRoot, topicId\)/.test(appSource) &&
+    /const latest = \(\) => request\.seq === navigationSeqRef\.current && isNavigationIntentCurrent\(request\.navigationIntentSeq\);/.test(appSource) &&
+    /return activateTopic\(scope, workspaceRoot, topicId, sessionPath \|\| "", request\.navigationIntentSeq\)/.test(appSource) &&
+    /return openTopicSession\(scope, workspaceRoot, topicId, sessionPath, request\.navigationIntentSeq\)/.test(appSource) &&
+    /return openGlobalTab\(topicId, request\.navigationIntentSeq\)/.test(appSource) &&
+    /return openProjectTab\(workspaceRoot, topicId, request\.navigationIntentSeq\)/.test(appSource) &&
    /enqueueNavigationRequest\([\s\S]*runningRef: navigationRunningRef, pendingRef: navigationPendingRef/.test(appSource) &&
    !/openTopicQueueRef\.current\.catch\(\(\) => \{\}\)\.then/.test(appSource) &&
    /const refreshLatestTabMetas = async \(\): Promise<TabMeta\[]> => \{[\s\S]*if \(latest\(\)\) setTabMetas\(tabs\);/.test(navigationBlock) &&
@@ -423,7 +608,7 @@ for (const selector of [
 ]) {
  ok(
    finalDeclaration(selector, "--app-chrome-height") === "0px" &&
-      finalDeclaration(selector, "grid-template-rows") === "minmax(0, 1fr)" &&
+      finalDeclaration(selector, "grid-template-rows") === "minmax(0, 1fr) var(--statusbar-height)" &&
      finalDeclaration(selector, "background") === "var(--bg)",
    `${selector} removes the workbench chrome row`,
  );
@@ -454,6 +639,22 @@ ok(
  "maximized workbench dock keeps a draggable title region while tabs remain clickable",
 );

+ok(
+  finalDeclaration(":root[data-theme-style] .workbench-dock__tab--active::after", "bottom") === "1px",
+  "active dock underline stays inside the visible dock edge",
+);
+
+const narrowDockRule = stylesSource.match(/@container \(max-width: 420px\) \{[\s\S]*?\.app--windows-frameless\.app--workbench \.workbench-dock__tab[\s\S]*?\n\}/)?.[0] || "";
+ok(
+  narrowDockRule.includes("padding-left: clamp(") &&
+    narrowDockRule.includes("gap: clamp(") &&
+    narrowDockRule.includes("flex: 0 0 auto") &&
+    narrowDockRule.includes("max-width: none") &&
+    !narrowDockRule.includes("text-overflow: ellipsis") &&
+    !narrowDockRule.includes("overflow: hidden"),
+  "narrow Windows frameless workbench compresses spacing without shrinking or truncating dock tabs",
+);
+
 for (const selector of [
  ":root[data-theme-style] .layout--workbench-chrome-hidden .topicbar",
  ":root[data-theme-style] .layout--workbench-chrome-hidden .topicbar__chrome-btn",
@@ -7,7 +7,7 @@ import { createRoot } from "react-dom/client";
 import gsap from "gsap";
 import { ApprovalModal } from "../components/ApprovalModal";
 import { activeFileReferenceToken, pickInlineFileReference } from "../components/FileReferenceMenu";
-import { LocaleProvider } from "../lib/i18n";
+import { LocaleProvider, preloadDetectedLocale } from "../lib/i18n";
 import type { AppBindings } from "../lib/bridge";
 import type { WireApproval } from "../lib/types";

@@ -95,6 +95,7 @@ function mockApp(methods: Partial<AppBindings>) {
 }

 async function renderApproval(props: Partial<Parameters<typeof ApprovalModal>[0]> = {}) {
+  await preloadDetectedLocale();
  const rootEl = document.getElementById("root");
  if (!rootEl) throw new Error("missing root");
  const root = createRoot(rootEl);
@@ -328,6 +329,70 @@ console.log("\napproval modal file references");
  dom.window.close();
 }

+{
+  const dom = installDom("zh-CN");
+  mockApp({
+    ListDir: async () => [],
+    SearchFileRefs: async () => [],
+  });
+  const { root } = await renderApproval({
+    approval: {
+      id: "dynamic-bash-zh",
+      tool: "bash",
+      subject: "python3 -c \"print('hello')\"",
+      reason: "Matched permission rule: ask Bash(python3:*)\nThis command uses nested or indirect shell execution. Auto and broad allow rules cannot verify the inner command; approve this exact command or use YOLO.",
+    },
+  });
+
+  const text = document.body.textContent ?? "";
+  ok(text.includes("命中权限规则：ask Bash(python3:*)"), "approval identifies the exact matched permission rule");
+  ok(text.includes("嵌套或间接执行"), "dynamic Bash approval explains the matched safety boundary in Chinese");
+  ok(text.includes("精确命令"), "dynamic Bash approval tells the user how to grant the command");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
+{
+  const dom = installDom();
+  mockApp({
+    ListDir: async () => [],
+    SearchFileRefs: async () => [],
+  });
+  const { root, rerender } = await renderApproval();
+
+  await clickImmediateAction("Revise plan");
+
+  const textarea = document.querySelector(".plan-revision__input") as HTMLTextAreaElement | null;
+  if (!textarea) throw new Error("plan revision textarea did not render");
+  ok(textarea === document.activeElement, "opening plan revision focuses its textarea once");
+
+  const transcriptText = document.createElement("p");
+  transcriptText.tabIndex = -1;
+  transcriptText.textContent = "copy this plan text";
+  document.body.appendChild(transcriptText);
+  transcriptText.focus();
+  const range = document.createRange();
+  range.selectNodeContents(transcriptText);
+  const selection = document.getSelection();
+  selection?.removeAllRanges();
+  selection?.addRange(range);
+
+  // App refreshes tab metadata periodically; emulate callback churn from a parent rerender.
+  await rerender({ onRevisionActiveChange: () => undefined });
+
+  ok(document.activeElement === transcriptText, "parent rerender does not return focus to plan revision");
+  eq(document.getSelection()?.toString(), "copy this plan text", "parent rerender preserves transcript text selection");
+
+  transcriptText.remove();
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
 {
  const dom = installDom();
  mockApp({
@@ -65,7 +65,7 @@ ok(
 const errorStart = snapshotBreadcrumbs().length;
 now = 100;
 try {
-  await app.CheckUpdate();
+  await app.CheckUpdate("");
 } catch {
  // Expected: this branch verifies the breadcrumb emitted by the proxy rejection path.
 }
@@ -22,6 +22,8 @@ const appSource = readFileSync(resolve(here, "../App.tsx"), "utf8");
 const projectTreeSource = readFileSync(resolve(here, "../components/ProjectTree.tsx"), "utf8");
 const settingsSource = readFileSync(resolve(here, "../components/SettingsPanel.tsx"), "utf8");
 const markdownSource = readFileSync(resolve(here, "../components/Markdown.tsx"), "utf8");
+const i18nSource = readFileSync(resolve(here, "../lib/i18n.tsx"), "utf8");
+const mainSource = readFileSync(resolve(here, "../main.tsx"), "utf8");
 const stylesSource = readFileSync(resolve(here, "../styles.css"), "utf8");

 console.log("\nbundle contract");
@@ -97,6 +99,20 @@ ok(
  markdownSource.includes('import("./MarkdownRenderer")'),
  "Markdown wrapper loads markdown renderer on demand",
 );
+ok(
+  !/import\s+\{\s*zh\s*\}\s+from\s+["']\.\.\/locales\/zh["']/.test(i18nSource) &&
+    !/import\s+\{\s*zhTW\s*\}\s+from\s+["']\.\.\/locales\/zh-TW["']/.test(i18nSource),
+  "i18n keeps Chinese dictionaries out of the unconditional initial chunk",
+);
+ok(
+  i18nSource.includes('import("../locales/zh")') &&
+    i18nSource.includes('import("../locales/zh-TW")'),
+  "i18n loads Chinese dictionaries on demand",
+);
+ok(
+  mainSource.includes("await preloadDetectedLocale()"),
+  "main preloads the detected locale before mounting React",
+);

 console.log(`\n${passed} passed, ${failed} failed`);
 if (failed > 0) process.exit(1);
@@ -435,6 +435,7 @@ console.log("capabilities panel MCP actions");
    await flush();
  });
  await waitFor("github server row", () => Boolean(document.querySelector(".cap-mcp-list-row__name")?.textContent?.includes("github")));
+  ok(Boolean(findButton("Remove server")), "configured MCP exposes a removal action directly in the server list");
  ok(document.body.textContent?.includes("1 unavailable"), "server list summary reports one quarantined tool");
  ok(!document.body.textContent?.includes("invalid input schema: bad nested type"), "server list keeps raw tool diagnostics out of the overview");

@@ -482,24 +483,35 @@ console.log("capabilities panel MCP actions");
    active: true,
    cwd: "/tmp/reasonix-test",
  }];
-  let projectAuthorizationCount = 0;
  let servers: ServerView[] = [{
    name: "github",
    transport: "stdio",
-    status: "failed",
-    runtimeState: "issue",
+    status: "connected",
+    runtimeState: "ready",
    configured: true,
+    source: "project",
+    configSource: "reasonix.toml",
    autoStart: true,
-    tools: 0,
+    tools: 3,
    prompts: 0,
    resources: 0,
-    error: "project-provided MCP server is blocked until the user authorizes it",
-    requiresLaunchApproval: true,
    toolList: [
      { name: "issue_read", description: "Read issues.", readOnlyHint: true },
      { name: "issue_write", description: "Write issues." },
      { name: "wipe", description: "Delete data.", destructiveHint: true },
    ],
+  }, {
+    name: "linear",
+    transport: "http",
+    status: "connected",
+    runtimeState: "ready",
+    configured: true,
+    source: "user",
+    autoStart: true,
+    tools: 1,
+    prompts: 0,
+    resources: 0,
+    toolList: [{ name: "get_issue", description: "Read an issue.", readOnlyHint: true }],
  }];
  window.go = {
    main: {
@@ -507,16 +519,6 @@ console.log("capabilities panel MCP actions");
        Meta: async () => meta,
        ListTabs: async () => tabs,
        MCPServers: async () => servers,
-        AuthorizeAndConnectMCPServer: async () => {
-          projectAuthorizationCount += 1;
-          servers = servers.map((item) => ({
-            ...item,
-            status: "connected",
-            runtimeState: "ready",
-            requiresLaunchApproval: false,
-            error: "",
-          }));
-        },
      } as Partial<AppBindings> as AppBindings,
    },
  };
@@ -533,16 +535,17 @@ console.log("capabilities panel MCP actions");
      await flush();
    });
  };
-  await waitFor("project MCP authorization action", () => Boolean(findButton("Authorize and connect")));
-  ok(!findButton("Review changes"), "project MCP launch approval has no separate change-review workflow");
+  await waitFor("trusted project MCP", () => Boolean(document.querySelector('[data-status="connected"]')));
+  ok(document.body.textContent?.includes("This project"), "project MCP is grouped under This project");
+  ok(document.body.textContent?.includes("Global MCP"), "user-installed MCP is grouped by its global scope");
+  ok(document.body.textContent?.includes("Install once and use automatically in every Reasonix project."), "global MCP explains its cross-project availability");
+  ok(document.body.textContent?.includes("Project"), "project MCP row shows a project source badge");
+  ok(document.body.textContent?.includes("Declared by this project and available automatically."), "project MCP explains zero-confirmation availability");
+  ok(!findButton("Install and use"), "trusted project MCP has no install confirmation");
+  ok(!findButton("Authorize and connect"), "trusted project MCP has no authorization action");
+  ok(!findButton("Review changes"), "project MCP has no separate change-review workflow");
  ok(!findButton("Refresh catalog"), "catalog maintenance is not part of the normal MCP workflow");
-  ok(!document.querySelector('[role="dialog"]'), "project authorization does not open a second modal");
-  await act(async () => {
-    findButton("Authorize and connect")?.click();
-    await flush();
-  });
-  await waitFor("durable project launch authorization", () => projectAuthorizationCount === 1 && Boolean(document.querySelector('[data-status="connected"]')));
-  ok(!document.querySelector('[role="dialog"]'), "project confirmation connects directly without a second modal");
+  ok(!document.querySelector('[role="dialog"]'), "project MCP does not open a confirmation modal");

  servers = servers.map((item) => ({
    ...item,
@@ -576,13 +579,14 @@ console.log("capabilities panel MCP actions");
    requiresLaunchApproval: false,
  }));
  await refreshStatus();
-  await waitFor("authorized project server row", () => Boolean(document.querySelector('[data-status="connected"]')));
+  await waitFor("trusted project server row", () => Boolean(document.querySelector('[data-status="connected"]')));
  await act(async () => {
    (document.querySelector(".cap-mcp-list-row__main") as HTMLButtonElement | null)?.click();
    await flush();
  });
  await waitFor("connected project server detail", () => Boolean(document.querySelector(".cap-mcp-subpage")));
-  ok(!findButton("Review changes"), "an authorized connected project server does not show a change alarm");
+  ok(document.body.textContent?.includes("Current project · reasonix.toml"), "project MCP details show their configuration source");
+  ok(!findButton("Review changes"), "a trusted connected project server does not show a change alarm");
  ok(!findButton("Revoke trust"), "normal MCP details do not expose a second authorization-management workflow");

  await act(async () => {
@@ -1,6 +1,7 @@
 // Run: tsx src/__tests__/composer-context-menu-clipboard.test.tsx
 //
 // Regression coverage for the composer edit context menu's clipboard guards:
+// - Undo/redo must expose the same fixed shortcuts as the composer keyboard path.
 // - Cut must not delete the selection when every clipboard path failed.
 // - Paste must not replace the selection when the clipboard has no text.
 // - Shortcut hints must use the platform modifier (Ctrl outside macOS).
@@ -193,7 +194,7 @@ async function openInputMenu(): Promise<HTMLButtonElement[]> {
    await flushTimers();
  });
  const items = Array.from(document.querySelectorAll(".context-menu__item")) as HTMLButtonElement[];
-  if (items.length !== 4) throw new Error(`expected 4 edit menu items, got ${items.length}`);
+  if (items.length !== 6) throw new Error(`expected 6 edit menu items, got ${items.length}`);
  return items;
 }

@@ -235,8 +236,10 @@ async function main() {
    await typeAndSelect("hello world", 0, 5);
    const items = await openInputMenu();
    const hints = items.map((item) => item.querySelector(".context-menu__shortcut")?.textContent ?? "");
-    eq(hints[0], "Ctrl+X", "cut hint uses the platform modifier");
-    eq(hints[2], "Ctrl+V", "paste hint uses the platform modifier");
+    eq(hints[0], "Ctrl+Z", "undo hint uses the platform modifier");
+    eq(hints[1], "Ctrl+Shift+Z", "redo hint uses the platform modifier");
+    eq(hints[2], "Ctrl+X", "cut hint uses the platform modifier");
+    eq(hints[4], "Ctrl+V", "paste hint uses the platform modifier");
    ok(hints.every((hint) => !hint.includes("⌘")), "no hardcoded mac glyph on a non-mac platform");
    // Close the menu without acting.
    await act(async () => {
@@ -245,13 +248,29 @@ async function main() {
    });
  }

+  // --- context-menu undo and redo share the programmatic edit history ---
+  {
+    await typeAndSelect("menu undo", 9, 9);
+    const undoItems = await openInputMenu();
+    ok(!undoItems[0].disabled, "undo is enabled at a programmatic edit boundary");
+    ok(undoItems[1].disabled, "redo is disabled before an undo");
+    await clickMenuItem(undoItems[0]);
+    eq(textarea().value, "hello world", "context-menu undo restores the previous composer text");
+
+    const redoItems = await openInputMenu();
+    ok(redoItems[0].disabled === false, "older programmatic history remains undoable");
+    ok(!redoItems[1].disabled, "redo is enabled after context-menu undo");
+    await clickMenuItem(redoItems[1]);
+    eq(textarea().value, "menu undo", "context-menu redo restores the undone composer edit");
+  }
+
  // --- cut keeps the draft when every clipboard path fails ---
  {
    stubClipboard({});
    (document as Document & { execCommand?: () => boolean }).execCommand = () => false;
    await typeAndSelect("hello world", 0, 5);
    const items = await openInputMenu();
-    await clickMenuItem(items[0]);
+    await clickMenuItem(items[2]);
    eq(textarea().value, "hello world", "failed cut must not delete the selection");
  }

@@ -260,7 +279,7 @@ async function main() {
    stubClipboard({ writeText: () => Promise.resolve() });
    await typeAndSelect("hello world", 0, 6);
    const items = await openInputMenu();
-    await clickMenuItem(items[0]);
+    await clickMenuItem(items[2]);
    eq(textarea().value, "world", "successful cut removes the selected text");
  }

@@ -269,7 +288,7 @@ async function main() {
    stubClipboard({ readText: () => Promise.resolve("") });
    await typeAndSelect("hello world", 0, 5);
    const items = await openInputMenu();
-    await clickMenuItem(items[2]);
+    await clickMenuItem(items[4]);
    eq(textarea().value, "hello world", "empty-clipboard paste must not erase the selection");
  }

@@ -278,7 +297,7 @@ async function main() {
    stubClipboard({ readText: () => Promise.resolve("bye") });
    await typeAndSelect("hello world", 0, 5);
    const items = await openInputMenu();
-    await clickMenuItem(items[2]);
+    await clickMenuItem(items[4]);
    eq(textarea().value, "bye world", "text paste replaces the selection");
  }

@@ -6,10 +6,11 @@ import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { Composer, composerPickFileEntry } from "../components/Composer";
 import { InvocationMetadataContext, UserMessage } from "../components/Message";
+import { selectionFromDom } from "../components/RichComposerInput";
 import { LocaleProvider } from "../lib/i18n";
 import { ToastProvider } from "../lib/toast";
 import type { AppBindings } from "../lib/bridge";
-import type { StructuredInvocationSubmit } from "../lib/invocationDisplay";
+import type { ComposerInvocation, StructuredInvocationSubmit } from "../lib/invocationDisplay";
 import type { CollaborationMode, CommandInfo, DirEntry, ToolApprovalMode, TokenMode } from "../lib/types";

 let passed = 0;
@@ -334,6 +335,142 @@ console.log("\ncomposer goal toggle");
  dom.window.close();
 }

+{
+  const dom = installDom();
+  mockApp({
+    Commands: async () => [
+      { name: "ui-ux-pro-max", description: "Review the interface", kind: "skill" },
+    ],
+    ListDirForTab: async () => [],
+    SearchFileRefsForTab: async () => [],
+  });
+  const { root, calls, rerender } = await renderComposer({ collaborationMode: "goal", goal: "" });
+  await replaceComposerDraft(rerender, 4199, "/ui-ux-pro-max");
+  await waitFor("skill menu for the initial goal", () => Boolean(document.querySelector(".slashmenu")));
+  let textarea = document.querySelector("textarea") as HTMLTextAreaElement | null;
+  if (!textarea) throw new Error("composer textarea did not render for the initial goal skill");
+  await act(async () => {
+    textarea.dispatchEvent(new window.KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
+    await flushTimers();
+  });
+
+  let sendButton = document.querySelector(".composer__btn--send") as HTMLButtonElement | null;
+  if (!sendButton) throw new Error("composer send button did not render for the initial goal skill");
+  await act(async () => {
+    sendButton.click();
+    await flushTimers();
+  });
+  eq(calls.send.length, 0, "a skill alone cannot become the initial goal");
+  ok(document.body.textContent?.includes("Enter a goal") === true, "a skill-only initial goal asks for task text");
+
+  await replaceComposerDraft(rerender, 4200, "List the existing notes");
+  sendButton = document.querySelector(".composer__btn--send") as HTMLButtonElement | null;
+  if (!sendButton) throw new Error("composer send button disappeared after entering the goal");
+  await act(async () => {
+    sendButton.click();
+    await flushTimers();
+  });
+  eq(calls.send[0], "List the existing notes", "the initial goal keeps its visible task text");
+  eq(calls.submit[0], "/ui-ux-pro-max List the existing notes", "the initial goal preserves the selected skill");
+  eq(calls.structured[0]?.input, "List the existing notes", "the initial goal sends structured skill input");
+  eq(calls.structured[0]?.invocations[0]?.name, "ui-ux-pro-max", "the initial goal submits the selected skill entity");
+
+  await replaceComposerDraft(rerender, 4201, "/ui-ux-pro-max List the notes again");
+  sendButton = document.querySelector(".composer__btn--send") as HTMLButtonElement | null;
+  if (!sendButton) throw new Error("composer send button did not render for a pasted skill invocation");
+  await act(async () => {
+    sendButton.click();
+    await flushTimers();
+  });
+  eq(calls.send[1], "List the notes again", "a pasted skill invocation keeps its task as the visible goal");
+  eq(calls.submit[1], "/ui-ux-pro-max List the notes again", "a pasted skill invocation keeps its slash display");
+  eq(calls.structured[1]?.input, "List the notes again", "a pasted skill invocation uses structured input");
+  eq(calls.structured[1]?.invocations[0]?.name, "ui-ux-pro-max", "a pasted skill invocation resolves the selected command");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
+{
+  // Attachment-only first Goal: no text, no skill — attachment refs are valid task context.
+  const dom = installDom();
+  mockApp({
+    SavePastedFile: async () => ".reasonix/attachments/notes.txt",
+  });
+  const { root, calls } = await renderComposer({ collaborationMode: "goal", goal: "" });
+  const textarea = document.querySelector("textarea") as HTMLTextAreaElement | null;
+  if (!textarea) throw new Error("composer textarea did not render for attachment-only goal");
+  await act(async () => {
+    dispatchPasteFile(textarea, new File(["hello"], "notes.txt", { type: "text/plain" }));
+    await flushTimers();
+  });
+  await waitFor("attachment-only initial goal card", () => document.body.textContent?.includes("notes.txt") === true);
+
+  const sendButton = document.querySelector(".composer__btn--send") as HTMLButtonElement | null;
+  if (!sendButton) throw new Error("send button missing for attachment-only initial goal");
+  await act(async () => {
+    sendButton.click();
+    await flushTimers();
+  });
+  eq(calls.send.length, 1, "attachment-only input can become the initial Goal");
+  ok(
+    calls.submit[0]?.includes("@.reasonix/attachments/notes.txt") === true,
+    "attachment-only initial Goal submits the attachment ref",
+  );
+  eq(calls.structured[0], undefined, "attachment-only initial Goal is not a structured skill submit");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
+{
+  // Workspace-ref-only first Goal: no text, no skill — workspace refs remain valid task context.
+  const dom = installDom();
+  let droppedCallback: ((x: number, y: number, paths: string[]) => void) | undefined;
+  window.runtime = {
+    EventsOn: () => () => {},
+    BrowserOpenURL: () => {},
+    OnFileDrop: (cb) => {
+      droppedCallback = cb;
+    },
+    OnFileDropOff: () => {},
+  };
+  mockApp({
+    AttachDropped: async () => ({
+      kind: "workspace",
+      path: "src/App.tsx",
+      isDir: false,
+      displayPath: "src/App.tsx",
+    }),
+  });
+  const { root, calls } = await renderComposer({ collaborationMode: "goal", goal: "" });
+  if (!droppedCallback) throw new Error("native file drop handler did not register for workspace-ref goal");
+  await act(async () => {
+    droppedCallback?.(0, 0, ["/repo/src/App.tsx"]);
+    await flushTimers();
+  });
+  await waitFor("workspace-ref-only initial goal card", () => document.body.textContent?.includes("App.tsx") === true);
+
+  const sendButton = document.querySelector(".composer__btn--send") as HTMLButtonElement | null;
+  if (!sendButton) throw new Error("send button missing for workspace-ref-only initial goal");
+  await act(async () => {
+    sendButton.click();
+    await flushTimers();
+  });
+  eq(calls.send.length, 1, "workspace-ref-only input can become the initial Goal");
+  eq(calls.submit[0], "@src/App.tsx", "workspace-ref-only initial Goal submits the workspace ref");
+  eq(calls.structured[0], undefined, "workspace-ref-only initial Goal is not a structured skill submit");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
 {
  const dom = installDom();
  mockApp({
@@ -437,6 +574,126 @@ console.log("\ncomposer goal toggle");
  dom.window.close();
 }

+{
+  const dom = installDom();
+  const command: CommandInfo = {
+    name: "writing-plans",
+    description: "Write a plan",
+    kind: "skill",
+  };
+  mockApp({
+    Commands: async () => [command],
+    ListDirForTab: async () => [],
+    SearchFileRefsForTab: async () => [],
+  });
+  const { root, rerender } = await renderComposer();
+  await replaceComposerDraft(rerender, 4201, "/writing-plans");
+  await waitFor("skill menu for paste undo selection", () => Boolean(document.querySelector(".slashmenu")));
+  const initialTextarea = document.querySelector("textarea") as HTMLTextAreaElement | null;
+  if (!initialTextarea) throw new Error("composer textarea did not render for paste undo selection");
+  await act(async () => {
+    initialTextarea.dispatchEvent(new window.KeyboardEvent("keydown", {
+      key: "Enter",
+      bubbles: true,
+      cancelable: true,
+    }));
+    await flushTimers();
+  });
+
+  let richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  let token = richInput?.querySelector<HTMLElement>(".composer-invocation-token");
+  const invocationId = token?.dataset.invocationId;
+  if (!richInput || !token || !invocationId) throw new Error("rich invocation did not render for paste undo selection");
+  const afterToken = document.createRange();
+  afterToken.setStartAfter(token);
+  afterToken.collapse(true);
+  document.getSelection()?.removeAllRanges();
+  document.getSelection()?.addRange(afterToken);
+  await act(async () => {
+    dispatchPasteText(richInput!, "pasted");
+    await flushTimers();
+  });
+  richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  if (!richInput) throw new Error("rich input disappeared after paste");
+  eq(richComposerTaskText(richInput), "pasted", "paste after an invocation inserts on the token's right side");
+
+  await act(async () => {
+    richInput!.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true, cancelable: true }));
+    await flushTimers();
+  });
+  let richMenuItems = Array.from(document.querySelectorAll<HTMLButtonElement>(".context-menu__item"));
+  eq(richMenuItems.length, 6, "rich composer exposes the shared edit context menu");
+  ok(richMenuItems[0]?.disabled === false, "rich composer context-menu undo is enabled after paste");
+  ok(richMenuItems[1]?.disabled === true, "rich composer context-menu redo is disabled before undo");
+  await act(async () => {
+    richMenuItems[0]?.click();
+    await flushTimers();
+  });
+  richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  if (!richInput) throw new Error("rich input disappeared after context-menu undo");
+  eq(richComposerTaskText(richInput), "", "rich composer context-menu undo removes the pasted text");
+
+  await act(async () => {
+    richInput!.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true, cancelable: true }));
+    await flushTimers();
+  });
+  richMenuItems = Array.from(document.querySelectorAll<HTMLButtonElement>(".context-menu__item"));
+  ok(richMenuItems[1]?.disabled === false, "rich composer context-menu redo is enabled after undo");
+  await act(async () => {
+    richMenuItems[1]?.click();
+    await flushTimers();
+  });
+  richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  if (!richInput) throw new Error("rich input disappeared after context-menu redo");
+  eq(richComposerTaskText(richInput), "pasted", "rich composer context-menu redo restores the pasted text");
+
+  const undoPaste = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    richInput!.dispatchEvent(undoPaste);
+    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+    await flushTimers();
+  });
+  eq(undoPaste.defaultPrevented, true, "Ctrl+Z restores the rich-composer paste transaction");
+
+  richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  token = richInput?.querySelector<HTMLElement>(".composer-invocation-token");
+  if (!richInput || !token) throw new Error("rich invocation disappeared after paste undo");
+  const restoredInvocation: ComposerInvocation = { id: invocationId, offset: 0, command };
+  const restoredSelection = selectionFromDom(
+    richInput,
+    new Map([[invocationId, restoredInvocation]]),
+  );
+  eq(
+    restoredSelection.ok ? restoredSelection.selection.afterInvocationId : undefined,
+    invocationId,
+    "paste undo restores the caret after the invocation token",
+  );
+
+  await act(async () => {
+    richInput!.dispatchEvent(new window.KeyboardEvent("keydown", {
+      key: "Backspace",
+      bubbles: true,
+      cancelable: true,
+    }));
+    await flushTimers();
+  });
+  ok(
+    document.querySelector(".composer-invocation-token") === null,
+    "Backspace after paste undo removes the invocation on the caret's left",
+  );
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
 {
  const dom = installDom();
  const { root, calls } = await renderComposer({
@@ -973,6 +1230,112 @@ console.log("\ncomposer goal toggle");
  dom.window.close();
 }

+{
+  // A backend steer rejection means the turn crossed its final admission
+  // boundary. Keep the guidance item, then submit it as a normal follow-up
+  // after TurnDone instead of treating the rejected call as consumed.
+  const dom = installDom();
+  let steerAttempts = 0;
+  const { root, calls, rerender } = await renderComposer({
+    running: true,
+    onSteer: async () => {
+      steerAttempts += 1;
+      throw new Error("turn ended before guidance could be applied");
+    },
+    onSend: (displayText, submitText) => {
+      calls.send.push(displayText);
+      calls.submit.push(submitText);
+      return Promise.resolve();
+    },
+  });
+
+  await rerender({ insertRequest: { id: 71, text: "preserve this late guidance", mode: "replace" } });
+  const sendButton = document.querySelector(".composer__btn--send") as HTMLButtonElement | null;
+  if (!sendButton) throw new Error("running composer send button did not render");
+  await act(async () => {
+    sendButton.click();
+    await flushTimers();
+  });
+  const guidanceItem = document.querySelector(".composer-guidance-item") as HTMLElement | null;
+  const guideButton = guidanceItem?.querySelector(".composer-guidance-item__guide") as HTMLButtonElement | null;
+  if (!guideButton) throw new Error("late guidance guide button did not render");
+  await act(async () => {
+    guideButton.click();
+    await flushTimers();
+  });
+
+  eq(steerAttempts, 1, "late guidance attempts one strict steer admission");
+  eq(calls.send.length, 0, "rejected steer does not open a provider turn");
+  ok(document.querySelector(".composer-guidance-item") !== null, "rejected steer remains queued");
+
+  await rerender({ running: false });
+  await waitFor("rejected steer sent as follow-up", () => calls.send.length === 1);
+  eq(calls.send[0], "preserve this late guidance", "late guidance becomes the next explicit user turn");
+  ok(document.querySelector(".composer-guidance-item") === null, "follow-up clears only after successful send");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
+{
+  // TurnDone can reach the frontend before an in-flight TrySteer rejection.
+  // Once that rejection settles, the preserved guidance must be re-evaluated
+  // as the next explicit turn instead of remaining stranded on the shelf.
+  const dom = installDom();
+  let steerAttempts = 0;
+  let rejectSteer: (error: Error) => void = () => {};
+  const pendingSteer = new Promise<void>((_, reject) => {
+    rejectSteer = reject;
+  });
+  pendingSteer.catch(() => {});
+  const { root, calls, rerender } = await renderComposer({
+    running: true,
+    onSteer: () => {
+      steerAttempts += 1;
+      return pendingSteer;
+    },
+    onSend: (displayText, submitText) => {
+      calls.send.push(displayText);
+      calls.submit.push(submitText);
+      return Promise.resolve();
+    },
+  });
+
+  await rerender({ insertRequest: { id: 72, text: "retry after TurnDone wins", mode: "replace" } });
+  const sendButton = document.querySelector(".composer__btn--send") as HTMLButtonElement | null;
+  if (!sendButton) throw new Error("running composer send button did not render");
+  await act(async () => {
+    sendButton.click();
+    await flushTimers();
+  });
+  const guideButton = document.querySelector(".composer-guidance-item__guide") as HTMLButtonElement | null;
+  if (!guideButton) throw new Error("deferred steer guide button did not render");
+  await act(async () => {
+    guideButton.click();
+    await flushTimers();
+  });
+
+  eq(steerAttempts, 1, "deferred guidance starts one strict steer admission");
+  await rerender({ running: false });
+  eq(calls.send.length, 0, "TurnDone waits for the in-flight steer result before follow-up");
+
+  await act(async () => {
+    rejectSteer(new Error("turn ended before guidance could be applied"));
+    await flushTimers();
+  });
+  await waitFor("deferred rejected steer sent as follow-up", () => calls.send.length === 1);
+  eq(calls.send[0], "retry after TurnDone wins", "deferred rejection becomes the next explicit user turn");
+  eq(steerAttempts, 1, "deferred rejection is not retried as another steer");
+  ok(document.querySelector(".composer-guidance-item") === null, "deferred follow-up clears after successful send");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
 {
  // Reproduces #6210: a message queued while a turn is running, without the
  // explicit "guide" steer click, must not vanish when the turn ends on its
@@ -1012,6 +1375,42 @@ console.log("\ncomposer goal toggle");
  dom.window.close();
 }

+{
+  // A normal follow-up failure must remain user-controlled. The steer-race
+  // re-arm above must not turn ordinary onSend failures into a retry loop.
+  const dom = installDom();
+  let followupAttempts = 0;
+  const { root, rerender } = await renderComposer({
+    running: true,
+    onSend: () => {
+      followupAttempts += 1;
+      return Promise.reject(new Error("controller is not ready"));
+    },
+  });
+
+  await rerender({ insertRequest: { id: 81, text: "keep failed follow-up", mode: "replace" } });
+  const sendButton = document.querySelector(".composer__btn--send") as HTMLButtonElement | null;
+  if (!sendButton) throw new Error("running composer send button did not render");
+  await act(async () => {
+    sendButton.click();
+    await flushTimers();
+  });
+
+  await rerender({ running: false });
+  await waitFor("queued follow-up attempts once", () => followupAttempts === 1);
+  await act(async () => {
+    await flushTimers();
+    await flushTimers();
+  });
+  eq(followupAttempts, 1, "failed normal follow-up is not retried automatically");
+  ok(document.querySelector(".composer-guidance-item") !== null, "failed normal follow-up remains on the shelf");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
 {
  // #6210 follow-up: if the turn ends naturally while the controller is
  // still activating/hydrating (submitDisabled), onSend would silently
@@ -1252,6 +1651,119 @@ console.log("\ncomposer goal toggle");
  dom.window.close();
 }

+{
+  const dom = installDom();
+  mockApp({
+    Commands: async () => [
+      { name: "writing-plans", description: "Write a plan", kind: "skill", color: "amber" },
+      { name: "review", description: "Review the result", kind: "skill" },
+      { name: "mcp", description: "Manage MCP servers", kind: "builtin", group: "integrations" },
+    ],
+    ListDirForTab: async () => [],
+    SearchFileRefsForTab: async () => [],
+  });
+  const { root, calls, rerender } = await renderComposer();
+
+  const initialText = "请用/writing-plans检查";
+  await replaceComposerDraft(rerender, 1900, initialText);
+  let textarea = document.querySelector("textarea") as HTMLTextAreaElement | null;
+  if (!textarea) throw new Error("composer textarea did not render for middle slash completion");
+  const slashCaret = "请用/writ".length;
+  await act(async () => {
+    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+    await flushTimers();
+  });
+  await act(async () => {
+    textarea!.focus();
+    textarea!.setSelectionRange(slashCaret, slashCaret);
+    textarea!.dispatchEvent(new window.Event("select", { bubbles: true }));
+    textarea!.dispatchEvent(new window.KeyboardEvent("keyup", { key: "/", bubbles: true }));
+    await flushTimers();
+  });
+  await waitFor("middle slash command menu", () => Boolean(document.querySelector(".slashmenu")));
+
+  await act(async () => {
+    textarea!.dispatchEvent(new window.KeyboardEvent("keydown", {
+      key: "Enter",
+      bubbles: true,
+      cancelable: true,
+    }));
+    await flushTimers();
+  });
+
+  let richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  let tokens = richInput?.querySelectorAll<HTMLElement>(".composer-invocation-token");
+  if (!richInput || !tokens?.[0]) throw new Error("middle skill invocation did not render");
+  eq(richComposerTaskText(richInput), "请用检查", "first middle skill selection preserves surrounding text");
+  eq(
+    document.querySelector<HTMLElement>(".invocation-display--composer")?.style.getPropertyValue("--invocation-color"),
+    "#d59a2f",
+    "middle skill selection keeps its configured color",
+  );
+
+  const afterFirstToken = document.createRange();
+  afterFirstToken.setStartAfter(tokens[0]);
+  afterFirstToken.collapse(true);
+  document.getSelection()?.removeAllRanges();
+  document.getSelection()?.addRange(afterFirstToken);
+  await act(async () => {
+    dispatchPasteText(richInput!, "更多");
+    await flushTimers();
+  });
+  richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  if (!richInput) throw new Error("rich input disappeared after middle-skill paste");
+  eq(richComposerTaskText(richInput), "请用更多检查", "paste after a middle skill preserves the entity and suffix");
+  eq(
+    richInput.querySelectorAll(".composer-invocation-token").length,
+    1,
+    "paste after a middle skill keeps the selected entity",
+  );
+
+  await appendRichComposerInput(richInput, " /review");
+  richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  if (!richInput) throw new Error("rich input disappeared before the second skill selection");
+  const queryAtEnd = document.createRange();
+  queryAtEnd.selectNodeContents(richInput);
+  queryAtEnd.collapse(false);
+  document.getSelection()?.removeAllRanges();
+  document.getSelection()?.addRange(queryAtEnd);
+  await act(async () => {
+    richInput!.dispatchEvent(new window.KeyboardEvent("keyup", { key: "w", bubbles: true }));
+    await flushTimers();
+  });
+  await waitFor("second skill menu at the end", () => Boolean(document.querySelector(".slashmenu")));
+  await act(async () => {
+    richInput!.dispatchEvent(new window.KeyboardEvent("keydown", {
+      key: "Enter",
+      bubbles: true,
+      cancelable: true,
+    }));
+    await flushTimers();
+  });
+
+  richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  tokens = richInput?.querySelectorAll<HTMLElement>(".composer-invocation-token");
+  eq(tokens?.length, 2, "a second skill can be inserted after existing text and an entity");
+  const sendButton = document.querySelector(".composer__btn--send") as HTMLButtonElement | null;
+  if (!sendButton) throw new Error("send button did not render for middle skill submission");
+  await act(async () => {
+    sendButton.click();
+    await flushTimers();
+  });
+  eq(calls.structured[0]?.input, "请用更多检查", "middle skills submit the surrounding task text without slash tokens");
+  eq(
+    calls.structured[0]?.invocations.map((item) => item.name).join(","),
+    "writing-plans,review",
+    "multiple middle/end skills submit in visual order",
+  );
+  eq(calls.structured[0]?.invocations[0]?.offset, 2, "first middle skill keeps its text offset");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
 {
  const dom = installDom();
  let commandsCalls = 0;
@@ -1364,8 +1876,42 @@ console.log("\ncomposer goal toggle");
    document.activeElement === textareaAfterEntityRemoval,
    "removing the last entity hands focus to the textarea that replaces the rich input",
  );
+  const undoEntityRemoval = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textareaAfterEntityRemoval.dispatchEvent(undoEntityRemoval);
+    await flushTimers();
+  });
+  eq(undoEntityRemoval.defaultPrevented, true, "Ctrl+Z restores a token removed by the rich composer");
+  ok(
+    document.querySelector(".invocation-display--composer") !== null,
+    "undoing the programmatic Backspace restores the selected skill",
+  );
+  const restoredRichInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  if (!restoredRichInput) throw new Error("rich composer did not return after undoing token removal");
+  const redoEntityRemoval = new window.KeyboardEvent("keydown", {
+    key: "Z",
+    ctrlKey: true,
+    shiftKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    restoredRichInput.dispatchEvent(redoEntityRemoval);
+    await flushTimers();
+  });
+  eq(redoEntityRemoval.defaultPrevented, true, "Ctrl+Shift+Z redoes rich token removal");
+  ok(
+    document.querySelector(".invocation-display--composer") === null,
+    "redoing the programmatic Backspace removes the selected skill again",
+  );

  await replaceComposerDraft(rerender, 2002, "/writing-plans");
+  await waitFor("plain composer after replacing the restored skill", () => Boolean(document.querySelector("textarea")));
  await waitFor("skill menu after removal", () => Boolean(document.querySelector(".slashmenu")));
  textarea = document.querySelector("textarea") as HTMLTextAreaElement | null;
  if (!textarea) throw new Error("composer textarea did not return after removing the skill");
@@ -1802,5 +2348,153 @@ console.log("\ncomposer goal toggle");
  dom.window.close();
 }

+{
+  const dom = installDom();
+  mockApp({
+    Commands: async () => [
+      { name: "review", description: "Review the current task", kind: "skill" },
+    ],
+    ListDirForTab: async () => [],
+    SearchFileRefsForTab: async () => [],
+  });
+  const sessionA = "session:project:/repo:topic-a:session-a";
+  const sessionB = "session:project:/repo:topic-b:session-b";
+  const { root, rerender } = await renderComposer({ sessionKey: sessionA });
+
+  await replaceComposerDraft(rerender, 5000, "x/review");
+  await waitFor("session A slash menu", () => Boolean(document.querySelector(".slashmenu")));
+
+  await rerender({ sessionKey: sessionB, insertRequest: null });
+  await replaceComposerDraft(rerender, 5001, "b");
+  const sessionBInput = document.querySelector("textarea") as HTMLTextAreaElement | null;
+  if (!sessionBInput) throw new Error("session B textarea did not render");
+  await act(async () => {
+    sessionBInput.focus();
+    sessionBInput.setSelectionRange(1, 1);
+    sessionBInput.dispatchEvent(new window.KeyboardEvent("keyup", { key: "b", bubbles: true }));
+    await flushTimers();
+  });
+
+  await rerender({ sessionKey: sessionA, insertRequest: null });
+  eq(
+    (document.querySelector("textarea") as HTMLTextAreaElement | null)?.value,
+    "x/review",
+    "switching back restores session A slash draft",
+  );
+  await waitFor(
+    "restored session A slash menu",
+    () => Boolean(document.querySelector(".slashmenu")),
+  );
+  ok(
+    document.querySelector(".slashmenu") !== null,
+    "restoring a draft recomputes slash completion from its end caret",
+  );
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
+{
+  const dom = installDom();
+  mockApp({
+    Commands: async () => [
+      { name: "review", description: "Review the current task", kind: "skill" },
+    ],
+    ListDirForTab: async () => [],
+    SearchFileRefsForTab: async () => [],
+  });
+  const sessionA = "session:project:/repo:rich-topic-a:rich-session-a";
+  const sessionB = "session:project:/repo:rich-topic-b:rich-session-b";
+  const realRequestAnimationFrame = globalThis.requestAnimationFrame;
+  const queuedComposerFrames: FrameRequestCallback[] = [];
+  globalThis.requestAnimationFrame = (callback) => {
+    queuedComposerFrames.push(callback);
+    return queuedComposerFrames.length;
+  };
+  const { root, rerender } = await renderComposer({ sessionKey: sessionA });
+
+  await replaceComposerDraft(rerender, 6000, "/review");
+  await waitFor("session A first skill menu", () => Boolean(document.querySelector(".slashmenu")));
+  const textarea = document.querySelector("textarea") as HTMLTextAreaElement | null;
+  if (!textarea) throw new Error("session A textarea did not render");
+  await act(async () => {
+    textarea.dispatchEvent(new window.KeyboardEvent("keydown", {
+      key: "Enter",
+      bubbles: true,
+      cancelable: true,
+    }));
+    await flushTimers();
+  });
+
+  let richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  if (!richInput) throw new Error("session A rich input did not render");
+  await appendRichComposerInput(richInput, " /review");
+  richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  if (!richInput) throw new Error("session A rich input disappeared");
+  const queryAtEnd = document.createRange();
+  queryAtEnd.selectNodeContents(richInput);
+  queryAtEnd.collapse(false);
+  document.getSelection()?.removeAllRanges();
+  document.getSelection()?.addRange(queryAtEnd);
+  await act(async () => {
+    richInput.dispatchEvent(new window.KeyboardEvent("keyup", { key: "w", bubbles: true }));
+    await flushTimers();
+  });
+  await waitFor("session A second skill menu", () => Boolean(document.querySelector(".slashmenu")));
+
+  await rerender({ sessionKey: sessionB, insertRequest: null });
+  await replaceComposerDraft(rerender, 6001, "b");
+  await rerender({ sessionKey: sessionA, insertRequest: null });
+  await act(async () => {
+    let frameTime = 0;
+    while (queuedComposerFrames.length > 0) {
+      queuedComposerFrames.shift()?.(frameTime += 16);
+    }
+    await flushTimers();
+  });
+  richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  if (!richInput) throw new Error("session A rich input was not restored");
+  eq(richComposerTaskText(richInput), " /review", "switching back restores the rich invocation draft");
+  await waitFor(
+    "restored session A rich slash menu",
+    () => Boolean(document.querySelector(".slashmenu")),
+  );
+  ok(
+    document.querySelector(".slashmenu") !== null,
+    "restoring a rich invocation draft recomputes slash completion from its end caret",
+  );
+
+  await act(async () => {
+    richInput.dispatchEvent(new window.KeyboardEvent("keydown", {
+      key: "Enter",
+      bubbles: true,
+      cancelable: true,
+    }));
+    await flushTimers();
+  });
+  richInput = document.querySelector(".composer__rich-input") as HTMLDivElement | null;
+  eq(
+    richInput?.querySelectorAll(".composer-invocation-token").length,
+    2,
+    "the restored rich slash query can select a second skill",
+  );
+  eq(richInput ? richComposerTaskText(richInput) : "", " ", "selecting the restored query replaces its slash token");
+
+  await rerender({ sessionKey: sessionB, insertRequest: null });
+  eq(
+    (document.querySelector("textarea") as HTMLTextAreaElement | null)?.value,
+    "b",
+    "switching away again preserves the other session draft",
+  );
+
+  await act(async () => {
+    root.unmount();
+  });
+  globalThis.requestAnimationFrame = realRequestAnimationFrame;
+  dom.window.close();
+}
+
 console.log(`\n${passed} passed, ${failed} failed, ${passed + failed} total`);
 if (failed > 0) process.exit(1);
@@ -0,0 +1,145 @@
+// Run: tsx src/__tests__/composer-menu-viewport.test.ts
+
+import { JSDOM } from "jsdom";
+import {
+  COMPOSER_MENU_AVAILABLE_HEIGHT,
+  composerMenuAvailableHeight,
+  observeComposerMenuViewport,
+} from "../lib/composerMenuViewport";
+
+let passed = 0;
+let failed = 0;
+
+function ok(value: boolean, label: string) {
+  if (value) {
+    process.stdout.write(`  PASS  ${label}\n`);
+    passed += 1;
+  } else {
+    process.stdout.write(`  FAIL  ${label}\n`);
+    failed += 1;
+  }
+}
+
+function eq(actual: unknown, expected: unknown, label: string) {
+  ok(actual === expected, `${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+
+function rect(top: number): DOMRect {
+  return {
+    left: 0,
+    top,
+    right: 600,
+    bottom: top + 120,
+    width: 600,
+    height: 120,
+    x: 0,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect;
+}
+
+class TestResizeObserver {
+  static instance: TestResizeObserver | null = null;
+  readonly observed = new Set<Element>();
+  disconnected = false;
+
+  constructor(private readonly callback: ResizeObserverCallback) {
+    TestResizeObserver.instance = this;
+  }
+
+  observe(target: Element) {
+    this.observed.add(target);
+  }
+
+  unobserve(target: Element) {
+    this.observed.delete(target);
+  }
+
+  disconnect() {
+    this.disconnected = true;
+    this.observed.clear();
+  }
+
+  trigger() {
+    this.callback([], this as unknown as ResizeObserver);
+  }
+}
+
+console.log("\ncomposer menu viewport geometry");
+
+const dom = new JSDOM(`<!doctype html><html><body>
+  <div id="layout">
+    <main id="chat"></main>
+    <footer id="footer"><div id="anchor"><div class="slashmenu"></div></div></footer>
+    <section id="terminal"></section>
+  </div>
+</body></html>`, { pretendToBeVisual: true });
+
+globalThis.window = dom.window as unknown as Window & typeof globalThis;
+globalThis.document = dom.window.document;
+globalThis.Element = dom.window.Element;
+globalThis.HTMLElement = dom.window.HTMLElement;
+globalThis.Event = dom.window.Event;
+globalThis.ResizeObserver = TestResizeObserver as unknown as typeof ResizeObserver;
+
+let nextFrameId = 1;
+const frames = new Map<number, FrameRequestCallback>();
+const requestFrame = (callback: FrameRequestCallback) => {
+  const id = nextFrameId++;
+  frames.set(id, callback);
+  return id;
+};
+const cancelFrame = (id: number) => frames.delete(id);
+dom.window.requestAnimationFrame = requestFrame;
+dom.window.cancelAnimationFrame = cancelFrame;
+globalThis.requestAnimationFrame = requestFrame;
+globalThis.cancelAnimationFrame = cancelFrame;
+
+function flushFrames() {
+  const queued = [...frames.entries()];
+  frames.clear();
+  for (const [, callback] of queued) callback(0);
+}
+
+const anchor = document.getElementById("anchor");
+const terminal = document.getElementById("terminal");
+if (!(anchor instanceof HTMLElement) || !(terminal instanceof HTMLElement)) {
+  throw new Error("missing geometry test elements");
+}
+
+let anchorTop = 567;
+anchor.getBoundingClientRect = () => rect(anchorTop);
+
+eq(composerMenuAvailableHeight(anchorTop), 553, "normal layout exposes the full 360px CSS cap");
+eq(composerMenuAvailableHeight(10), 0, "tiny viewports never produce a negative max height");
+
+const stop = observeComposerMenuViewport(anchor);
+eq(anchor.style.getPropertyValue(COMPOSER_MENU_AVAILABLE_HEIGHT), "553px", "initial layout is measured synchronously");
+
+const observer = TestResizeObserver.instance;
+if (!observer) throw new Error("ResizeObserver was not installed");
+ok(observer.observed.has(terminal), "terminal sibling is observed because it can move the composer anchor");
+
+// Reproduce the constrained layout from the review: terminal + tall composer
+// move the anchor to y=207. The menu has 207 - 6 (anchor gap) - 8 (safe edge)
+// = 193px, so its first rows remain on-screen and the rest scroll internally.
+anchorTop = 207;
+observer.trigger();
+flushFrames();
+eq(anchor.style.getPropertyValue(COMPOSER_MENU_AVAILABLE_HEIGHT), "193px", "terminal expansion uses real space above the composer");
+
+anchorTop = 307;
+window.dispatchEvent(new Event("resize"));
+flushFrames();
+eq(anchor.style.getPropertyValue(COMPOSER_MENU_AVAILABLE_HEIGHT), "293px", "viewport resize recomputes the geometry");
+
+observer.trigger();
+stop();
+eq(frames.size, 0, "cleanup cancels a queued geometry frame");
+eq(anchor.style.getPropertyValue(COMPOSER_MENU_AVAILABLE_HEIGHT), "", "cleanup removes the temporary CSS variable");
+ok(observer.disconnected, "cleanup disconnects layout observers");
+
+dom.window.close();
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);
@@ -56,6 +56,9 @@ eq(finalDeclaration(".composer-card--resized .composer__input", "height"), "100%
 eq(finalDeclaration(".composer-card--resized .composer__input", "overflow-y"), "auto", "resized textarea scrolls internally");
 eq(finalDeclaration(".composer-card--resized .composer__rich-input", "height"), "100%", "resized rich input fills the card's input area");
 eq(finalDeclaration(".composer-card--resized .composer__rich-input", "overflow-y"), "auto", "resized rich input scrolls internally");
+eq(finalDeclaration(".composer-invocation-caret-anchor", "min-width"), "1px", "invocation caret anchor keeps a compact hit target");
+eq(finalDeclaration(".composer-invocation-caret-anchor", "width"), undefined, "invocation caret anchor can expand around WebView2-hosted text");
+eq(finalDeclaration(".composer-invocation-caret-anchor", "overflow"), undefined, "invocation caret anchor does not clip WebView2-hosted text");

 console.log(`\n${passed} passed, ${failed} failed`);
 if (failed > 0) process.exit(1);
@@ -8,6 +8,7 @@ import { Composer } from "../components/Composer";
 import { invalidateCache } from "../lib/composerHistory";
 import { composerDraftKeyForTab } from "../lib/composerDraftKey";
 import { LocaleProvider } from "../lib/i18n";
+import { resetCustomShortcuts, saveCustomShortcut } from "../lib/keyboardShortcuts";
 import {
  SELECTED_TEXT_MAX_CHARS,
  formatSelectedTextContext,
@@ -172,6 +173,24 @@ function textarea(): HTMLTextAreaElement {
  return node;
 }

+function updateTextareaFromUser(
+  value: string,
+  inputType: "insertText" | "deleteContentBackward" | "historyUndo" | "historyRedo",
+) {
+  const input = textarea();
+  input.focus();
+  const setter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, "value")?.set;
+  if (!setter) throw new Error("textarea value setter is unavailable");
+  setter.call(input, value);
+  input.dispatchEvent(new window.InputEvent("input", {
+    bubbles: true,
+    data: inputType === "insertText" ? value.slice(-1) : null,
+    inputType,
+  }));
+  input.dispatchEvent(new window.Event("change", { bubbles: true }));
+  input.dispatchEvent(new window.KeyboardEvent("keyup", { key: "x", bubbles: true }));
+}
+
 function sendButton(): HTMLButtonElement {
  const node = document.querySelector(".composer__btn--send") as HTMLButtonElement | null;
  if (!node) throw new Error("composer send button did not render");
@@ -422,24 +441,93 @@ console.log("\ncomposer session draft");
 {
  const dom = installDom();
  const sent: Array<{ display: string; submit?: string }> = [];
-  const { root } = await renderComposer({
+  const { root, rerender } = await renderComposer({
    onSend: (display, submit) => {
      sent.push({ display, submit });
    },
  });
+  const typedPrefix = "typed before paste: ";
+  await rerender({ insertRequest: { id: 100, text: typedPrefix, mode: "replace" } });
  const rawPaste = "error: failed to compile\r\nat loader.ts:10\r\nat run.ts:22";
  const normalizedPaste = "error: failed to compile\nat loader.ts:10\nat run.ts:22";
  const event = textPasteEvent(rawPaste);

  await act(async () => {
    const input = textarea();
-    input.selectionStart = input.selectionEnd = 0;
+    input.selectionStart = input.selectionEnd = typedPrefix.length;
    input.dispatchEvent(event);
    await flushTimers();
  });

  eq(event.defaultPrevented, true, "short text paste is handled by React state");
-  eq(textarea().value, normalizedPaste, "short multiline paste is visible in the composer");
+  eq(textarea().value, typedPrefix + normalizedPaste, "short multiline paste is visible after existing text");
+
+  const undo = new window.KeyboardEvent("keydown", { key: "z", ctrlKey: true, bubbles: true, cancelable: true });
+  await act(async () => {
+    textarea().dispatchEvent(undo);
+    await flushTimers();
+  });
+  eq(undo.defaultPrevented, true, "Ctrl+Z handles the programmatic paste transaction");
+  eq(textarea().value, typedPrefix, "Ctrl+Z preserves the text typed before a short paste");
+
+  const redo = new window.KeyboardEvent("keydown", {
+    key: "Z",
+    ctrlKey: true,
+    shiftKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(redo);
+    await flushTimers();
+  });
+  eq(redo.defaultPrevented, true, "Ctrl+Shift+Z redoes the programmatic paste transaction");
+  eq(textarea().value, typedPrefix + normalizedPaste, "redo restores the short paste after existing text");
+
+  const undoAgain = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(undoAgain);
+    await flushTimers();
+  });
+  eq(textarea().value, typedPrefix, "a second undo returns to the pre-paste boundary");
+
+  await act(async () => {
+    updateTextareaFromUser(`${typedPrefix}X`, "insertText");
+    await flushTimers();
+  });
+  await rerender();
+  eq(textarea().value, `${typedPrefix}X`, "ordinary typing after paste undo updates the draft");
+  await act(async () => {
+    updateTextareaFromUser(typedPrefix, "deleteContentBackward");
+    await flushTimers();
+  });
+  await rerender();
+
+  const staleRedo = new window.KeyboardEvent("keydown", {
+    key: "Z",
+    ctrlKey: true,
+    shiftKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(staleRedo);
+    await flushTimers();
+  });
+  eq(staleRedo.defaultPrevented, false, "a new native edit invalidates the programmatic redo transaction");
+  eq(textarea().value, typedPrefix, "stale redo cannot resurrect an earlier paste");
+
+  await act(async () => {
+    const input = textarea();
+    input.selectionStart = input.selectionEnd = typedPrefix.length;
+    input.dispatchEvent(textPasteEvent(rawPaste));
+    await flushTimers();
+  });

  await act(async () => {
    sendButton().click();
@@ -447,8 +535,8 @@ console.log("\ncomposer session draft");
  });

  eq(sent.length, 1, "short multiline paste submits once");
-  eq(sent[0]?.display, normalizedPaste, "short multiline paste is preserved in display text");
-  eq(sent[0]?.submit, normalizedPaste, "short multiline paste is preserved in submit text");
+  eq(sent[0]?.display, typedPrefix + normalizedPaste, "short multiline paste is preserved in display text");
+  eq(sent[0]?.submit, typedPrefix + normalizedPaste, "short multiline paste is preserved in submit text");

  await act(async () => {
    root.unmount();
@@ -456,6 +544,460 @@ console.log("\ncomposer session draft");
  dom.window.close();
 }

+{
+  const dom = installDom();
+  const { root, rerender } = await renderComposer();
+  const base = "base:";
+  const pasted = "paste";
+  await rerender({ insertRequest: { id: 101, text: base, mode: "replace" } });
+  await act(async () => {
+    const input = textarea();
+    input.selectionStart = input.selectionEnd = base.length;
+    input.dispatchEvent(textPasteEvent(pasted));
+    await flushTimers();
+  });
+  eq(textarea().value, base + pasted, "interleaved-history test starts at the paste boundary");
+
+  await act(async () => {
+    updateTextareaFromUser(`${base}${pasted}X`, "insertText");
+    await flushTimers();
+  });
+  await rerender();
+  await act(async () => {
+    updateTextareaFromUser(base + pasted, "deleteContentBackward");
+    await flushTimers();
+  });
+  await rerender();
+
+  const undoNativeDelete = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(undoNativeDelete);
+    await flushTimers();
+  });
+  eq(
+    undoNativeDelete.defaultPrevented,
+    false,
+    "Ctrl+Z leaves a native deletion above the paste transaction to the browser",
+  );
+  eq(
+    textarea().value,
+    base + pasted,
+    "matching net text does not make the older paste transaction look newest",
+  );
+
+  await act(async () => {
+    updateTextareaFromUser(`${base}${pasted}X`, "historyUndo");
+    await flushTimers();
+  });
+  await rerender();
+  const undoNativeInsert = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(undoNativeInsert);
+    await flushTimers();
+  });
+  eq(
+    undoNativeInsert.defaultPrevented,
+    false,
+    "Ctrl+Z leaves the remaining native insertion to the browser",
+  );
+
+  await act(async () => {
+    updateTextareaFromUser(base + pasted, "historyUndo");
+    await flushTimers();
+  });
+  await rerender();
+  const undoPasteAfterNative = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(undoPasteAfterNative);
+    await flushTimers();
+  });
+  eq(
+    undoPasteAfterNative.defaultPrevented,
+    true,
+    "the paste transaction becomes undoable only after newer native edits are exhausted",
+  );
+  eq(textarea().value, base, "ordered undo eventually restores the pre-paste text");
+
+  const redoPasteBeforeNative = new window.KeyboardEvent("keydown", {
+    key: "Z",
+    ctrlKey: true,
+    shiftKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(redoPasteBeforeNative);
+    await flushTimers();
+  });
+  eq(
+    redoPasteBeforeNative.defaultPrevented,
+    true,
+    "ordered redo restores the custom paste before its newer native edits",
+  );
+  eq(textarea().value, base + pasted, "custom redo returns to the browser redo boundary");
+
+  const redoNativeAfterPaste = new window.KeyboardEvent("keydown", {
+    key: "Z",
+    ctrlKey: true,
+    shiftKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(redoNativeAfterPaste);
+    await flushTimers();
+  });
+  eq(
+    redoNativeAfterPaste.defaultPrevented,
+    false,
+    "newer native redo remains browser-owned after the paste redo",
+  );
+
+  await act(async () => root.unmount());
+  dom.window.close();
+}
+
+{
+  const dom = installDom();
+  const { root, rerender } = await renderComposer();
+  await act(async () => {
+    textarea().dispatchEvent(textPasteEvent("first"));
+    await flushTimers();
+  });
+  await act(async () => {
+    updateTextareaFromUser("firstX", "insertText");
+    await flushTimers();
+  });
+  await rerender();
+  await act(async () => {
+    const input = textarea();
+    input.selectionStart = input.selectionEnd = input.value.length;
+    input.dispatchEvent(textPasteEvent("second"));
+    await flushTimers();
+  });
+  eq(textarea().value, "firstXsecond", "two custom pastes can surround a native edit");
+
+  const undoSecondPaste = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(undoSecondPaste);
+    await flushTimers();
+  });
+  eq(undoSecondPaste.defaultPrevented, true, "the newest custom paste undoes first");
+  eq(textarea().value, "firstX", "undoing the second paste reaches its native boundary");
+
+  const undoInterleavedNative = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(undoInterleavedNative);
+    await flushTimers();
+  });
+  eq(
+    undoInterleavedNative.defaultPrevented,
+    false,
+    "the native edit between two custom pastes remains browser-owned",
+  );
+  await act(async () => {
+    updateTextareaFromUser("first", "historyUndo");
+    await flushTimers();
+  });
+  await rerender();
+
+  const undoFirstPaste = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(undoFirstPaste);
+    await flushTimers();
+  });
+  eq(undoFirstPaste.defaultPrevented, true, "the older custom paste follows the native undo segment");
+  eq(textarea().value, "", "ordered undo reaches the start of the mixed timeline");
+
+  const redoFirstPaste = new window.KeyboardEvent("keydown", {
+    key: "Z",
+    ctrlKey: true,
+    shiftKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(redoFirstPaste);
+    await flushTimers();
+  });
+  eq(redoFirstPaste.defaultPrevented, true, "ordered redo restores the first custom paste");
+  eq(textarea().value, "first", "redo reaches the native segment after the first paste");
+
+  const redoInterleavedNative = new window.KeyboardEvent("keydown", {
+    key: "Z",
+    ctrlKey: true,
+    shiftKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(redoInterleavedNative);
+    await flushTimers();
+  });
+  eq(
+    redoInterleavedNative.defaultPrevented,
+    false,
+    "ordered redo returns the interleaved native edit to the browser",
+  );
+  await act(async () => {
+    updateTextareaFromUser("firstX", "historyRedo");
+    await flushTimers();
+  });
+  await rerender();
+
+  const redoSecondPaste = new window.KeyboardEvent("keydown", {
+    key: "Z",
+    ctrlKey: true,
+    shiftKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(redoSecondPaste);
+    await flushTimers();
+  });
+  eq(redoSecondPaste.defaultPrevented, true, "the second custom paste redoes after the native segment");
+  eq(textarea().value, "firstXsecond", "mixed custom/native redo restores the final state");
+
+  await act(async () => root.unmount());
+  dom.window.close();
+}
+
+{
+  const dom = installDom();
+  await act(async () => {
+    resetCustomShortcuts();
+    await flushTimers();
+  });
+  saveCustomShortcut("toolApproval.yolo", { key: "z", ctrl: true });
+  let yoloToggles = 0;
+  const { root } = await renderComposer({
+    onToggleYoloApprovalMode: () => {
+      yoloToggles += 1;
+    },
+  });
+  await act(async () => {
+    textarea().dispatchEvent(textPasteEvent("pasted"));
+    await flushTimers();
+  });
+  const undoPaste = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(undoPaste);
+    await flushTimers();
+  });
+  eq(undoPaste.defaultPrevented, true, "legacy Ctrl+Z YOLO binding yields to composer undo while editing");
+  eq(textarea().value, "", "legacy Ctrl+Z YOLO binding still undoes the paste");
+  eq(yoloToggles, 0, "legacy Ctrl+Z YOLO binding does not toggle YOLO while editing");
+
+  await act(async () => {
+    saveCustomShortcut("toolApproval.yolo", { key: "z", ctrl: true, shift: true });
+    await flushTimers();
+  });
+  const legacyRedo = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    shiftKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(legacyRedo);
+    await flushTimers();
+  });
+  eq(legacyRedo.defaultPrevented, true, "legacy Ctrl+Shift+Z YOLO binding yields to composer redo while editing");
+  eq(textarea().value, "pasted", "legacy Ctrl+Shift+Z YOLO binding still redoes the paste");
+  eq(yoloToggles, 0, "legacy Ctrl+Shift+Z YOLO binding does not toggle YOLO while editing");
+
+  await act(async () => {
+    saveCustomShortcut("toolApproval.yolo", { key: "u", ctrl: true });
+    textarea().dispatchEvent(new window.KeyboardEvent("keydown", {
+      key: "z",
+      ctrlKey: true,
+      bubbles: true,
+      cancelable: true,
+    }));
+    await flushTimers();
+  });
+  eq(textarea().value, "", "Ctrl+Z prepares a custom redo transaction after YOLO is rebound");
+
+  const ctrlYRedo = new window.KeyboardEvent("keydown", {
+    key: "y",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(ctrlYRedo);
+    await flushTimers();
+  });
+  eq(ctrlYRedo.defaultPrevented, true, "Ctrl+Y redoes the paste when the YOLO shortcut is rebound");
+  eq(textarea().value, "pasted", "Ctrl+Y restores the programmatic paste");
+  eq(yoloToggles, 0, "Ctrl+Y does not toggle YOLO after that action is rebound");
+
+  await act(async () => {
+    resetCustomShortcuts();
+    await flushTimers();
+  });
+  const defaultCtrlY = new window.KeyboardEvent("keydown", {
+    key: "y",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(defaultCtrlY);
+    await flushTimers();
+  });
+  eq(defaultCtrlY.defaultPrevented, true, "default Ctrl+Y remains reserved for the YOLO shortcut");
+  eq(yoloToggles, 1, "default Ctrl+Y still toggles YOLO exactly once");
+  eq(textarea().value, "pasted", "the YOLO shortcut does not mutate composer history");
+
+  await act(async () => root.unmount());
+  resetCustomShortcuts();
+  dom.window.close();
+}
+
+{
+  const dom = installDom();
+  const { root, rerender } = await renderComposer({
+    tabId: "tab-a",
+    sessionKey: "session:project:/repo:topic-a:session-a",
+  });
+  const longPaste = Array.from({ length: 20 }, (_, index) => `line ${index + 1}`).join("\n");
+  await act(async () => {
+    textarea().dispatchEvent(textPasteEvent(longPaste));
+    await flushTimers();
+  });
+  ok(document.querySelector(".composer__pasted-label") !== null, "long paste creates a folded block");
+  const previewButton = document.querySelector<HTMLButtonElement>(".composer__pasted-actions button");
+  if (!previewButton) throw new Error("long paste preview button did not render");
+  await act(async () => {
+    previewButton.click();
+    await flushTimers();
+  });
+  ok(document.querySelector(".composer__pasted-preview") !== null, "long paste preview opens without changing text history");
+
+  await rerender({
+    tabId: "tab-b",
+    sessionKey: "session:project:/repo:topic-b:session-b",
+    insertRequest: { id: 101, text: "draft B", mode: "replace" },
+  });
+  const unrelatedUndo = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(unrelatedUndo);
+    await flushTimers();
+  });
+  eq(unrelatedUndo.defaultPrevented, false, "another draft does not inherit the paste undo transaction");
+  eq(textarea().value, "draft B", "Ctrl+Z in another draft leaves its text unchanged");
+
+  await rerender({ tabId: "tab-a", sessionKey: "session:project:/repo:topic-a:session-a" });
+  ok(document.querySelector(".composer__pasted-preview") !== null, "source draft restores its open long-paste preview");
+  const foldedUndo = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(foldedUndo);
+    await flushTimers();
+  });
+  eq(foldedUndo.defaultPrevented, true, "source draft keeps its own folded-paste undo transaction");
+  eq(textarea().value, "", "Ctrl+Z removes the folded-paste label");
+  ok(document.querySelector(".composer__pasted-label") === null, "Ctrl+Z removes the folded block state");
+  ok(document.querySelector(".composer__pasted-preview") === null, "Ctrl+Z also clears preview state with the folded block");
+
+  await act(async () => root.unmount());
+  dom.window.close();
+}
+
+{
+  const dom = installDom();
+  const { root } = await renderComposer();
+  const longPaste = Array.from({ length: 20 }, (_, index) => `expanded ${index + 1}`).join("\n");
+  await act(async () => {
+    textarea().dispatchEvent(textPasteEvent(longPaste));
+    await flushTimers();
+  });
+  const expandButton = document.querySelectorAll<HTMLButtonElement>(".composer__pasted-actions button")[1];
+  if (!expandButton) throw new Error("long paste expand button did not render");
+  await act(async () => {
+    expandButton.click();
+    await flushTimers();
+  });
+  eq(textarea().value, longPaste, "expanding a folded paste restores its original text");
+  ok(document.querySelector(".composer__pasted-label") === null, "expanded paste no longer renders a folded label");
+
+  const undoExpand = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(undoExpand);
+    await flushTimers();
+  });
+  eq(undoExpand.defaultPrevented, true, "Ctrl+Z treats pasted-block expansion as a custom transaction");
+  ok(document.querySelector(".composer__pasted-label") !== null, "undoing expansion restores the folded block");
+
+  const undoLongPaste = new window.KeyboardEvent("keydown", {
+    key: "z",
+    ctrlKey: true,
+    bubbles: true,
+    cancelable: true,
+  });
+  await act(async () => {
+    textarea().dispatchEvent(undoLongPaste);
+    await flushTimers();
+  });
+  eq(undoLongPaste.defaultPrevented, true, "a second Ctrl+Z undoes the original folded paste");
+  eq(textarea().value, "", "undoing the original folded paste restores the empty draft");
+
+  await act(async () => root.unmount());
+  dom.window.close();
+}
+
 {
  const dom = installDom();
  const saveStarted = deferred<void>();
@@ -577,7 +1119,7 @@ console.log("\ncomposer session draft");
  textarea().setSelectionRange(2, 2);
  const menuItems = await openComposerInputMenu();
  await act(async () => {
-    menuItems[2]?.click();
+    menuItems[4]?.click();
    await flushTimers();
  });
  await rerender({
@@ -624,7 +1166,7 @@ console.log("\ncomposer session draft");
  textarea().setSelectionRange(1, 4);
  const menuItems = await openComposerInputMenu();
  await act(async () => {
-    menuItems[0]?.click();
+    menuItems[2]?.click();
    await clipboardWriteStarted.promise;
  });
  await rerender({
@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+
+function ok(value: unknown, message: string) {
+  if (!value) throw new Error(message);
+}
+
+const source = readFileSync(new URL("../components/MemoryPanel.tsx", import.meta.url), "utf8");
+
+ok(source.includes("function memoryFactKey"), "Context Center must use a stable fact identity helper");
+ok(source.includes("app.MemoryRevisionsForTab"), "Context Center must load revision history for the selected workspace");
+ok(source.includes("app.RestoreMemoryRevisionForTab"), "Context Center must restore a selected revision");
+ok(source.includes("view.lastRecall"), "Context Center must explain the last automatic recall");
+ok(source.includes("view.conflicts"), "Context Center must explain project-over-global memory resolution");
+ok(source.includes("view.instructionDiagnostics"), "Context Center must surface instruction diagnostics");
+ok(source.includes("d.precedence"), "Context Center must show resolved instruction precedence");
+
+console.log("context-center-contract: ok");
@@ -146,6 +146,31 @@ console.log("\ncontext window ring");
  dom.window.close();
 }

+{
+  const dom = installDom();
+  installContextPanelMock(async () => contextPanelInfo(0));
+
+  const { root } = await renderRing({ turnCost: 0.125, currency: "$" });
+  const button = document.querySelector(".context-ring") as HTMLButtonElement | null;
+  if (!button) throw new Error("missing context ring button");
+  await act(async () => {
+    button.dispatchEvent(new MouseEvent("mouseover", { bubbles: true, relatedTarget: null }));
+    await wait(220);
+  });
+  const turnCostRow = [...document.querySelectorAll(".context-ring-popover__row")]
+    .find((row) => row.querySelector(".context-ring-popover__label")?.textContent === "turn cost");
+  eq(
+    turnCostRow?.querySelector(".context-ring-popover__value")?.textContent,
+    "$0.1250",
+    "turn cost uses the session currency before panel info is available",
+  );
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
 {
  const dom = installDom();
  const calls: string[] = [];
@@ -10,6 +10,7 @@ import { createRoot } from "react-dom/client";
 import gsap from "gsap";
 import { ApprovalModal } from "../components/ApprovalModal";
 import { ClearContextCard } from "../components/ClearContextCard";
+import { RuntimeDecisionCard } from "../components/RuntimeDecisionCard";
 import { LocaleProvider } from "../lib/i18n";
 import type { WireApproval } from "../lib/types";

@@ -73,13 +74,14 @@ function installDom(language = "en-US") {

 console.log("\ndecision surface");

-// Plan keeps one explicit start decision, but both visible choices are direct
-// buttons. Exit/stop remain global controls rather than extra card branches.
+// Plan exposes start, revise, and leave-without-executing as direct buttons so
+// declining the current plan never traps the user in Plan mode.
 {
  const dom = installDom();
  const root = createRoot(document.getElementById("root")!);
  const answers: Array<[boolean, boolean, boolean]> = [];
  const revisions: string[] = [];
+  let exits = 0;
  const approval: WireApproval = {
    id: "plan-1",
    tool: "exit_plan_mode",
@@ -93,6 +95,7 @@ console.log("\ndecision surface");
          approval={approval}
          onAnswer={(a, s, p) => answers.push([a, s, p])}
          onRevisePlan={(text) => revisions.push(text)}
+          onExitPlan={() => { exits += 1; }}
          onStop={() => undefined}
        />
      </LocaleProvider>,
@@ -101,11 +104,11 @@ console.log("\ndecision surface");
  });

  const actions = [...document.querySelectorAll(".prompt-shelf__actions .prompt-action")] as HTMLButtonElement[];
-  eq(actions.length, 2, "Plan has start and revise actions only");
+  eq(actions.length, 3, "Plan has start, revise, and exit-without-executing actions");
  eq(document.querySelector(".prompt-shelf__actions")?.getAttribute("role"), "group", "Plan actions use button-group semantics");
  ok(actions.every((action) => action.getAttribute("role") === "button"), "Plan actions are announced as buttons");
  ok(!document.querySelector(".decision-confirm-bar__confirm"), "Plan has no redundant confirm button");
-  ok(!document.body.textContent?.includes("Exit plan mode"), "Plan card hides the exit branch");
+  ok(actions[2].textContent?.includes("Exit without executing"), "Plan card exposes a clear non-executing exit");
  ok(!document.body.textContent?.includes("Stop task"), "Plan card relies on the global Stop control");

  await act(async () => {
@@ -115,6 +118,46 @@ console.log("\ndecision surface");
  ok(document.querySelector(".plan-revision__input") != null, "Revise opens the inline editor in one click");
  eq(answers.length, 0, "Opening revision does not start execution");

+  await act(async () => {
+    actions[2].click();
+    actions[2].click();
+    await flushTimers(220);
+  });
+  eq(exits, 1, "Exit without executing runs once and ignores a double click");
+  eq(answers.length, 0, "Exit without executing never approves plan execution");
+  eq(revisions.length, 0, "Exit without executing does not submit a plan revision");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
+{
+  const dom = installDom();
+  const root = createRoot(document.getElementById("root")!);
+  let exits = 0;
+
+  await act(async () => {
+    root.render(
+      <LocaleProvider>
+        <ApprovalModal
+          approval={{ id: "plan-exit-key", tool: "exit_plan_mode", subject: "Plan ready" }}
+          onAnswer={() => undefined}
+          onExitPlan={() => { exits += 1; }}
+          onStop={() => undefined}
+        />
+      </LocaleProvider>,
+    );
+    await flushTimers();
+  });
+
+  await act(async () => {
+    document.dispatchEvent(new window.KeyboardEvent("keydown", { key: "3", bubbles: true }));
+    await flushTimers(220);
+  });
+  eq(exits, 1, "number key 3 exits Plan without execution");
+
  await act(async () => {
    root.unmount();
  });
@@ -577,6 +620,83 @@ console.log("\ndecision surface");
  dom.window.close();
 }

+// Runtime decisions expose direct actions, so their displayed number keys must
+// invoke the same callbacks while preserving normal typing behavior.
+{
+  const dom = installDom();
+  const root = createRoot(document.getElementById("root")!);
+  const selected: string[] = [];
+  let cancelled = 0;
+
+  await act(async () => {
+    root.render(
+      <LocaleProvider>
+        <RuntimeDecisionCard
+          id="runtime-shortcuts"
+          title="Choose runtime action"
+          badge="Runtime"
+          meta="Select an action"
+          actions={["1", "2", "3"].map((key) => ({
+            key,
+            label: `Action ${key}`,
+            description: `Run action ${key}`,
+            onClick: () => selected.push(key),
+          }))}
+          onCancel={() => { cancelled += 1; }}
+        />
+      </LocaleProvider>,
+    );
+    await flushTimers();
+  });
+
+  await act(async () => {
+    document.dispatchEvent(new window.KeyboardEvent("keydown", { key: "1", bubbles: true }));
+    document.dispatchEvent(new window.KeyboardEvent("keydown", { key: "2", bubbles: true }));
+    document.dispatchEvent(new window.KeyboardEvent("keydown", { key: "3", bubbles: true }));
+    await flushTimers();
+  });
+  eq(selected.join(","), "1,2,3", "runtime decision number keys invoke their displayed actions");
+
+  await act(async () => {
+    root.render(
+      <LocaleProvider>
+        <RuntimeDecisionCard
+          id="runtime-shortcuts"
+          title="Choose runtime action"
+          badge="Runtime"
+          meta="Select an action"
+          actions={[{
+            key: "2", label: "Unavailable action", description: "Cannot run yet",
+            disabled: true, onClick: () => selected.push("disabled"),
+          }]}
+          onCancel={() => { cancelled += 1; }}
+        />
+      </LocaleProvider>,
+    );
+    await flushTimers();
+  });
+  await act(async () => {
+    document.dispatchEvent(new window.KeyboardEvent("keydown", { key: "2", bubbles: true }));
+    await flushTimers();
+  });
+  eq(selected.join(","), "1,2,3", "runtime decision shortcuts do not invoke disabled actions");
+
+  const input = document.createElement("input");
+  document.body.append(input);
+  await act(async () => {
+    input.dispatchEvent(new window.KeyboardEvent("keydown", { key: "1", bubbles: true }));
+    document.dispatchEvent(new window.KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+    await flushTimers();
+  });
+  eq(selected.join(","), "1,2,3", "runtime decision shortcuts ignore editable fields");
+  eq(cancelled, 1, "Escape cancels the runtime decision");
+
+  await act(async () => {
+    root.unmount();
+  });
+  dom.window.close();
+}
+
 // Clear context: default cancel; clear requires explicit confirm; Escape cancels.
 {
  const dom = installDom();
@@ -75,7 +75,7 @@ function baseReport(runtime: boolean): CapabilityDiagnosticsReport {
      plugins: 0,
      mcp_servers: 1,
    },
-    instructions: { docs: [{ path: "<workspace>/AGENTS.md", scope: "project", order: 1 }] },
+    instructions: { docs: [{ path: "<workspace>/AGENTS.md", scope: "project", directory: "<workspace>", depth: 0, order: 1 }] },
    skills: {
      roots: [{ path: "<workspace>/.reasonix/skills", scope: "project", status: "ok" }],
      entries: [{ name: "demo", path: "<workspace>/.reasonix/skills/demo/SKILL.md", status: "winner" }],
@@ -0,0 +1,133 @@
+// Run: tsx src/__tests__/footer-decision-overflow.test.ts
+//
+// Contract: the footer becomes a scroll/clip container ONLY while a decision
+// surface (plan/tool approval, ask, clear-context) is shown. Scoping the
+// overflow to `.footer--decision` keeps tall approval cards scrolling inside a
+// capped footer (#7030) while leaving the composer state unclipped, so the
+// upward-popping "/" and "@" menus (.slashmenu — position:absolute; bottom:
+// calc(100% + 6px)) can expand to full height. An unconditional overflow-y on
+// .footer clipped those menus to a thin strip above the input box (regression
+// shipped after desktop-v1.18.0 via the #7030 fix in #7069).
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const testDir = dirname(fileURLToPath(import.meta.url));
+// Strip comments so declaration parsing never matches prose inside them.
+const styles = readFileSync(resolve(testDir, "../styles.css"), "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+const appSource = readFileSync(resolve(testDir, "../App.tsx"), "utf8");
+const composerSource = readFileSync(resolve(testDir, "../components/Composer.tsx"), "utf8");
+
+let passed = 0;
+let failed = 0;
+
+function eq(a: unknown, b: unknown, label: string) {
+  if (a === b) {
+    process.stdout.write(`  PASS  ${label}\n`);
+    passed += 1;
+  } else {
+    process.stdout.write(`  FAIL  ${label}: expected ${JSON.stringify(b)}, got ${JSON.stringify(a)}\n`);
+    failed += 1;
+  }
+}
+
+function matchingBlocks(selector: string): string[] {
+  const blocks: string[] = [];
+  const rule = /([^{}]+)\{([^{}]*)\}/g;
+  let match: RegExpExecArray | null;
+  while ((match = rule.exec(styles)) !== null) {
+    const selectors = match[1].split(",").map((part) => part.trim());
+    if (selectors.includes(selector)) blocks.push(match[2]);
+  }
+  return blocks;
+}
+
+function finalDeclaration(selector: string, property: string): string | undefined {
+  let value: string | undefined;
+  for (const block of matchingBlocks(selector)) {
+    const declaration = new RegExp(`(?:^|;)\\s*${property}\\s*:\\s*([^;]+)`, "g");
+    let match: RegExpExecArray | null;
+    while ((match = declaration.exec(block)) !== null) {
+      value = match[1].trim();
+    }
+  }
+  return value;
+}
+
+console.log("\nfooter decision overflow");
+
+// AC1 — composer state: the base footer is not a scroll/clip container, so the
+// upward-popping menus are free to expand.
+eq(finalDeclaration(".footer", "overflow-y"), undefined, "base .footer does not scroll/clip (composer menus can expand)");
+eq(finalDeclaration(".footer", "max-height"), undefined, "base .footer is not height-capped in the composer state");
+eq(finalDeclaration(".footer", "flex"), "0 0 auto", "base .footer keeps its flex sizing");
+
+// AC2 — decision state: capped + scrollable so tall approval cards stay
+// reachable and never slip behind the status bar (#7030 stays fixed).
+eq(finalDeclaration(".footer--decision", "overflow-y"), "auto", "decision footer scrolls tall approval cards");
+eq(finalDeclaration(".footer--decision", "max-height"), "calc(100% - var(--topicbar-height))", "decision footer is capped above the status bar");
+
+// AC3 — the menu stays anchored above the composer, but its preferred 360px cap
+// is now bounded by the real viewport space measured by Composer.
+eq(finalDeclaration(".slashmenu", "position"), "absolute", ".slashmenu still anchors to the composer");
+eq(finalDeclaration(".slashmenu", "bottom"), "calc(100% + 6px)", ".slashmenu still pops above the composer");
+eq(finalDeclaration(".slashmenu", "max-height"), "min(360px, var(--composer-menu-available-height, 50vh))", ".slashmenu uses the measured available height");
+
+// AC4 — App.tsx applies footer--decision exactly when a decision surface owns
+// the footer, and the pre-existing footer--compact wiring stays intact.
+eq(/decisionSurface \? "footer--decision" : ""/.test(appSource), true, "App.tsx toggles footer--decision on decisionSurface");
+eq(/terminalPanelOpen && !sidebarCreation \? "footer--compact" : ""/.test(appSource), true, "footer--compact wiring stays intact");
+eq(/ref=\{composerWrapRef\}/.test(composerSource), true, "Composer measures the real menu anchor");
+eq(/observeComposerMenuViewport\(anchor\)/.test(composerSource), true, "Composer observes geometry while a menu is open");
+
+// AC5 — mutual-exclusivity guard: the composer host is hidden while a decision
+// owns the footer, so a menu can never open in the decision state.
+eq(finalDeclaration(".composer-decision-host--hidden", "display"), "none !important", "composer host stays hidden under a decision (menus cannot open)");
+
+// AC6 — guard the detection gap noted in #7128's first review and covered by
+// #7138: no scoped footer variant except the decision modifier may reintroduce
+// clipping or a height cap around the composer menus.
+function footerTarget(selectorPart: string): string {
+  return selectorPart.split(/[\s>+~]+/).pop() ?? "";
+}
+
+function targetsFooterElement(selectorPart: string): boolean {
+  return /\.footer(?!__)(--[a-z-]+)?(?=$|[.:\[])/.test(footerTarget(selectorPart));
+}
+
+function isDecisionTarget(selectorPart: string): boolean {
+  return footerTarget(selectorPart).includes(".footer--decision");
+}
+
+function declValue(body: string, property: string): string | undefined {
+  const declaration = new RegExp(`(?:^|;)\\s*${property}\\s*:\\s*([^;]+)`, "g");
+  let value: string | undefined;
+  let match: RegExpExecArray | null;
+  while ((match = declaration.exec(body)) !== null) value = match[1].trim();
+  return value;
+}
+
+function footerClipOffenders(): string[] {
+  const offenders: string[] = [];
+  const rule = /([^{}]+)\{([^{}]*)\}/g;
+  let match: RegExpExecArray | null;
+  while ((match = rule.exec(styles)) !== null) {
+    const selectorList = match[1].trim();
+    const parts = selectorList.split(",").map((part) => part.trim());
+    const footerParts = parts.filter(targetsFooterElement);
+    if (footerParts.length === 0 || footerParts.every(isDecisionTarget)) continue;
+    const body = match[2];
+    const clips =
+      (declValue(body, "overflow") ?? "visible") !== "visible" ||
+      (declValue(body, "overflow-y") ?? "visible") !== "visible" ||
+      (declValue(body, "overflow-x") ?? "visible") !== "visible";
+    if (clips || declValue(body, "max-height") !== undefined) offenders.push(selectorList);
+  }
+  return offenders;
+}
+
+eq(footerClipOffenders().join(", "), "", "no footer rule except .footer--decision clips or caps the footer");
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);
@@ -0,0 +1,138 @@
+// Run: tsx src/__tests__/github-link-rendering.test.tsx
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { JSDOM } from "jsdom";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { classifyLinkIcon, parseGitHubLink } from "../components/githubLink";
+import { RichMarkdownLink } from "../components/githubLink";
+
+let passed = 0;
+let failed = 0;
+
+function ok(value: unknown, label: string) {
+  eq(Boolean(value), true, label);
+}
+
+function eq(actual: unknown, expected: unknown, label: string) {
+  if (JSON.stringify(actual) === JSON.stringify(expected)) {
+    process.stdout.write(`  PASS  ${label}\n`);
+    passed += 1;
+  } else {
+    process.stdout.write(
+      `  FAIL  ${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}\n`,
+    );
+    failed += 1;
+  }
+}
+
+console.log("\ngithub link rendering");
+
+eq(parseGitHubLink("https://github.com/esengine/DeepSeek-Reasonix/issues/6856"), {
+  kind: "issue",
+  owner: "esengine",
+  repo: "DeepSeek-Reasonix",
+  value: "6856",
+  compactLabel: "#6856",
+}, "recognizes GitHub issue links");
+
+eq(parseGitHubLink("https://github.com/esengine/DeepSeek-Reasonix/pull/123?diff=split"), {
+  kind: "pull",
+  owner: "esengine",
+  repo: "DeepSeek-Reasonix",
+  value: "123",
+  compactLabel: "PR #123",
+}, "recognizes GitHub pull request links with query parameters");
+
+eq(parseGitHubLink("https://github.com/esengine/DeepSeek-Reasonix/commit/abcdef1234567890"), {
+  kind: "commit",
+  owner: "esengine",
+  repo: "DeepSeek-Reasonix",
+  value: "abcdef1234567890",
+  compactLabel: "abcdef1",
+}, "recognizes GitHub commit links");
+
+eq(parseGitHubLink("https://github.com/esengine/DeepSeek-Reasonix"), null, "leaves repository links unchanged");
+eq(parseGitHubLink("http://github.com/esengine/DeepSeek-Reasonix/issues/1"), null, "rejects insecure GitHub links");
+eq(parseGitHubLink("https://example.com/issues/6856"), null, "leaves non-GitHub links unchanged");
+eq(parseGitHubLink("javascript:alert(1)"), null, "does not enhance unsafe links");
+
+eq(classifyLinkIcon("https://github.com/esengine/DeepSeek-Reasonix"), "github", "adds a GitHub icon to repository links");
+eq(classifyLinkIcon("https://example.com/docs"), "external", "adds an external-link icon to web links");
+eq(classifyLinkIcon("http://localhost:5173/docs"), "external", "adds an external-link icon to HTTP links");
+eq(classifyLinkIcon("mailto:[email protected]"), "mail", "adds a mail icon to email links");
+eq(classifyLinkIcon("./docs/GUIDE.md"), null, "leaves relative links without an icon");
+eq(classifyLinkIcon("#section"), null, "leaves page fragments without an icon");
+eq(classifyLinkIcon("javascript:alert(1)"), null, "does not add icons to unsafe protocols");
+
+function renderLink(href: string, label: string = href) {
+  const markup = renderToStaticMarkup(
+    createElement(RichMarkdownLink, { href, children: label }),
+  );
+  return new JSDOM(markup).window.document.querySelector("a");
+}
+
+{
+  const href = "https://github.com/esengine/DeepSeek-Reasonix/pull/6976";
+  const link = renderLink(href);
+  const label = link?.querySelector(".md-rich-link__label");
+  eq(label?.textContent, href, "keeps the original GitHub URL in selectable DOM text");
+  eq(label?.getAttribute("data-display-label"), "PR #6976", "exposes the compact visual PR label");
+  eq(
+    link?.getAttribute("aria-label"),
+    "GitHub esengine/DeepSeek-Reasonix pull request #6976",
+    "gives compact PR links a contextual accessible name",
+  );
+  ok(link?.querySelector("svg[aria-hidden=\"true\"]"), "hides the decorative GitHub icon from assistive technology");
+
+  const selection = link?.ownerDocument.defaultView?.getSelection();
+  const range = link?.ownerDocument.createRange();
+  if (link && selection && range) {
+    range.selectNodeContents(link);
+    selection.removeAllRanges();
+    selection.addRange(range);
+  }
+  eq(selection?.toString(), href, "copies the original URL instead of the compact visual label");
+}
+
+{
+  const link = renderLink(
+    "https://github.com/esengine/DeepSeek-Reasonix/issues/6856",
+    "Readable issue title",
+  );
+  eq(link?.textContent, "Readable issue title", "preserves an explicit Markdown link label");
+  eq(
+    link?.querySelector(".md-rich-link__label")?.hasAttribute("data-display-label"),
+    false,
+    "does not compact explicit Markdown link labels",
+  );
+  eq(link?.hasAttribute("aria-label"), false, "does not override an explicit accessible link label");
+}
+
+{
+  const link = renderLink("https://example.com/a/very/long/documentation/path");
+  ok(link?.classList.contains("md-rich-link--external"), "renders ordinary HTTPS destinations as rich external links");
+  ok(link?.querySelector("svg[aria-hidden=\"true\"]"), "renders a decorative external-link icon");
+}
+
+{
+  const relative = renderLink("./docs/GUIDE.md", "Guide");
+  eq(relative?.className, "", "leaves relative links without rich-link styling");
+  eq(relative?.querySelector("svg"), null, "leaves relative links without an icon");
+}
+
+{
+  const styles = readFileSync(fileURLToPath(new URL("../styles.css", import.meta.url)), "utf8");
+  ok(
+    /\.md \.md-rich-link\s*\{[^}]*white-space:\s*normal;/.test(styles),
+    "allows rich links to wrap on narrow layouts",
+  );
+  ok(
+    /\.md \.md-rich-link__label\s*\{[^}]*min-width:\s*0;[^}]*overflow-wrap:\s*anywhere;/.test(styles),
+    "lets long unbroken link labels shrink and wrap",
+  );
+}
+
+console.log(`\n${passed} passed, ${failed} failed, ${passed + failed} total`);
+if (failed > 0) process.exit(1);
@@ -0,0 +1,109 @@
+// Run: tsx src/__tests__/goal-action-errors.test.tsx
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { JSDOM } from "jsdom";
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { useGoalActionHandler } from "../lib/goalAction";
+import { ToastProvider } from "../lib/toast";
+
+let passed = 0;
+let failed = 0;
+
+function ok(value: boolean, label: string) {
+  if (value) {
+    process.stdout.write(`  PASS  ${label}\n`);
+    passed += 1;
+  } else {
+    process.stdout.write(`  FAIL  ${label}\n`);
+    failed += 1;
+  }
+}
+
+function flushPromises(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+console.log("\ngoal action bridge errors");
+
+const dom = new JSDOM("<!doctype html><html><body><div id=\"root\"></div></body></html>", {
+  pretendToBeVisual: true,
+  url: "http://localhost/",
+});
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+globalThis.window = dom.window as unknown as Window & typeof globalThis;
+globalThis.document = dom.window.document;
+globalThis.Event = dom.window.Event;
+globalThis.MouseEvent = dom.window.MouseEvent;
+
+const unhandled: unknown[] = [];
+const onUnhandledRejection = (reason: unknown) => unhandled.push(reason);
+const onWindowUnhandledRejection = (event: PromiseRejectionEvent) => unhandled.push(event.reason);
+process.on("unhandledRejection", onUnhandledRejection);
+window.addEventListener("unhandledrejection", onWindowUnhandledRejection);
+
+function Probe() {
+  const { runGoalAction } = useGoalActionHandler();
+  const run = (label: string) => {
+    runGoalAction(async () => {
+      throw new Error(`${label} bridge failed`);
+    });
+  };
+  return (
+    <>
+      <button type="button" data-action="stop" onClick={() => run("stop goal")}>stop</button>
+      <button type="button" data-action="mode" onClick={() => run("switch mode")}>mode</button>
+      <button type="button" data-action="resync" onClick={() => run("background goal resync")}>resync</button>
+    </>
+  );
+}
+
+const rootElement = document.getElementById("root");
+if (!rootElement) throw new Error("missing root");
+const root = createRoot(rootElement);
+await act(async () => {
+  root.render(<ToastProvider><Probe /></ToastProvider>);
+});
+
+for (const action of ["stop", "mode", "resync"]) {
+  await act(async () => {
+    document.querySelector<HTMLButtonElement>(`[data-action="${action}"]`)?.click();
+    await flushPromises();
+  });
+}
+
+const errors = Array.from(document.querySelectorAll(".toast--error .toast__text")).map((node) => node.textContent);
+ok(errors.includes("stop goal bridge failed"), "rejected Stop Goal action shows an error toast");
+ok(errors.includes("switch mode bridge failed"), "rejected mode action shows an error toast");
+ok(errors.includes("background goal resync bridge failed"), "rejected background Goal resync shows an error toast");
+ok(unhandled.length === 0, "handled Goal action rejections do not emit unhandledrejection");
+
+const here = dirname(fileURLToPath(import.meta.url));
+const appSource = readFileSync(resolve(here, "../App.tsx"), "utf8");
+ok(
+  /runGoalAction\(\(\) => applyCollaborationMode\(collaborationMode === "plan" \? "normal" : "plan"\)\)/.test(appSource),
+  "mode shortcut routes through the rejection handler",
+);
+ok(
+  /runGoalAction\(async \(\) => \{[\s\S]{0,260}setControllerComposerProfileForTab\([\s\S]{0,260}propagateError: true/.test(appSource),
+  "background Goal resync routes through the rejection handler",
+);
+ok(appSource.includes("onClearGoal={clearGoalFromUi}"), "Composer Stop Goal routes through the rejection handler");
+ok(appSource.includes("onSetCollaborationMode={setCollaborationModeFromUi}"), "Composer mode changes route through the rejection handler");
+ok(/if \(model\) \{\s*await switchModel\(model\[1\]\);/.test(appSource), "/model awaits Goal restoration failures");
+ok(
+  /await \(trimmed \? setControllerGoalForTab\(tabId, trimmed\) : clearControllerGoalForTab\(tabId\)\);\s*patchActivatedGoalForTab\(tabId, trimmed\)/.test(appSource),
+  "failed Goal bridge calls cannot patch local Goal state or user intent",
+);
+
+await act(async () => {
+  root.unmount();
+});
+process.off("unhandledRejection", onUnhandledRejection);
+window.removeEventListener("unhandledrejection", onWindowUnhandledRejection);
+dom.window.close();
+
+console.log(`\n${passed} passed, ${failed} failed, ${passed + failed} total`);
+if (failed > 0) process.exit(1);