diff --git a/.github/pr-assets/260921-lane-d-consent-surface.png b/.github/pr-assets/260921-lane-d-consent-surface.png
new file mode 100644
index 00000000000..44a46139e4e
Binary files /dev/null and b/.github/pr-assets/260921-lane-d-consent-surface.png differ
diff --git a/.github/pr-assets/opencodex-cache-usage.png b/.github/pr-assets/opencodex-cache-usage.png
new file mode 100644
index 00000000000..6011c89b57f
Binary files /dev/null and b/.github/pr-assets/opencodex-cache-usage.png differ
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 003415f3af5..c7d1c5de8f3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -34,6 +34,8 @@ on:
       - "bin/**"
       - "tests/**"
       - "scripts/**"
+      - "app/**"
+      - "desktop/**"
       - "gui/**"
       - "assets/**"
       - ".gitattributes"
@@ -213,6 +215,8 @@ jobs:
               - 'bin/**'
               - 'tests/**'
               - 'scripts/**'
+              - 'app/**'
+              - 'desktop/**'
               - 'gui/**'
               - 'assets/**'
               - '.gitattributes'
@@ -1147,6 +1151,118 @@ jobs:
   # `if: always()` is load-bearing. Without it, a failed or skipped dependency
   # skips this job too — and GitHub reports a skipped job as success, so the gate
   # would go green precisely when something went wrong.
+  widget:
+    name: macos widget + bundle
+    needs: [changes, gates]
+    if: github.event_name != 'pull_request' || needs.changes.outputs.ci == 'true'
+    runs-on: macos-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: 1.3.14
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd desktop
+          bun install --frozen-lockfile
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@02cb101ec7c40f2c49e1d9714d64511d8e1b74de # master
+        with:
+          toolchain: stable
+
+      - name: Test MenuBarCore
+        run: bun run test:macos
+
+      - name: Build dashboard
+        run: bun run build:gui
+
+      - name: Prepare desktop sidecar
+        run: bun desktop/scripts/prepare-sidecar.ts
+
+      - name: Build WidgetKit appex
+        run: bash desktop/scripts/build-widget.sh
+
+      - name: Build unsigned desktop app
+        working-directory: desktop
+        # `createUpdaterArtifacts` is on and the updater public key is committed, so a plain
+        # `tauri build` stops with "A public key has been found, but no private key" unless
+        # TAURI_SIGNING_PRIVATE_KEY is set. This job proves the appex and the app bundle build
+        # and that the widget is embedded; it does not ship an update, and a verification
+        # build has no business holding the release key. Updater artifacts are therefore off
+        # here and the signing path stays in release.yml, which already reads the secret and
+        # refuses to publish a manifest when it is absent.
+        run: bunx tauri build --ci --bundles app --config '{"bundle":{"createUpdaterArtifacts":false}}'
+
+      - name: Verify WidgetKit appex and desktop app
+        run: |
+          app=desktop/src-tauri/target/release/bundle/macos/OpenCodex.app
+          # Tauri renames the main binary only when `mainBinaryName` is set, and this config
+          # does not set it, so the bundled executable keeps the Cargo bin name rather than
+          # the product name. Read the name the bundle itself declares instead of restating
+          # it here, so this check follows the config instead of drifting from it.
+          executable="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleExecutable' "$app/Contents/Info.plist")"
+          test -n "$executable"
+          test -x "$app/Contents/MacOS/$executable"
+          test -x "$app/Contents/PlugIns/OpenCodexWidget.appex/Contents/MacOS/OpenCodexWidget"
+          test -x "$app/Contents/MacOS/ocx"
+          codesign -dv "$app/Contents/PlugIns/OpenCodexWidget.appex"
+          # The widget is only offered in the gallery when its bundle is actually linked in, and
+          # nothing else here would notice its absence: the appex builds, signs and registers
+          # exactly the same way with the WidgetBundle dropped by the linker.
+          nm -a "$app/Contents/PlugIns/OpenCodexWidget.appex/Contents/MacOS/OpenCodexWidget" \
+            | grep -q "OpenCodexWidget0abC6BundleV" \
+            || { echo "::error::the widget bundle is not linked into the extension"; exit 1; }
+
+  desktop-shell:
+    name: desktop shell
+    needs: [changes, gates]
+    if: github.event_name != 'pull_request' || needs.changes.outputs.ci == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install Tauri Linux dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@02cb101ec7c40f2c49e1d9714d64511d8e1b74de # master
+        with:
+          toolchain: stable
+          components: rustfmt, clippy
+
+      - name: Prepare desktop check resources
+        run: |
+          set -euo pipefail
+          triple="$(rustc -vV | sed -n 's/^host: //p')"
+          mkdir -p desktop/src-tauri/binaries desktop/src-tauri/resources/gui/dist
+          : > "desktop/src-tauri/binaries/ocx-${triple}"
+          chmod +x "desktop/src-tauri/binaries/ocx-${triple}"
+          : > desktop/src-tauri/resources/gui/dist/.keep
+
+      - name: Check Rust formatting
+        run: cargo fmt --manifest-path desktop/src-tauri/Cargo.toml --check
+
+      - name: Run Rust clippy
+        run: cargo clippy --manifest-path desktop/src-tauri/Cargo.toml --all-targets -- -D warnings
+
+      - name: Run Rust tests
+        run: cargo test --manifest-path desktop/src-tauri/Cargo.toml
+
   ci:
     name: ci
     if: always()
@@ -1154,7 +1270,7 @@ jobs:
     # direct dependencies only, so a failing `select-windows-runner` would
     # otherwise reach this gate as nothing at all while its dependents report
     # `skipped`, which is the shape the step below is written to catch.
-    needs: [changes, select-windows-runner, test, storage-policy, api-usage, gates, platform-macos, macos-control, platform-windows, keyring-smoke, docker-smoke, docs-site-build, structure-gate, npm-global-smoke]
+    needs: [changes, select-windows-runner, test, storage-policy, api-usage, gates, platform-macos, macos-control, platform-windows, keyring-smoke, docker-smoke, docs-site-build, structure-gate, npm-global-smoke, widget, desktop-shell]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions:
@@ -1220,12 +1336,15 @@ jobs:
           GATED_JOBS="changes select-windows-runner test storage-policy api-usage gates"
           GATED_JOBS="$GATED_JOBS platform-macos keyring-smoke docker-smoke npm-global-smoke"
           GATED_JOBS="$GATED_JOBS macos-control platform-windows docs-site-build"
-          GATED_JOBS="$GATED_JOBS structure-gate"
+          GATED_JOBS="$GATED_JOBS structure-gate widget"
+          GATED_JOBS="$GATED_JOBS desktop-shell"
 
           expected_for() {
             case "$1" in
               changes|select-windows-runner) echo requested ;;
-              test|storage-policy|api-usage|gates|platform-macos|keyring-smoke|docker-smoke)
+              test|storage-policy|api-usage|gates|platform-macos|keyring-smoke|docker-smoke|widget)
+                echo "$scoped" ;;
+              desktop-shell)
                 echo "$scoped" ;;
               npm-global-smoke) echo "$packaging" ;;
               docs-site-build) echo "$docs" ;;
diff --git a/.github/workflows/desktop-installed-gate.yml b/.github/workflows/desktop-installed-gate.yml
new file mode 100644
index 00000000000..8782cd84623
--- /dev/null
+++ b/.github/workflows/desktop-installed-gate.yml
@@ -0,0 +1,277 @@
+name: desktop installed-artifact gate
+
+# D9 part two: install the real artifact on a machine per platform, launch it against a
+# staged npm runtime, and exercise the ownership contract — takeover, the gestures that
+# must leave the runtime alive, tray Quit draining an in-flight request, and on Linux
+# both update paths (R3). Runs only on maintainer-registered self-hosted GUI machines;
+# publication wiring into release.yml is a separate change.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Release version whose desktop artifacts the gate installs
+        required: true
+        type: string
+      from-version:
+        description: Older release used for the staged npm runtime and the Linux update phases
+        required: true
+        type: string
+      # Hook inputs are FILE NAMES, never command text. The runner's operator installs
+      # audited executables in a hooks directory (vars.OPENCODEX_GATE_HOOKS_DIR) and a
+      # dispatch picks among them by name; the gate executes the file directly, so this
+      # workflow can never become an arbitrary-shell surface on a persistent runner.
+      consent-hook:
+        description: Name of the runner hook that answers the takeover consent prompt
+        required: false
+        type: string
+      tray-click-hook:
+        description: Name of the runner hook that left-clicks the tray icon
+        required: false
+        type: string
+      tray-quit-hook:
+        description: Name of the runner hook that opens the tray menu and chooses Quit
+        required: false
+        type: string
+      tray-check-hook:
+        description: Name of the runner hook that chooses Check for Updates in the tray
+        required: false
+        type: string
+      tray-install-hook:
+        description: Name of the runner hook that chooses Install update in the tray
+        required: false
+        type: string
+      elevate-accept-hook:
+        description: Name of the runner hook that answers the deb update's elevation prompt (drives the accept path)
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: desktop-installed-gate-${{ inputs.version }}
+  cancel-in-progress: false
+
+jobs:
+  macos:
+    runs-on: [self-hosted, opencodex-gate-macos]
+    timeout-minutes: 60
+    # Required-review environment: no run reaches the GUI runner without a maintainer
+    # approval, and the checkout below pins the driver to the protected dev branch, so a
+    # dispatched ref cannot smuggle modified gate code onto the machine.
+    environment: opencodex-desktop-gate
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          ref: dev
+          persist-credentials: false
+
+      - name: Setup project Bun
+        uses: ./.github/actions/setup-project-bun
+
+      - name: Download the release artifact
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_VERSION: ${{ inputs.version }}
+          GATE_ARTIFACTS: ${{ runner.temp }}/gate-artifacts
+        run: |
+          mkdir -p "$GATE_ARTIFACTS"
+          gh release download "v${RELEASE_VERSION}" \
+            --pattern "OpenCodex-${RELEASE_VERSION}-macos.dmg" \
+            --dir "$GATE_ARTIFACTS" \
+            --clobber
+
+      - name: Run the installed-artifact gate
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+          FROM_VERSION: ${{ inputs.from-version }}
+          CONSENT_HOOK: ${{ inputs.consent-hook }}
+          TRAY_CLICK_HOOK: ${{ inputs.tray-click-hook }}
+          TRAY_QUIT_HOOK: ${{ inputs.tray-quit-hook }}
+          GATE_HOOKS_DIR: ${{ vars.OPENCODEX_GATE_HOOKS_DIR }}
+          GATE_ARTIFACTS: ${{ runner.temp }}/gate-artifacts
+          GATE_WORK: ${{ runner.temp }}/installed-gate
+          GATE_REPORT: ${{ runner.temp }}/installed-gate-report.json
+        run: |
+          set -euo pipefail
+          args=(
+            --platform macos --format dmg
+            --artifact "$GATE_ARTIFACTS/OpenCodex-${RELEASE_VERSION}-macos.dmg"
+            --work-dir "$GATE_WORK"
+            --to-version "$RELEASE_VERSION"
+            --from-version "$FROM_VERSION"
+            --report "$GATE_REPORT"
+          )
+          if [ -n "$GATE_HOOKS_DIR" ]; then args+=(--hooks-dir "$GATE_HOOKS_DIR"); fi
+          for pair in "consent-hook:CONSENT_HOOK" "tray-click-hook:TRAY_CLICK_HOOK" "tray-quit-hook:TRAY_QUIT_HOOK"; do
+            name="${pair%%:*}"; env_name="${pair##*:}"
+            value="${!env_name}"
+            if [ -n "$value" ]; then args+=("--${name}" "$value"); fi
+          done
+          bun desktop/scripts/installed-gate.ts "${args[@]}"
+
+      - name: Upload the gate report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: installed-gate-report-macos
+          path: ${{ runner.temp }}/installed-gate-report.json
+          if-no-files-found: error
+
+  windows:
+    runs-on: [self-hosted, opencodex-gate-windows]
+    timeout-minutes: 60
+    environment: opencodex-desktop-gate
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          ref: dev
+          persist-credentials: false
+
+      - name: Setup project Bun
+        uses: ./.github/actions/setup-project-bun
+
+      - name: Download the release artifact
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_VERSION: ${{ inputs.version }}
+          GATE_ARTIFACTS: ${{ runner.temp }}/gate-artifacts
+        run: |
+          mkdir -p "$GATE_ARTIFACTS"
+          gh release download "v${RELEASE_VERSION}" \
+            --pattern "OpenCodex-${RELEASE_VERSION}-windows-x64.msi" \
+            --dir "$GATE_ARTIFACTS" \
+            --clobber
+
+      - name: Run the installed-artifact gate
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+          FROM_VERSION: ${{ inputs.from-version }}
+          CONSENT_HOOK: ${{ inputs.consent-hook }}
+          TRAY_CLICK_HOOK: ${{ inputs.tray-click-hook }}
+          TRAY_QUIT_HOOK: ${{ inputs.tray-quit-hook }}
+          GATE_HOOKS_DIR: ${{ vars.OPENCODEX_GATE_HOOKS_DIR }}
+          GATE_ARTIFACTS: ${{ runner.temp }}/gate-artifacts
+          GATE_WORK: ${{ runner.temp }}/installed-gate
+          GATE_REPORT: ${{ runner.temp }}/installed-gate-report.json
+        run: |
+          set -euo pipefail
+          args=(
+            --platform windows --format msi
+            --artifact "$GATE_ARTIFACTS/OpenCodex-${RELEASE_VERSION}-windows-x64.msi"
+            --work-dir "$GATE_WORK"
+            --to-version "$RELEASE_VERSION"
+            --from-version "$FROM_VERSION"
+            --report "$GATE_REPORT"
+          )
+          if [ -n "$GATE_HOOKS_DIR" ]; then args+=(--hooks-dir "$GATE_HOOKS_DIR"); fi
+          for pair in "consent-hook:CONSENT_HOOK" "tray-click-hook:TRAY_CLICK_HOOK" "tray-quit-hook:TRAY_QUIT_HOOK"; do
+            name="${pair%%:*}"; env_name="${pair##*:}"
+            value="${!env_name}"
+            if [ -n "$value" ]; then args+=("--${name}" "$value"); fi
+          done
+          bun desktop/scripts/installed-gate.ts "${args[@]}"
+
+      - name: Upload the gate report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: installed-gate-report-windows
+          path: ${{ runner.temp }}/installed-gate-report.json
+          if-no-files-found: error
+
+  linux:
+    runs-on: [self-hosted, opencodex-gate-linux]
+    timeout-minutes: 60
+    environment: opencodex-desktop-gate
+    strategy:
+      fail-fast: false
+      matrix:
+        format: [deb, appimage]
+        include:
+          - format: deb
+            suffix: linux-amd64.deb
+          - format: appimage
+            suffix: linux-x86_64.AppImage
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          ref: dev
+          persist-credentials: false
+
+      - name: Setup project Bun
+        uses: ./.github/actions/setup-project-bun
+
+      - name: Download the release artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_VERSION: ${{ inputs.version }}
+          FROM_VERSION: ${{ inputs.from-version }}
+          ARTIFACT_SUFFIX: ${{ matrix.suffix }}
+          GATE_ARTIFACTS: ${{ runner.temp }}/gate-artifacts
+        run: |
+          mkdir -p "$GATE_ARTIFACTS"
+          gh release download "v${RELEASE_VERSION}" \
+            --pattern "OpenCodex-${RELEASE_VERSION}-${ARTIFACT_SUFFIX}" \
+            --dir "$GATE_ARTIFACTS" \
+            --clobber
+          gh release download "v${FROM_VERSION}" \
+            --pattern "OpenCodex-${FROM_VERSION}-${ARTIFACT_SUFFIX}" \
+            --dir "$GATE_ARTIFACTS" \
+            --clobber
+
+      - name: Run the installed-artifact gate
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+          FROM_VERSION: ${{ inputs.from-version }}
+          GATE_FORMAT: ${{ matrix.format }}
+          ARTIFACT_SUFFIX: ${{ matrix.suffix }}
+          CONSENT_HOOK: ${{ inputs.consent-hook }}
+          TRAY_CLICK_HOOK: ${{ inputs.tray-click-hook }}
+          TRAY_QUIT_HOOK: ${{ inputs.tray-quit-hook }}
+          TRAY_CHECK_HOOK: ${{ inputs.tray-check-hook }}
+          TRAY_INSTALL_HOOK: ${{ inputs.tray-install-hook }}
+          ELEVATE_ACCEPT_HOOK: ${{ inputs.elevate-accept-hook }}
+          GATE_HOOKS_DIR: ${{ vars.OPENCODEX_GATE_HOOKS_DIR }}
+          GATE_ARTIFACTS: ${{ runner.temp }}/gate-artifacts
+          GATE_WORK: ${{ runner.temp }}/installed-gate
+          GATE_REPORT: ${{ runner.temp }}/installed-gate-report.json
+        run: |
+          set -euo pipefail
+          args=(
+            --platform linux --format "$GATE_FORMAT"
+            --artifact "$GATE_ARTIFACTS/OpenCodex-${RELEASE_VERSION}-${ARTIFACT_SUFFIX}"
+            --older-artifact "$GATE_ARTIFACTS/OpenCodex-${FROM_VERSION}-${ARTIFACT_SUFFIX}"
+            --work-dir "$GATE_WORK"
+            --to-version "$RELEASE_VERSION"
+            --from-version "$FROM_VERSION"
+            --report "$GATE_REPORT"
+          )
+          if [ -n "$GATE_HOOKS_DIR" ]; then args+=(--hooks-dir "$GATE_HOOKS_DIR"); fi
+          for pair in "consent-hook:CONSENT_HOOK" "tray-click-hook:TRAY_CLICK_HOOK" "tray-quit-hook:TRAY_QUIT_HOOK" "tray-check-hook:TRAY_CHECK_HOOK" "tray-install-hook:TRAY_INSTALL_HOOK" "elevate-accept-hook:ELEVATE_ACCEPT_HOOK"; do
+            name="${pair%%:*}"; env_name="${pair##*:}"
+            value="${!env_name}"
+            if [ -n "$value" ]; then args+=("--${name}" "$value"); fi
+          done
+          bun desktop/scripts/installed-gate.ts "${args[@]}"
+
+      - name: Upload the gate report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: installed-gate-report-linux-${{ matrix.format }}
+          path: ${{ runner.temp }}/installed-gate-report.json
+          if-no-files-found: error
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7b565b68003..ace74775e84 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -24,6 +24,11 @@ on:
         required: false
         type: boolean
         default: true
+      resume-after-npm-publish:
+        description: "Operator attestation: a previous run of this workflow acknowledged npm publication for this exact commit; skip npm publish and complete the GitHub side"
+        required: false
+        type: boolean
+        default: false
       expected-sha:
         description: "Immutable release commit this dispatch must publish (fail if the branch moved)"
         required: true
@@ -69,8 +74,490 @@ jobs:
             process.exit(1);
           }
           NODE
-  publish:
+  package-standalone:
     needs: validate-dispatch
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: bun-linux-x64
+            smoke: true
+          - os: macos-latest
+            target: bun-darwin-arm64
+            smoke: true
+          - os: macos-latest
+            target: bun-darwin-x64
+            smoke: false
+          - os: windows-latest
+            target: bun-windows-x64
+            smoke: true
+          - os: ubuntu-latest
+            target: bun-linux-arm64
+            smoke: false
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project Bun
+        uses: ./.github/actions/setup-project-bun
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build dashboard
+        run: bun run build:gui
+
+      - name: Build standalone binary
+        run: bun run build:standalone --target ${{ matrix.target }}
+
+      - name: Smoke test standalone binary
+        if: matrix.smoke && runner.os != 'Windows'
+        shell: bash
+        run: |
+          set -euo pipefail
+          binary="dist/standalone/${{ matrix.target }}/ocx"
+          "$binary" --version
+          OPENCODEX_HOME="$RUNNER_TEMP/ocx-home" "$binary" start --port 10177 >"$RUNNER_TEMP/ocx.log" 2>&1 &
+          pid=$!
+          trap 'kill "$pid" 2>/dev/null || true' EXIT
+          for _ in $(seq 1 30); do curl -fsS http://127.0.0.1:10177/healthz && break || sleep 1; done
+          curl -fsS http://127.0.0.1:10177/healthz
+          test "$(curl -sS -o /dev/null -w '%{http_code}' http://127.0.0.1:10177/)" = 200
+
+      - name: Smoke test standalone binary (Windows)
+        if: matrix.smoke && runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $binary = "dist/standalone/${{ matrix.target }}/ocx.exe"
+          & $binary --version
+          $env:OPENCODEX_HOME = Join-Path $env:RUNNER_TEMP "ocx-home"
+          $process = Start-Process -FilePath $binary -ArgumentList "start", "--port", "10177" -PassThru
+          try {
+            for ($i = 0; $i -lt 30; $i++) {
+              try { Invoke-WebRequest -UseBasicParsing http://127.0.0.1:10177/healthz | Out-Null; break } catch { Start-Sleep -Seconds 1 }
+            }
+            Invoke-WebRequest -UseBasicParsing http://127.0.0.1:10177/healthz | Select-Object -ExpandProperty Content
+            Invoke-WebRequest -UseBasicParsing http://127.0.0.1:10177/ | Out-Null
+          } finally { Stop-Process -Id $process.Id -Force -ErrorAction SilentlyContinue }
+
+      - name: Archive standalone release
+        shell: bash
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+          STANDALONE_TARGET: ${{ matrix.target }}
+        run: |
+          set -euo pipefail
+          cd "dist/standalone/$STANDALONE_TARGET"
+          if [[ "$RUNNER_OS" == "Windows" ]]; then
+            powershell -NoProfile -Command 'Compress-Archive -Path ocx.exe,gui -DestinationPath ("../../ocx-{0}-{1}.zip" -f $env:RELEASE_VERSION,$env:STANDALONE_TARGET) -Force'
+          else
+            tar -czf "../../ocx-${RELEASE_VERSION}-${STANDALONE_TARGET}.tar.gz" ocx gui
+          fi
+          cd ../..
+          # The pre-publication verifier resolves every recorded checksum from
+          # dist/release, where the artifact download lands these files flat; the
+          # checksum therefore records the bare file name, which sha256sum takes
+          # verbatim from its argument.
+          if [[ "$RUNNER_OS" == "Windows" ]]; then sha256sum "ocx-${RELEASE_VERSION}-${STANDALONE_TARGET}.zip" > "ocx-${RELEASE_VERSION}-${STANDALONE_TARGET}.sha256"
+          else sha256sum "ocx-${RELEASE_VERSION}-${STANDALONE_TARGET}.tar.gz" > "ocx-${RELEASE_VERSION}-${STANDALONE_TARGET}.sha256"
+          fi
+
+      - name: Upload standalone release
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: standalone-${{ matrix.target }}
+          path: |
+            dist/ocx-*.tar.gz
+            dist/ocx-*.zip
+            dist/ocx-*.sha256
+          if-no-files-found: error
+          retention-days: 7
+
+  package-desktop:
+    needs: validate-dispatch
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-latest
+            target: universal-apple-darwin
+            bundles: app,dmg
+            sidecar-targets: macos
+            artifact-suffixes: macos.dmg,macos.app.tar.gz
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+            bundles: msi
+            sidecar-targets: x86_64-pc-windows-msvc
+            artifact-suffixes: windows-x64.msi
+          - os: ubuntu-22.04
+            target: x86_64-unknown-linux-gnu
+            bundles: appimage,deb
+            sidecar-targets: x86_64-unknown-linux-gnu
+            artifact-suffixes: linux-x86_64.AppImage,linux-amd64.deb
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 45
+    permissions:
+      contents: read
+    env:
+      # Whether this run holds the Developer ID material at all. A run without it still builds
+      # locally useful bundles; a run with it must not silently downgrade any part of the app.
+      DESKTOP_SIGNING_CONFIGURED: ${{ secrets.APPLE_CERTIFICATE != '' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project Bun
+        uses: ./.github/actions/setup-project-bun
+
+      - name: Install project dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build dashboard
+        run: bun run build:gui
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@02cb101ec7c40f2c49e1d9714d64511d8e1b74de # master
+        with:
+          toolchain: stable
+
+      - name: Install Linux desktop dependencies
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libssl-dev
+
+      - name: Install desktop dependencies
+        working-directory: desktop
+        run: bun install --frozen-lockfile
+
+      - name: Prepare macOS sidecars
+        if: runner.os == 'macOS'
+        run: |
+          bun desktop/scripts/prepare-sidecar.ts --target aarch64-apple-darwin
+          bun desktop/scripts/prepare-sidecar.ts --target x86_64-apple-darwin
+
+      - name: Prepare sidecar
+        if: runner.os != 'macOS'
+        run: bun desktop/scripts/prepare-sidecar.ts --target ${{ matrix.sidecar-targets }}
+
+      # The signing certificate has to be in a keychain before the widget is signed, and the
+      # Tauri build step creates its own keychain only when it runs — which is after this. Until
+      # this step existed, build-widget.sh saw no MACOS_SIGN_IDENTITY and took its unsigned
+      # branch, and the bundler does not re-sign anything under PlugIns, so the extension would
+      # have gone out ad-hoc inside a Developer ID host. No release has published a macOS
+      # application yet, so this is a defect that had not reached anyone rather than one that had.
+      - name: Import the release signing certificate
+        if: runner.os == 'macOS'
+        env:
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          DRY_RUN: ${{ inputs.dry-run }}
+        run: |
+          set -euo pipefail
+          # Checked as a set, because a partial set is the dangerous case: the Tauri CLI skips
+          # notarization without failing when the notary credentials are missing, and the
+          # unnotarized artifact is uploaded and attached exactly as a good one would be.
+          missing=""
+          for name in APPLE_CERTIFICATE APPLE_CERTIFICATE_PASSWORD APPLE_ID APPLE_PASSWORD APPLE_TEAM_ID; do
+            eval "value=\${$name:-}"
+            [ -n "$value" ] || missing="$missing $name"
+          done
+          if [ -n "$missing" ]; then
+            if [ "${DRY_RUN}" != "true" ]; then
+              echo "::error::A real release needs the full signing and notarization credential set."
+              echo "::error::Missing:$missing"
+              exit 1
+            fi
+            echo "Signing credentials are incomplete, so this build stays ad-hoc signed:$missing"
+            echo "It is usable for local validation and is not a release asset."
+            exit 0
+          fi
+          keychain="$RUNNER_TEMP/opencodex-signing.keychain-db"
+          # Recorded before anything is created, so the cleanup step can still find a keychain
+          # that a failure left half-built.
+          echo "OPENCODEX_SIGNING_KEYCHAIN=$keychain" >> "$GITHUB_ENV"
+          keychain_password="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
+          certificate="$RUNNER_TEMP/opencodex-signing.p12"
+          # The decoded certificate must not outlive this step even when a later command fails.
+          trap 'shred -u "$certificate" 2>/dev/null || rm -Pf "$certificate" 2>/dev/null || true' EXIT
+          printf '%s' "$APPLE_CERTIFICATE" | base64 --decode > "$certificate"
+          security create-keychain -p "$keychain_password" "$keychain"
+          security set-keychain-settings -lut 21600 "$keychain"
+          security unlock-keychain -p "$keychain_password" "$keychain"
+          security import "$certificate" -k "$keychain" -P "$APPLE_CERTIFICATE_PASSWORD" \
+            -T /usr/bin/codesign
+          security set-key-partition-list -S apple-tool:,apple:,codesign: \
+            -s -k "$keychain_password" "$keychain" > /dev/null
+          # shellcheck disable=SC2046 # the keychain list is intentionally word-split into arguments
+          security list-keychain -d user -s "$keychain" $(security list-keychains -d user | tr -d '"')
+
+      - name: Build WidgetKit extension
+        if: runner.os == 'macOS'
+        env:
+          MACOS_SIGN_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+          # A run holding Developer ID material must not produce an ad-hoc widget. Without this
+          # the script's ad-hoc branch is the silent default, which is how a signed, notarized
+          # app shipped with an extension macOS will not register.
+          WIDGET_SIGN_REQUIRED: ${{ env.DESKTOP_SIGNING_CONFIGURED == 'true' && '1' || '0' }}
+        run: bash desktop/scripts/build-widget.sh
+
+      - name: Verify the extension carries the release signature
+        if: runner.os == 'macOS'
+        env:
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          DRY_RUN: ${{ inputs.dry-run }}
+        run: |
+          set -euo pipefail
+          appex=desktop/src-tauri/widget/OpenCodexWidget.appex
+          if [ -z "${APPLE_TEAM_ID}" ]; then
+            if [ "${DRY_RUN}" != "true" ]; then
+              echo "::error::A real release cannot assert its own signature without APPLE_TEAM_ID."
+              exit 1
+            fi
+            echo "No team configured; skipping the signature assertion for this non-release build."
+            exit 0
+          fi
+          codesign --verify --strict --deep "$appex"
+          description="$(codesign -dvvv "$appex" 2>&1)"
+          echo "$description"
+          echo "$description" | grep -q "TeamIdentifier=$APPLE_TEAM_ID"
+          echo "$description" | grep -q "flags=.*runtime"
+          echo "$description" | grep -q "Timestamp="
+
+      # Release signing is intentionally secret-gated. Developer ID, notarization,
+      # and updater signatures require maintainer-owned credentials; builds without
+      # those secrets remain useful for local validation but are not release assets.
+      - name: Build desktop bundles
+        working-directory: desktop
+        env:
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          MACOS_SIGN_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+        run: bunx tauri build --ci --target ${{ matrix.target }} --bundles ${{ matrix.bundles }}
+
+      - name: Rename release assets
+        shell: bash
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+          DESKTOP_TARGET: ${{ matrix.target }}
+        run: |
+          bun desktop/scripts/collect-release-assets.ts \
+            --version "$RELEASE_VERSION" \
+            --target "$DESKTOP_TARGET" \
+            --out dist/release
+
+      # After the bundle exists, not before: a sweep that runs first passes by finding nothing.
+      - name: Verify every Mach-O in the bundle carries the release identity
+        if: runner.os == 'macOS'
+        env:
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          DRY_RUN: ${{ inputs.dry-run }}
+        run: |
+          set -euo pipefail
+          if [ -z "${APPLE_TEAM_ID}" ]; then
+            if [ "${DRY_RUN}" != "true" ]; then
+              echo "::error::A real release cannot verify its bundle without APPLE_TEAM_ID."
+              exit 1
+            fi
+            echo "No team configured; skipping the bundle-wide assertion for this local build."
+            exit 0
+          fi
+          # Executables are found by their magic bytes rather than by path or extension. A bundler
+          # signs what it placed; anything copied in afterwards is invisible to it, and the
+          # binaries that get missed are the ones with no extension to filter on.
+          apps=0
+          machos=0
+          bad=0
+          while IFS= read -r app; do
+            apps=$((apps + 1))
+            echo "checking $app"
+            while IFS= read -r -d '' file; do
+              # All eight Mach-O leading words: thin and fat, 32- and 64-bit, both byte orders.
+              # A list that covers only the common ones skips the rest in silence while the
+              # non-zero counter below still reports a healthy sweep.
+              case "$(head -c 4 "$file" | xxd -p)" in
+                cefaedfe|cffaedfe|feedface|feedfacf) ;;
+                cafebabe|bebafeca|cafebabf|bfbafeca) ;;
+                *) continue ;;
+              esac
+              machos=$((machos + 1))
+              if ! codesign -dvvv "$file" 2>&1 | grep -q "TeamIdentifier=$APPLE_TEAM_ID"; then
+                echo "::error::$file is not signed with the release identity"
+                bad=1
+              fi
+            done < <(find "$app" -type f -print0)
+          done < <(find desktop/src-tauri/target -maxdepth 6 -type d -name '*.app')
+          echo "inspected $machos Mach-O files across $apps app bundles"
+          # A sweep that inspected nothing is the failure mode this step exists to prevent.
+          if [ "$apps" -eq 0 ] || [ "$machos" -eq 0 ]; then
+            echo "::error::found $apps app bundles and $machos Mach-O files; the sweep inspected nothing"
+            exit 1
+          fi
+          exit "$bad"
+
+      - name: Upload desktop release
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: desktop-${{ matrix.target }}
+          path: dist/release/
+          if-no-files-found: error
+          retention-days: 7
+
+      # always(), because a keychain holding the release identity must not survive a failed job
+      # on a runner image that could be reused.
+      - name: Remove the signing keychain
+        if: always() && runner.os == 'macOS'
+        run: |
+          if [ -n "${OPENCODEX_SIGNING_KEYCHAIN:-}" ] && [ -f "${OPENCODEX_SIGNING_KEYCHAIN}" ]; then
+            security delete-keychain "${OPENCODEX_SIGNING_KEYCHAIN}"
+          fi
+
+  # Pre-publication verification. Everything that will be published is checked
+  # here — expected platform set, every checksum, the updater signatures, and the
+  # manifest parse-back — and publication consumes this result rather than
+  # verifying after the fact. Runs on dry-run too: a dry run must prove the same
+  # chain a real release will rely on.
+  verify-release:
+    runs-on: ubuntu-latest
+    needs: [validate-dispatch, package-standalone, package-desktop]
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    env:
+      UPDATER_SIGNING_CONFIGURED: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY != '' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project Bun
+        uses: ./.github/actions/setup-project-bun
+
+      - name: Download standalone packaged assets
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: standalone-*
+          merge-multiple: true
+          path: dist/release
+
+      - name: Download desktop packaged assets
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: desktop-*
+          merge-multiple: true
+          path: dist/release
+
+      - name: Verify release assets
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+          args=(
+            --version "$RELEASE_VERSION"
+            --dir dist/release
+            --repo "$GITHUB_REPOSITORY"
+            --sha "$GITHUB_SHA"
+            --receipt-out verification/receipt.json
+          )
+          # Signatures are verified whenever they exist; the manifest is only
+          # generated when this run holds the updater key, exactly as before.
+          if [ "$UPDATER_SIGNING_CONFIGURED" = "true" ]; then
+            args+=(--manifest-out dist/release/latest.json --require-signatures)
+          fi
+          bun desktop/scripts/verify-release-assets.ts "${args[@]}"
+
+      - name: Upload verified release bundle
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: verified-release
+          path: dist/release/
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Upload verification receipt
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-verification-receipt
+          path: verification/receipt.json
+          if-no-files-found: error
+          retention-days: 7
+
+  attach-release:
+    runs-on: ubuntu-latest
+    needs: [publish, verify-release]
+    if: ${{ inputs.dry-run != true }}
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project Bun
+        uses: ./.github/actions/setup-project-bun
+
+      - name: Download the verified release bundle
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: verified-release
+          path: dist/release
+
+      - name: Download the verification receipt
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-verification-receipt
+          path: verification
+
+      # The bundle is attached exactly as verified: the receipt must name this
+      # run's version and commit, or nothing uploads.
+      - name: Require the verification receipt for this commit
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+          receipt_version="$(bun -e 'console.log(JSON.parse(await Bun.file("verification/receipt.json").text()).version)')"
+          receipt_sha="$(bun -e 'console.log(JSON.parse(await Bun.file("verification/receipt.json").text()).sha)')"
+          test "$receipt_version" = "$RELEASE_VERSION" || {
+            echo "::error::verification receipt names version $receipt_version, not $RELEASE_VERSION"
+            exit 1
+          }
+          test "$receipt_sha" = "$GITHUB_SHA" || {
+            echo "::error::verification receipt names commit $receipt_sha, not $GITHUB_SHA"
+            exit 1
+          }
+
+      - name: Attach to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          # Workflow inputs reach shell code through env, never by interpolation into
+          # run: source. tests/ci-workflows.test.ts enforces this repo-wide.
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          gh release upload "v${RELEASE_VERSION}" dist/release/* --clobber
+
+  publish:
+    needs: [validate-dispatch, verify-release]
     runs-on: ubuntu-latest
     timeout-minutes: 15
     permissions:
@@ -221,8 +708,10 @@ jobs:
           fi
 
           # Keep in sync with the service-lifecycle.yml trigger paths. src/cli.ts is
-          # the pre-restructure compat stub that durable launchers still execute.
-          if printf '%s\n' "$changed_files" | grep -Eq '^(src/service\.ts|src/cli\.ts|src/cli/index\.ts|src/lib/bun-runtime\.ts|package\.json|bun\.lock|\.github/workflows/service-lifecycle\.yml|\.github/workflows/release\.yml)$'; then
+          # the pre-restructure compat stub that durable launchers still execute; the
+          # service implementation itself is the src/service/ directory, and the desktop
+          # shell packages and launches it.
+          if printf '%s\n' "$changed_files" | grep -Eq '^(src/service\.ts|src/service/.*|desktop/.*|src/cli\.ts|src/cli/index\.ts|src/lib/bun-runtime\.ts|package\.json|bun\.lock|\.github/workflows/service-lifecycle\.yml|\.github/workflows/release\.yml)$'; then
             service_url="$(
               gh run list \
                 --workflow service-lifecycle.yml \
@@ -259,6 +748,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           RELEASE_VERSION: ${{ inputs.version }}
           DRY_RUN: ${{ inputs.dry-run }}
+          RESUME: ${{ inputs.resume-after-npm-publish }}
         run: |
           set -euo pipefail
 
@@ -275,7 +765,9 @@ jobs:
           fi
 
           if [ -n "$existing_tag_sha" ]; then
-            if [ "$dry_run" = "true" ]; then
+            if [ "$RESUME" = "true" ]; then
+              echo "::notice::${release_tag} already exists at this commit; resuming"
+            elif [ "$dry_run" = "true" ]; then
               echo "::notice::${release_tag} already exists at this commit; dry-run only"
             else
               echo "::error::${release_tag} already exists. Refusing to publish a version with pre-existing Git metadata."
@@ -284,7 +776,9 @@ jobs:
           fi
 
           if gh release view "$release_tag" >/dev/null 2>&1; then
-            if [ "$dry_run" = "true" ]; then
+            if [ "$RESUME" = "true" ]; then
+              echo "::notice::GitHub Release ${release_tag} already exists; resuming to complete the attachment"
+            elif [ "$dry_run" = "true" ]; then
               echo "::notice::GitHub Release ${release_tag} already exists; dry-run only"
             else
               echo "::error::GitHub Release ${release_tag} already exists. Choose the next unused patch version."
@@ -292,24 +786,36 @@ jobs:
             fi
           fi
 
+          if [ "$RESUME" = "true" ] && [ "$dry_run" = "true" ]; then
+            echo "::error::resume-after-npm-publish is a real-publication recovery path and cannot combine with dry-run"
+            exit 1
+          fi
           if npm view "${pkg_name}@${RELEASE_VERSION}" version >/dev/null 2>&1; then
-            if [ "$dry_run" = "true" ]; then
+            if [ "$RESUME" = "true" ]; then
+              echo "::notice::${pkg_name}@${RELEASE_VERSION} is acknowledged on npm; resuming after the recorded partial publication"
+            elif [ "$dry_run" = "true" ]; then
               echo "::notice::${pkg_name}@${RELEASE_VERSION} already exists on npm; dry-run only"
             else
-              echo "::error::${pkg_name}@${RELEASE_VERSION} already exists on npm. Choose the next unused patch version."
+              echo "::error::${pkg_name}@${RELEASE_VERSION} already exists on npm. If a previous run acknowledged this publication and failed afterwards, re-dispatch with resume-after-npm-publish: true; otherwise choose the next unused patch version."
               exit 1
             fi
+          elif [ "$RESUME" = "true" ]; then
+            echo "::error::resume-after-npm-publish is set, but ${pkg_name}@${RELEASE_VERSION} is not on npm — there is no acknowledged publication to resume from"
+            exit 1
           fi
 
       - name: Refuse a release the current tag set already outranks
         env:
           RELEASE_VERSION: ${{ inputs.version }}
           DRY_RUN: ${{ inputs.dry-run }}
+          RESUME: ${{ inputs.resume-after-npm-publish }}
         run: |
           set -euo pipefail
           allow=""
           existing_tag_sha="$(git rev-parse -q --verify "refs/tags/v${RELEASE_VERSION}^{commit}" || true)"
-          if [ "$DRY_RUN" = "true" ] && [ -n "$existing_tag_sha" ] && [ "$existing_tag_sha" = "$GITHUB_SHA" ]; then
+          # Dry-run re-dispatches and the resume path both legitimately find the tag
+          # already at this commit; a moved tag is still refused above.
+          if { [ "$DRY_RUN" = "true" ] || [ "$RESUME" = "true" ]; } && [ -n "$existing_tag_sha" ] && [ "$existing_tag_sha" = "$GITHUB_SHA" ]; then
             allow="--allow-existing-tag-at-head"
           fi
           git tag --list 'v*' | bun scripts/version-line.ts assert-releasable "$RELEASE_VERSION" $allow
@@ -338,15 +844,25 @@ jobs:
         env:
           DRY_RUN: ${{ inputs.dry-run }}
           NPM_DIST_TAG: ${{ inputs.tag }}
+          RESUME: ${{ inputs.resume-after-npm-publish }}
+          RELEASE_VERSION: ${{ inputs.version }}
         run: |
           set -euo pipefail
-          if [ "$DRY_RUN" = "true" ]; then
+          pkg_name="$(node -p "require('./package.json').name")"
+          if [ "$RESUME" = "true" ]; then
+            # npm publication was acknowledged by the earlier run and confirmed by the
+            # preflight above; completing the GitHub side must never republish.
+            echo "::notice::RESUME — npm publish skipped; publication already acknowledged"
+            echo "published=true" >> "$GITHUB_OUTPUT"
+            echo "Publication resumed for ${pkg_name}@${RELEASE_VERSION} at ${GITHUB_SHA} (npm publish skipped; acknowledged by the earlier run)." >> "$GITHUB_STEP_SUMMARY"
+          elif [ "$DRY_RUN" = "true" ]; then
             echo "::notice::DRY RUN — building + packing, not publishing"
             npm run prepublishOnly
             npm pack --dry-run
           else
             npm publish --tag "$NPM_DIST_TAG" --access public
             echo "published=true" >> "$GITHUB_OUTPUT"
+            echo "Publication acknowledged for ${pkg_name}@${RELEASE_VERSION} at ${GITHUB_SHA}. If any later step in this run fails, re-dispatch with the same version and expected-sha plus resume-after-npm-publish: true — never republish this version." >> "$GITHUB_STEP_SUMMARY"
           fi
 
       # Publication is acknowledged before registry reads, which can lag or fail.
@@ -388,6 +904,7 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           RELEASE_VERSION: ${{ inputs.version }}
+          RESUME: ${{ inputs.resume-after-npm-publish }}
         run: |
           set -euo pipefail
 
@@ -416,5 +933,18 @@ jobs:
             git push origin "refs/tags/${release_tag}"
           fi
 
-          gh release create "$release_tag" --target "$GITHUB_SHA" --title "$release_tag" \
-            --notes-file "$notes_file" ${prerelease_flag:+$prerelease_flag}
+          # Idempotent only for the resume path: a previous run may already have
+          # created the release and then failed before the assets were attached.
+          # Outside resume, finding a release here means the preflight was bypassed
+          # or the release appeared mid-run, and that stays a hard failure.
+          if gh release view "$release_tag" >/dev/null 2>&1; then
+            if [ "$RESUME" = "true" ]; then
+              echo "::notice::GitHub Release ${release_tag} already exists; reusing it for attachment"
+            else
+              echo "::error::GitHub Release ${release_tag} already exists; refusing to reuse it outside the resume path"
+              exit 1
+            fi
+          else
+            gh release create "$release_tag" --target "$GITHUB_SHA" --title "$release_tag" \
+              --notes-file "$notes_file" ${prerelease_flag:+$prerelease_flag}
+          fi
diff --git a/.github/workflows/service-lifecycle.yml b/.github/workflows/service-lifecycle.yml
index df37f605618..af6d3f34504 100644
--- a/.github/workflows/service-lifecycle.yml
+++ b/.github/workflows/service-lifecycle.yml
@@ -5,6 +5,11 @@ on:
     branches: [main, dev]
     paths:
       - "src/service.ts"
+      # The service implementation is the src/service/ directory; src/service.ts is only
+      # the pre-restructure compat facade. The desktop shell packages and launches the
+      # service, so its changes carry lifecycle evidence too.
+      - "src/service/**"
+      - "desktop/**"
       # Keep in sync with the release.yml service-gate regex (release.yml "Require
       # successful Cross-platform CI" step). src/cli.ts is the pre-restructure compat
       # stub that durable launchers still execute.
@@ -22,6 +27,9 @@ on:
     paths:
       - "src/service.ts"
       # Keep in sync with the release.yml service-gate regex (see above).
+      - "src/service/**"
+      - "desktop/**"
+      # Keep in sync with the release.yml service-gate regex (see above).
       - "src/cli.ts"
       - "src/cli/index.ts"
       - "src/lib/bun-runtime.ts"
diff --git a/.gitignore b/.gitignore
index 1973231f05b..3aa3ff0c143 100644
--- a/.gitignore
+++ b/.gitignore
@@ -70,3 +70,15 @@ go/
 
 # Rust native helpers keep their reproducible sources and lockfile in git, never local artifacts.
 native/**/target/
+dist/macos/
+dist/release/
+desktop/src-tauri/binaries/
+desktop/src-tauri/resources/
+desktop/src-tauri/widget/
+desktop/src-tauri/gen/
+desktop/src-tauri/target/
+# Running `bun install` inside desktop/ writes a second lockfile that shadows the root one for
+# any command run from that directory. CI installs the desktop workspace with --frozen-lockfile
+# on an older Bun, so a shadowing lockfile written by a newer Bun fails the job with "Unknown
+# lockfile version" before anything is built. The root lockfile is the only one this repo keeps.
+desktop/bun.lock
diff --git a/AGENTS.md b/AGENTS.md
index 1f621b99b41..5fc447e7c3c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,6 +27,10 @@ Bun-native TypeScript with no separate server compile step.
   seeds in `layout.json` place a conventionally named file until then.
   History: `devlog/_fin/260905_test_modularization_and_windows/`.
 - `gui/` — React + Vite dashboard; packaged output is served from `gui/dist`.
+- `app/` — native macOS WidgetKit extension bundled into the Tauri desktop app;
+  `MenuBarCore` is its snapshot model/formatting layer. Its tests are
+  executables, not XCTest bundles — Command Line Tools ships neither a usable
+  XCTest module nor the swift-testing runtime.
 - `docs-site/` — public docs (Astro + Starlight), deployed to GitHub Pages.
 - `go/` — retired Go native-runtime experiment; kept only where the TypeScript
   runtime still references it. New work does not go here.
@@ -41,6 +45,7 @@ Bun-native TypeScript with no separate server compile step.
   gone, and on a new `src/` area nobody claimed.
 - `scripts/` — release and maintenance tooling; `scripts/release.ts` is the
   release authority.
+- `desktop/` — Tauri v2 desktop shell, bootstrap UI, and compiled proxy sidecar preparation.
 - `devlog/` — planning and investigation notes, tracked in this repository. See
   "The `devlog` directory" below for what may and may not go there.
 
diff --git a/AGENTS_INSTALL.md b/AGENTS_INSTALL.md
index 05278f37cb9..50d5f8554e0 100644
--- a/AGENTS_INSTALL.md
+++ b/AGENTS_INSTALL.md
@@ -52,6 +52,70 @@ The following instructions concern **starring the repository on GitHub**.
   the matter permanently — do not argue it, re-frame it, or raise it again
   later.
 
+## Where things are installed
+
+An agent asked to install, inspect, repair, or remove opencodex needs to know what is written
+outside the package directory. Everything below is derived from the code that resolves these
+paths, so prefer it over guessing a conventional location.
+
+### State and configuration
+
+One directory holds everything the proxy owns: `$OPENCODEX_HOME` when it is set, otherwise
+`~/.opencodex`. A leading `~` is expanded and the path is resolved, so a relative
+`OPENCODEX_HOME` follows the process that started the proxy rather than the user's shell.
+
+| Path | What it is |
+|---|---|
+| `<home>/config.json` | providers, models, accounts, routing — the file `ocx init` writes |
+| `<home>/admin-api-token` | the management API token the server writes at startup |
+| `<home>/service.log` | stdout and stderr of the installed background service |
+| `<home>/service-state.json` | which manager installed the service, and on which port |
+| `<home>/winsw/` | the native Windows service binary and its XML, when `--native` was used |
+
+Two instances must not share a home: the spend ledger takes a single-writer lock and the second
+process is refused, so an independent instance needs its own `OPENCODEX_HOME`.
+
+### Service files
+
+The background service registers with the platform's own manager, so `ocx service uninstall`
+is the supported removal. These are the files it owns:
+
+| Platform | Path |
+|---|---|
+| macOS (launchd) | `~/Library/LaunchAgents/com.opencodex.proxy.plist` |
+| Linux (systemd user unit) | `~/.config/systemd/user/opencodex-proxy.service` |
+| Windows (Task Scheduler) | a scheduled task named `opencodex-proxy`, with no file of its own |
+| Windows (`--native`, WinSW) | `<home>/winsw/` beside the task, never both at once |
+
+A host that has both a Task Scheduler entry and a WinSW service is in a conflicting state;
+`ocx service status` reports it and the repair is to uninstall before reinstalling one of them.
+
+### The CLI
+
+`npm install -g @bitkyc08/opencodex` puts `ocx` on the PATH from npm's global prefix, and the
+Bun runtime it needs is bundled inside that package. There is no separate runtime to install and
+no WSL layer on Windows.
+
+### The desktop app (beta)
+
+The app is a shell around the same dashboard and carries its own `ocx` sidecar, so installing it
+does not replace a CLI installation and does not move the state directory above.
+
+| Platform | Installed at |
+|---|---|
+| macOS | `/Applications/OpenCodex.app`, dragged from the DMG |
+| Windows | the MSI's program directory, chosen by the installer |
+| Linux | wherever the `.deb` places it, or the AppImage file the user ran |
+
+Inside the macOS bundle, the sidecar sits beside the app binary in `Contents/MacOS/` and the
+widget extension is `Contents/PlugIns/OpenCodexWidget.appex`. Removing the app removes both;
+it does not remove `~/.opencodex`, and it does not stop a service installed by the CLI.
+
+Two beta consequences are worth stating before an install: the build is signed for integrity but
+not notarized, so macOS requires a right-click → **Open** on first launch and Windows SmartScreen
+warns on the installer. Neither is a failure to route around by disabling a security setting on
+the user's behalf — relay it and let the user decide.
+
 ## Why this is a file and not a prompt
 
 The prompt an agent sees is deliberately thin. Printing the full rule on every
diff --git a/README.md b/README.md
index d29cd2f43af..ec64c3de89d 100644
--- a/README.md
+++ b/README.md
@@ -90,7 +90,34 @@ Use `ocx service` to run it in the background.
 Open **http://localhost:10100** and configure everything in the web dashboard — add providers
 (40+ built-ins, or any OpenAI-compatible endpoint), pick models, manage accounts. `ocx gui`
 re-opens the dashboard at any time.
-It can also manage a **ChatGPT account pool** for Codex auth. Add multiple ChatGPT / Codex accounts,
+
+<details>
+<summary><b>Desktop app and macOS widget — beta</b></summary>
+
+A native shell around the same dashboard, plus a WidgetKit extension that shows proxy status,
+today's usage and provider quotas without opening a browser. The proxy is unchanged: the app
+finds a running one or starts the bundled `ocx` sidecar, and the dashboard stays at
+**http://localhost:10100**.
+
+It is beta. Builds are signed for integrity but not notarized, so macOS asks for a
+right-click → **Open** on first launch and Windows SmartScreen warns on the installer. The
+widget needs macOS 14 or newer; the snapshot model it renders lives in [`app/`](./app)
+(`MenuBarCore`).
+
+Download it from the [latest release](https://github.com/lidge-jun/opencodex/releases), or build
+it locally with `bun run prepare-sidecar && bun run prepare-widget && bunx tauri build`.
+
+Install locations, service files and everything else written to disk are listed in
+[`AGENTS_INSTALL.md`](./AGENTS_INSTALL.md#where-things-are-installed). The
+[Desktop App guide](https://lidge-jun.github.io/opencodex/guides/desktop-app/) and the
+[macOS Menu Bar App guide](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/) cover
+per-platform installation and the Gatekeeper prompt.
+
+</details>
+
+### ChatGPT account pool
+
+opencodex can also manage a **ChatGPT account pool** for Codex auth. Add multiple ChatGPT / Codex accounts,
 refresh their 5h / weekly / 30d quota in the dashboard. Under quota routing, new sessions can use
 the lowest-usage healthy account; round-robin and fill-first use their own policies. Existing Codex
 threads normally retain affinity to the account that started them, so long SSH, tmux, or
diff --git a/app/.gitignore b/app/.gitignore
new file mode 100644
index 00000000000..4629e801bfa
--- /dev/null
+++ b/app/.gitignore
@@ -0,0 +1,4 @@
+.build/
+.swiftpm/
+*.xcodeproj
+DerivedData/
diff --git a/app/Package.swift b/app/Package.swift
new file mode 100644
index 00000000000..a741d5bfd12
--- /dev/null
+++ b/app/Package.swift
@@ -0,0 +1,57 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "OpenCodexWidget",
+    platforms: [.macOS(.v14)],
+    products: [
+        .executable(name: "OpenCodexWidget", targets: ["OpenCodexWidget"]),
+        .executable(name: "MenuBarCoreTests", targets: ["MenuBarCoreTests"]),
+    ],
+    targets: [
+        .target(name: "MenuBarCore", path: "Sources/MenuBarCore"),
+        .executableTarget(
+            name: "OpenCodexWidget",
+            dependencies: ["MenuBarCore"],
+            path: "Sources/OpenCodexWidget",
+            swiftSettings: [
+                // Xcode sets APPLICATION_EXTENSION_API_ONLY on an app-extension target, and the
+                // two projects that have this working from SwiftPM pass its compiler spelling by
+                // hand. It restricts the target to the extension-safe API surface, which is the
+                // contract the extension host assumes it was built against.
+                .unsafeFlags(["-application-extension"]),
+            ],
+            linkerSettings: [
+                // A widget extension needs both halves of what Xcode does for an app-extension
+                // target, and each half is useless alone. This flag is one of them; `@main` on
+                // OpenCodexWidgetBundle is the other.
+                //
+                // With the entry override and no `@main`, nothing references the WidgetBundle, the
+                // linker drops it, and the extension registers with pluginkit — the Info.plist is
+                // enough for that — while the gallery has no configuration to offer. That is what
+                // shipped, and it failed silently.
+                //
+                // With `@main` and no entry override, the Swift main runs instead of
+                // NSExtensionMain, and ExtensionFoundation traps inside
+                // _EXRunningExtension._shared while bootstrapping. Measured: EXC_BREAKPOINT on
+                // every launch, chronod logging "query failed - will try lazy reload later", and
+                // a crash report per attempt.
+                //
+                // Both together is the shape that works and the shape Xcode produces: the entry
+                // is NSExtensionMain, and the bundle stays in the binary because `@main` refers
+                // to it.
+                .linkedFramework("Foundation"),
+                .unsafeFlags(["-Xlinker", "-e", "-Xlinker", "_NSExtensionMain"]),
+            ]
+        ),
+        // An executable rather than a .testTarget: Xcode Command Line Tools ships
+        // neither a usable XCTest module nor the swift-testing runtime, so a test bundle
+        // cannot run without a full Xcode install. See Sources/MenuBarCoreTests/Harness.swift.
+        .executableTarget(
+            name: "MenuBarCoreTests",
+            dependencies: ["MenuBarCore"],
+            path: "Sources/MenuBarCoreTests"
+        ),
+    ],
+    swiftLanguageVersions: [.v5]
+)
diff --git a/app/Sources/MenuBarCore/ActionCoordinator.swift b/app/Sources/MenuBarCore/ActionCoordinator.swift
new file mode 100644
index 00000000000..5666ad48c92
--- /dev/null
+++ b/app/Sources/MenuBarCore/ActionCoordinator.swift
@@ -0,0 +1,123 @@
+import Foundation
+
+/// The result of a write action, in terms the UI can render directly.
+public enum ActionOutcome: Equatable, Sendable {
+    case succeeded
+    /// The stop was confirmed, but nothing will restart the proxy — the user has to.
+    case requiresManualStart(String)
+    /// The proxy stopped, but it could not restore native Codex on the way out, so the
+    /// user's Codex config still points at a port that is now closed.
+    case stoppedWithRestoreFailure(String)
+    /// A human sentence. Never a response body: bodies can echo configuration.
+    case failed(String)
+}
+
+/// Executes write actions and reports what actually happened.
+///
+/// Split from the UI because the interesting behaviour is timing, not presentation:
+/// `/api/stop` answers before it drains, so "the request returned 200" and "the proxy
+/// stopped" are different facts and only the second one is worth telling the user.
+public actor ActionCoordinator {
+    /// How long to wait for the port to stop answering before giving up.
+    public static let stopTimeout: TimeInterval = 10
+    public static let pollInterval: TimeInterval = 0.5
+
+    private let client: ProxyClient
+    /// One in-flight write per provider. Both this actor and `ProxyClient` are reentrant
+    /// across network awaits, so two rapid toggles could otherwise reach the server out
+    /// of order and leave it opposite to the user's last click.
+    private var inFlight: Set<String> = []
+    private let sleeper: @Sendable (TimeInterval) async -> Void
+    /// Injected so tests can advance time without waiting for it. A no-op sleeper alone
+    /// is not enough: the loop is bounded by a deadline, so the clock has to move too.
+    private let now: @Sendable () -> Date
+
+    public init(
+        client: ProxyClient,
+        sleeper: @escaping @Sendable (TimeInterval) async -> Void = { seconds in
+            try? await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))
+        },
+        now: @escaping @Sendable () -> Date = { Date() }
+    ) {
+        self.client = client
+        self.sleeper = sleeper
+        self.now = now
+    }
+
+    /// Stops the proxy and waits until it is actually gone.
+    ///
+    /// `/api/stop` calls `stopServiceIfInstalled()` and returns before draining, so a
+    /// 200 means "accepted", not "stopped". Reporting success on the response alone
+    /// would make the UI claim a state the system has not reached yet.
+    public func stop(startCommand: String) async -> ActionOutcome {
+        let restored: Bool
+        do {
+            restored = try await client.stop()
+        } catch let error as ProxyError {
+            return .failed(error.userMessage)
+        } catch {
+            return .failed("Could not reach the proxy to stop it.")
+        }
+
+        let deadline = now().addingTimeInterval(Self.stopTimeout)
+        var sawIndeterminate = false
+        while now() < deadline {
+            await sleeper(Self.pollInterval)
+            // Cap the probe to whatever time is left, so the last one cannot overrun the
+            // deadline by its own timeout.
+            let remaining = deadline.timeIntervalSince(now())
+            guard remaining > 0 else { break }
+            switch await client.liveness(timeout: min(1.5, remaining)) {
+            case .refused:
+                // The only proof the proxy is actually gone.
+                return restored
+                    ? .requiresManualStart(startCommand)
+                    : .stoppedWithRestoreFailure(startCommand)
+            case .reachable:
+                sawIndeterminate = false
+            case .indeterminate:
+                // A timeout proves nothing; keep polling rather than declaring victory.
+                sawIndeterminate = true
+            }
+        }
+
+        return .failed(
+            sawIndeterminate
+                ? "The proxy accepted the stop, but its state could not be confirmed. Check with `ocx status`."
+                : "The proxy accepted the stop but was still responding after \(Int(Self.stopTimeout)) seconds."
+        )
+    }
+
+    /// Enables or disables a provider.
+    ///
+    /// The default provider is rejected before any request is sent: the proxy answers
+    /// 400 for that case, and firing a request that cannot succeed is worse than not
+    /// offering it.
+    public func setProvider(
+        _ name: String,
+        disabled: Bool,
+        defaultProvider: String?
+    ) async -> ActionOutcome {
+        if disabled, name == defaultProvider {
+            return .failed("\(name) is the default provider. Choose another default in the dashboard first.")
+        }
+        guard !inFlight.contains(name) else {
+            return .failed("A change to \(name) is still in progress.")
+        }
+        inFlight.insert(name)
+        defer { inFlight.remove(name) }
+
+        do {
+            try await client.setProviderDisabled(name, disabled: disabled)
+            return .succeeded
+        } catch ProxyError.http(400) {
+            // The proxy validates more than we can predict; surface its refusal without
+            // quoting its body.
+            return .failed("The proxy refused that change. Adjust it in the dashboard.")
+        } catch let error as ProxyError {
+            return .failed(error.userMessage)
+        } catch {
+            return .failed("That change could not be applied.")
+        }
+    }
+}
diff --git a/app/Sources/MenuBarCore/CompanionSettings.swift b/app/Sources/MenuBarCore/CompanionSettings.swift
new file mode 100644
index 00000000000..2e3b0333b1a
--- /dev/null
+++ b/app/Sources/MenuBarCore/CompanionSettings.swift
@@ -0,0 +1,118 @@
+import Foundation
+
+public struct CompanionSettings: Decodable, Equatable, Sendable {
+    public enum MenuBarMetric: String, Sendable {
+        case requests, tokens, cost, quota, none
+    }
+
+    public enum ChartStyle: String, Sendable {
+        case line, stackedBar
+    }
+
+    public enum TokenMetric: String, Sendable {
+        case total, input, output, cached
+    }
+
+    public enum Aggregation: String, Sendable {
+        case sum, average, max
+    }
+
+    public enum ChartGrouping: String, Sendable {
+        case model, modelAccount
+    }
+
+    public let menuBarMetric: MenuBarMetric
+    public let menuBarTemplate: String?
+    public let showToday: Bool
+    public let showChart: Bool
+    public let showModels: Bool
+    public let showCost: Bool
+    public let showAccounts: Bool
+    public let chartHours: Int
+    public let bucketMinutes: Int
+    public let chartStyle: ChartStyle
+    public let tokenMetric: TokenMetric
+    public let aggregation: Aggregation
+    public let chartGrouping: ChartGrouping
+    public let models: [String]?
+    public let hiddenProviders: [String]
+
+    public static let defaults = CompanionSettings(
+        menuBarMetric: .tokens, menuBarTemplate: nil,
+        showToday: true, showChart: true, showModels: true, showCost: true, showAccounts: true,
+        chartHours: 24, bucketMinutes: 60, chartStyle: .line, tokenMetric: .total,
+        aggregation: .sum, chartGrouping: .model, models: nil, hiddenProviders: []
+    )
+
+    public init(
+        menuBarMetric: MenuBarMetric = .tokens,
+        menuBarTemplate: String? = nil,
+        showToday: Bool = true,
+        showChart: Bool = true,
+        showModels: Bool = true,
+        showCost: Bool = true,
+        showAccounts: Bool = true,
+        chartHours: Int = 24,
+        bucketMinutes: Int = 60,
+        chartStyle: ChartStyle = .line,
+        tokenMetric: TokenMetric = .total,
+        aggregation: Aggregation = .sum,
+        chartGrouping: ChartGrouping = .model,
+        models: [String]? = nil,
+        hiddenProviders: [String] = []
+    ) {
+        self.menuBarMetric = menuBarMetric
+        self.menuBarTemplate = menuBarTemplate
+        self.showToday = showToday
+        self.showChart = showChart
+        self.showModels = showModels
+        self.showCost = showCost
+        self.showAccounts = showAccounts
+        self.chartHours = chartHours
+        self.bucketMinutes = bucketMinutes
+        self.chartStyle = chartStyle
+        self.tokenMetric = tokenMetric
+        self.aggregation = aggregation
+        self.chartGrouping = chartGrouping
+        self.models = models
+        self.hiddenProviders = hiddenProviders
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case menuBarMetric, menuBarTemplate, showToday, showChart, showModels, showCost, showAccounts
+        case chartHours, bucketMinutes, chartStyle, tokenMetric, aggregation, chartGrouping, models, hiddenProviders
+    }
+
+    public init(from decoder: Decoder) throws {
+        let c = try decoder.container(keyedBy: CodingKeys.self)
+        self.init(
+            menuBarMetric: Self.enumValue(MenuBarMetric.self, try c.decodeIfPresent(String.self, forKey: .menuBarMetric), default: .tokens),
+            menuBarTemplate: try c.decodeIfPresent(String.self, forKey: .menuBarTemplate),
+            showToday: try c.decodeIfPresent(Bool.self, forKey: .showToday) ?? true,
+            showChart: try c.decodeIfPresent(Bool.self, forKey: .showChart) ?? true,
+            showModels: try c.decodeIfPresent(Bool.self, forKey: .showModels) ?? true,
+            showCost: try c.decodeIfPresent(Bool.self, forKey: .showCost) ?? true,
+            showAccounts: try c.decodeIfPresent(Bool.self, forKey: .showAccounts) ?? true,
+            chartHours: try c.decodeIfPresent(Int.self, forKey: .chartHours) ?? 24,
+            bucketMinutes: try c.decodeIfPresent(Int.self, forKey: .bucketMinutes) ?? 60,
+            chartStyle: Self.enumValue(ChartStyle.self, try c.decodeIfPresent(String.self, forKey: .chartStyle), default: .line),
+            tokenMetric: Self.enumValue(TokenMetric.self, try c.decodeIfPresent(String.self, forKey: .tokenMetric), default: .total),
+            aggregation: Self.enumValue(Aggregation.self, try c.decodeIfPresent(String.self, forKey: .aggregation), default: .sum),
+            chartGrouping: Self.enumValue(ChartGrouping.self, try c.decodeIfPresent(String.self, forKey: .chartGrouping), default: .model),
+            models: try c.decodeIfPresent([String].self, forKey: .models),
+            hiddenProviders: try c.decodeIfPresent([String].self, forKey: .hiddenProviders) ?? []
+        )
+    }
+
+    private static func enumValue<T: RawRepresentable>(
+        _ type: T.Type, _ raw: String?, default value: T
+    ) -> T where T.RawValue == String {
+        raw.flatMap(T.init(rawValue:)) ?? value
+    }
+}
+
+public struct CompanionSettingsResponse: Decodable, Equatable, Sendable {
+    public let settings: CompanionSettings
+    public let updatedAt: Double?
+    public let corrupt: Bool?
+}
diff --git a/app/Sources/MenuBarCore/Discovery.swift b/app/Sources/MenuBarCore/Discovery.swift
new file mode 100644
index 00000000000..23b34e1d0c3
--- /dev/null
+++ b/app/Sources/MenuBarCore/Discovery.swift
@@ -0,0 +1,80 @@
+import Foundation
+
+/// A loopback endpoint for the local OpenCodex proxy.
+///
+/// The host is deliberately fixed to loopback and never read from disk: the port record
+/// is a convenience, not a redirection mechanism.
+public struct ProxyEndpoint: Equatable, Sendable {
+    public static let loopbackHost = "127.0.0.1"
+    public static let validPorts = 1...65535
+
+    public let host: String
+    public let port: Int
+    private let resolvedURL: URL
+
+    /// Fails rather than traps on an out-of-range port. `baseURL` is built once here, so
+    /// no accessor can crash later on a value that was never a valid URL.
+    public init?(port: Int) {
+        guard Self.validPorts.contains(port),
+              let url = URL(string: "http://\(Self.loopbackHost):\(port)")
+        else { return nil }
+        self.host = Self.loopbackHost
+        self.port = port
+        self.resolvedURL = url
+    }
+
+    /// The default endpoint, which is known-valid by construction.
+    public static let `default` = ProxyEndpoint(port: ProxyDiscovery.defaultPort)!
+
+    public var baseURL: URL { resolvedURL }
+
+    public var display: String { "\(host):\(port)" }
+}
+
+struct RuntimePortRecord: Decodable {
+    let pid: Int?
+    let port: Int
+}
+
+/// Resolves where the proxy is listening, mirroring `resolveRuntimePortPath()` in
+/// `src/config.ts`.
+public enum ProxyDiscovery {
+    public static let defaultPort = 10100
+    public static var validPorts: ClosedRange<Int> { ProxyEndpoint.validPorts }
+
+    /// `OPENCODEX_HOME` when set and non-empty, else `~/.opencodex`.
+    public static func configDirectory(
+        environment: [String: String] = ProcessInfo.processInfo.environment,
+        home: URL = FileManager.default.homeDirectoryForCurrentUser
+    ) -> URL {
+        if let override = environment["OPENCODEX_HOME"]?.trimmingCharacters(in: .whitespaces),
+           !override.isEmpty {
+            return URL(fileURLWithPath: (override as NSString).expandingTildeInPath)
+        }
+        return home.appendingPathComponent(".opencodex", isDirectory: true)
+    }
+
+    /// Reads `runtime-port.json`, falling back to the default port on any problem.
+    ///
+    /// Every failure mode — missing file, malformed JSON, out-of-range port — resolves to
+    /// the default rather than throwing. A desktop app that refuses to start because a
+    /// cache file is unreadable would be worse than one that probes the usual port.
+    public static func resolve(configDirectory directory: URL) -> ProxyEndpoint {
+        let file = directory.appendingPathComponent("runtime-port.json")
+        guard
+            let data = try? Data(contentsOf: file),
+            let record = try? JSONDecoder().decode(RuntimePortRecord.self, from: data),
+            let endpoint = ProxyEndpoint(port: record.port)
+        else {
+            return .default
+        }
+        return endpoint
+    }
+
+    public static func resolve(
+        environment: [String: String] = ProcessInfo.processInfo.environment,
+        home: URL = FileManager.default.homeDirectoryForCurrentUser
+    ) -> ProxyEndpoint {
+        resolve(configDirectory: configDirectory(environment: environment, home: home))
+    }
+}
diff --git a/app/Sources/MenuBarCore/Formatting.swift b/app/Sources/MenuBarCore/Formatting.swift
new file mode 100644
index 00000000000..4008f53f34f
--- /dev/null
+++ b/app/Sources/MenuBarCore/Formatting.swift
@@ -0,0 +1,106 @@
+import Foundation
+
+/// Number and date presentation for a 340pt popover.
+///
+/// Live data reaches `requests: 232507`, `totalTokens: 36536664705`, and
+/// `estimatedCostUsd: 34018.25`. Rendering those verbatim destroys the layout, so every
+/// value is abbreviated and every unknown is an em dash — never a plausible-looking zero.
+public enum Format {
+    public static let unknown = "—"
+
+    private static let grouping: NumberFormatter = {
+        let f = NumberFormatter()
+        f.numberStyle = .decimal
+        f.groupingSeparator = ","
+        f.maximumFractionDigits = 0
+        return f
+    }()
+
+    /// Counts: grouped below 10 000, then SI-suffixed with 3 significant figures.
+    public static func count(_ value: Int?) -> String {
+        guard let value else { return unknown }
+        if value < 10_000 {
+            return grouping.string(from: NSNumber(value: value)) ?? String(value)
+        }
+        return abbreviate(Double(value))
+    }
+
+    /// Tokens are always suffixed — they are never small enough to be worth grouping.
+    public static func tokens(_ value: Int?) -> String {
+        guard let value else { return unknown }
+        if value < 1_000 { return String(value) }
+        return abbreviate(Double(value), integer: true)
+    }
+
+    public static func cost(_ value: Double?) -> String {
+        guard let value else { return unknown }
+        if value < 1_000 {
+            return String(format: "$%.2f", value)
+        }
+        return "$" + abbreviate(value)
+    }
+
+    public static func percent(_ value: Double?) -> String {
+        guard let value else { return unknown }
+        return "\(Int(value.rounded()))%"
+    }
+
+    /// "resets in 3d 4h" / "resets in 12m". Past dates read as "expired".
+    public static func resetsIn(_ date: Date?, now: Date = Date()) -> String {
+        guard let date else { return unknown }
+        let interval = date.timeIntervalSince(now)
+        guard interval > 0 else { return "expired" }
+
+        let totalMinutes = Int(interval / 60)
+        let days = totalMinutes / 1440
+        let hours = (totalMinutes % 1440) / 60
+        let minutes = totalMinutes % 60
+
+        if days > 0 { return hours > 0 ? "\(days)d \(hours)h" : "\(days)d" }
+        if hours > 0 { return minutes > 0 ? "\(hours)h \(minutes)m" : "\(hours)h" }
+        return "\(max(minutes, 1))m"
+    }
+
+    /// "2m ago" for staleness labels on the degraded state.
+    public static func age(_ date: Date?, now: Date = Date()) -> String {
+        guard let date else { return unknown }
+        let seconds = Int(now.timeIntervalSince(date))
+        if seconds < 60 { return "just now" }
+        if seconds < 3600 { return "\(seconds / 60)m ago" }
+        if seconds < 86_400 { return "\(seconds / 3600)h ago" }
+        return "\(seconds / 86_400)d ago"
+    }
+
+    private static func abbreviate(_ value: Double, integer: Bool = false) -> String {
+        let units: [(threshold: Double, suffix: String)] = [
+            (1_000_000_000_000, "T"),
+            (1_000_000_000, "B"),
+            (1_000_000, "M"),
+            (1_000, "K"),
+        ]
+        // Ascending, so promotion is a simple step to the next entry.
+        let ascending = units.reversed().map { $0 }
+
+        for (index, unit) in ascending.enumerated() where value < (unit.threshold * 1000) {
+            let rendered = render(value / unit.threshold, suffix: unit.suffix, integer: integer)
+            // Rounding can push a value across its own boundary: 999_999 scales to
+            // 999.999K, which would render "1000K" instead of promoting to "1.00M".
+            guard rendered.hasPrefix("1000"), index + 1 < ascending.count else { return rendered }
+            let larger = ascending[index + 1]
+            return render(value / larger.threshold, suffix: larger.suffix, integer: integer)
+        }
+
+        // Beyond the largest unit, stay in that unit rather than inventing a suffix.
+        if let largest = ascending.last, value >= largest.threshold {
+            return render(value / largest.threshold, suffix: largest.suffix, integer: integer)
+        }
+        return String(format: "%.0f", value)
+    }
+
+    /// Render an abbreviated value with either integer or 3-significant-figure precision.
+    private static func render(_ scaled: Double, suffix: String, integer: Bool = false) -> String {
+        if integer { return String(format: "%.0f%@", scaled, suffix) }
+        let decimals = scaled >= 100 ? 0 : (scaled >= 10 ? 1 : 2)
+        return String(format: "%.\(decimals)f%@", scaled, suffix)
+    }
+}
diff --git a/app/Sources/MenuBarCore/Keychain.swift b/app/Sources/MenuBarCore/Keychain.swift
new file mode 100644
index 00000000000..2d67ecb5de3
--- /dev/null
+++ b/app/Sources/MenuBarCore/Keychain.swift
@@ -0,0 +1,76 @@
+import Foundation
+import Security
+
+/// Generic-password storage for the optional management API key.
+///
+/// The key is read lazily — only after a 401 — and is never written to UserDefaults,
+/// never logged, and never included in an error surfaced to the UI.
+///
+/// **Read-only in practice today, and there is no way to provision the key.** Nothing in
+/// the app calls `write`, because there is no key-entry UI yet — and a user cannot fill
+/// the gap by hand either: every query sets `kSecUseDataProtectionKeychain`, and
+/// Keychain Access does not create data-protection items. So a non-loopback bind is
+/// genuinely unsupported rather than merely inconvenient, and the docs say exactly that.
+///
+/// `write`/`delete` exist for the native entry flow that is planned. Do not document a
+/// manual workaround on top of them: an earlier revision of the guide did, naming a
+/// service that was both wrong and unreachable.
+///
+/// Every query sets `kSecUseDataProtectionKeychain`. Without it, `kSecAttrAccessible` is
+/// ignored on macOS (it applies only to data-protection or synchronizable items), so the
+/// declared accessibility class would be decorative. Setting it on *all* operations also
+/// matters for correctness: a data-protection item is invisible to a query that omits
+/// the flag, so a mixed set of queries would fail to find or delete its own items.
+public enum Keychain {
+    public static let service = "com.opencodex.menubar.apikey"
+    public static let defaultAccount = "default"
+
+    private static func baseQuery(account: String) -> [String: Any] {
+        [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: account,
+            kSecUseDataProtectionKeychain as String: true,
+        ]
+    }
+
+    public static func read(account: String = defaultAccount) -> String? {
+        var query = baseQuery(account: account)
+        query[kSecReturnData as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+        var item: CFTypeRef?
+        guard SecItemCopyMatching(query as CFDictionary, &item) == errSecSuccess,
+              let data = item as? Data,
+              let value = String(data: data, encoding: .utf8),
+              !value.isEmpty
+        else { return nil }
+        return value
+    }
+
+    @discardableResult
+    public static func write(_ value: String, account: String = defaultAccount) -> Bool {
+        let data = Data(value.utf8)
+
+        // Update first, add only when absent. Deleting first would destroy a working key
+        // whenever the subsequent add failed.
+        let updateStatus = SecItemUpdate(
+            baseQuery(account: account) as CFDictionary,
+            [kSecValueData as String: data] as CFDictionary
+        )
+        if updateStatus == errSecSuccess { return true }
+        guard updateStatus == errSecItemNotFound else { return false }
+
+        var attributes = baseQuery(account: account)
+        attributes[kSecValueData as String] = data
+        // ThisDeviceOnly: the key is a local proxy credential with no reason to migrate
+        // to another machine via backup or transfer.
+        attributes[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+        return SecItemAdd(attributes as CFDictionary, nil) == errSecSuccess
+    }
+
+    @discardableResult
+    public static func delete(account: String = defaultAccount) -> Bool {
+        let status = SecItemDelete(baseQuery(account: account) as CFDictionary)
+        return status == errSecSuccess || status == errSecItemNotFound
+    }
+}
diff --git a/app/Sources/MenuBarCore/MenuBarTitle.swift b/app/Sources/MenuBarCore/MenuBarTitle.swift
new file mode 100644
index 00000000000..c17613e3c85
--- /dev/null
+++ b/app/Sources/MenuBarCore/MenuBarTitle.swift
@@ -0,0 +1,38 @@
+import Foundation
+
+public enum MenuBarTitle {
+    public static func render(
+        settings: CompanionSettings,
+        today: UsageReport?,
+        quotas: [NormalizedQuota]
+    ) -> String? {
+        let summary = today?.summary
+        let values: [String: String] = [
+            "requests": Format.count(summary?.requests),
+            "totalTokens": Format.tokens(summary?.totalTokens),
+            "inputTokens": Format.tokens(summary?.inputTokens),
+            "outputTokens": Format.tokens(summary?.outputTokens),
+            "costUsd": Format.cost(summary?.estimatedCostUsd),
+            "quotaPercent": Format.percent(quotas.compactMap(\.percent).min()),
+        ]
+        let rendered: String
+        if let template = settings.menuBarTemplate?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !template.isEmpty {
+            rendered = values.reduce(template) { text, item in
+                text.replacingOccurrences(of: "{\(item.key)}", with: item.value)
+            }
+        } else {
+            switch settings.menuBarMetric {
+            case .requests: rendered = Format.count(summary?.requests)
+            case .tokens: rendered = Format.tokens(summary?.totalTokens)
+            case .cost: rendered = Format.cost(summary?.estimatedCostUsd)
+            case .quota: rendered = Format.percent(quotas.compactMap(\.percent).min())
+            case .none: return nil
+            }
+        }
+        let text = rendered.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !text.isEmpty else { return nil }
+        if text.count <= 24 { return text }
+        return String(text.prefix(23)) + "…"
+    }
+}
diff --git a/app/Sources/MenuBarCore/PollingCoordinator.swift b/app/Sources/MenuBarCore/PollingCoordinator.swift
new file mode 100644
index 00000000000..5154fd7e835
--- /dev/null
+++ b/app/Sources/MenuBarCore/PollingCoordinator.swift
@@ -0,0 +1,268 @@
+import Foundation
+
+/// Owns the refresh schedule and turns transport results into a `ProxySnapshot`.
+///
+/// Polling is deliberately conservative. A desktop app that hits a local server every
+/// five seconds forever is a battery complaint waiting to happen, so heavy aggregation
+/// endpoints are fetched only while the popover is open, and repeated failures back the
+/// liveness tick off rather than hammering a proxy the user has stopped on purpose.
+public actor PollingCoordinator {
+    public static let livenessInterval: TimeInterval = 5
+    public static let heavyInterval: TimeInterval = 60
+    public static let backoffInterval: TimeInterval = 30
+    public static let backoffAfterFailures = 3
+
+    private let client: ProxyClient
+    private var snapshot: ProxySnapshot
+    private var popoverOpen = false
+    private var observers: [UUID: @Sendable (ProxySnapshot) -> Void] = [:]
+    /// Rises on every close and on every new refresh, so results from a superseded or
+    /// abandoned cycle can be discarded instead of overwriting fresher state.
+    private var generation = 0
+    private var refreshInFlight = false
+    /// A refresh requested while another was in flight. Without this, closing and
+    /// immediately reopening the popover dropped the reopen's refresh entirely: the old
+    /// cycle exited on its generation guard and the new one had already been rejected.
+    private var pendingOpenRefresh = false
+    /// Continuations waiting for a cycle to publish. Waiting on a real completion signal
+    /// rather than a bounded spin means a slow-but-legitimate refresh cannot be
+    /// abandoned early, which would re-enable a control against pre-write state.
+    private var completionWaiters: [CheckedContinuation<Void, Never>] = []
+    /// Attempt time, distinct from success time: a persistently failing endpoint must
+    /// not turn its healthy sibling into a 5-second poller.
+    private var lastAggregationAttempt: Date?
+
+    public init(client: ProxyClient, endpoint: ProxyEndpoint) {
+        self.client = client
+        self.snapshot = ProxySnapshot(endpoint: endpoint)
+    }
+
+    public var current: ProxySnapshot { snapshot }
+
+    /// Interval until the next liveness tick, widened once failures pile up.
+    public var currentInterval: TimeInterval {
+        snapshot.consecutiveFailures >= Self.backoffAfterFailures
+            ? Self.backoffInterval
+            : Self.livenessInterval
+    }
+
+    @discardableResult
+    public func observe(_ handler: @escaping @Sendable (ProxySnapshot) -> Void) -> UUID {
+        let token = UUID()
+        observers[token] = handler
+        handler(snapshot)
+        return token
+    }
+
+    public func removeObserver(_ token: UUID) { observers[token] = nil }
+
+    public func setPopoverOpen(_ open: Bool) async {
+        popoverOpen = open
+        if open {
+            await refresh(includeHeavy: true)
+        } else {
+            // Abandon in-flight heavy work: its results are no longer visible and
+            // must not land as if they were current.
+            generation &+= 1
+        }
+    }
+
+    /// One refresh cycle.
+    ///
+    /// `includeHeavy` marks a popover-open refresh: on-open reads (providers, config)
+    /// always run, while the expensive aggregation reads (usage, quotas) still respect
+    /// the 60s interval so reopening the popover repeatedly does not hammer the proxy.
+    public func refresh(includeHeavy: Bool = false) async {
+        // Overlapping cycles publish interleaved state and double the request rate.
+        guard !refreshInFlight else {
+            if includeHeavy { pendingOpenRefresh = true }
+            return
+        }
+        refreshInFlight = true
+        generation &+= 1
+        let cycle = generation
+        defer { refreshInFlight = false }
+
+        do {
+            let health = try await client.health()
+            guard cycle == generation else {
+                refreshInFlight = false
+                await drainPendingRefresh()
+                signalCompletionIfIdle()
+                return
+            }
+            snapshot.state = .running(health)
+            snapshot.lastKnownStartCommand = health.manualStartCommand
+            snapshot.recommendedCommand = health.recommendedCommand
+            snapshot.consecutiveFailures = 0
+            snapshot.lastUpdated = Date()
+        } catch is CancellationError {
+            // The popover closed mid-flight. Not a proxy failure; leave state untouched.
+            refreshInFlight = false
+            await drainPendingRefresh()
+            signalCompletionIfIdle()
+            return
+        } catch let error as ProxyError {
+            if cycle == generation { apply(error); publish() }
+            refreshInFlight = false
+            await drainPendingRefresh()
+            signalCompletionIfIdle()
+            return
+        } catch {
+            if cycle == generation { apply(.transport); publish() }
+            refreshInFlight = false
+            await drainPendingRefresh()
+            signalCompletionIfIdle()
+            return
+        }
+
+        if popoverOpen, includeHeavy {
+            await refreshOnOpen(cycle: cycle)
+        }
+
+        // Settings and today metrics also drive the menu-bar title, so aggregation runs
+        // on the normal cadence even while the popover is closed.
+        let aggregationDue = lastAggregationAttempt.map {
+            Date().timeIntervalSince($0) >= Self.heavyInterval
+        } ?? true
+        if aggregationDue, isCurrentCycle(cycle) {
+            lastAggregationAttempt = Date()
+            _ = await refreshAggregation(cycle: cycle)
+        }
+
+        if cycle == generation { publish() }
+        refreshInFlight = false
+        await drainPendingRefresh()
+        signalCompletionIfIdle()
+    }
+
+    /// Refreshes and does not return until a cycle has actually published.
+    ///
+    /// `refresh()` coalesces: if another cycle holds the lock it queues and returns
+    /// immediately. A caller that needs authoritative state afterwards — such as
+    /// re-enabling a switch after a write — would otherwise act on pre-write data.
+    public func refreshAndWait(includeHeavy: Bool = true) async {
+        if refreshInFlight {
+            // Queue behind the running cycle and wait for the queued one to finish.
+            await refresh(includeHeavy: includeHeavy)
+            await waitForCompletion()
+            return
+        }
+        await refresh(includeHeavy: includeHeavy)
+    }
+
+    /// Number of callers currently suspended in `waitForCompletion()`.
+    ///
+    /// Exposed so a test can wait for registration deterministically instead of sleeping
+    /// and hoping the waiter task was scheduled — a fixed sleep let the continuation
+    /// tests pass without ever entering this path.
+    package var waiterCount: Int { completionWaiters.count }
+
+    private func waitForCompletion() async {
+        guard refreshInFlight || pendingOpenRefresh else { return }
+        await withCheckedContinuation { continuation in
+            completionWaiters.append(continuation)
+        }
+    }
+
+    /// Releases anyone waiting once no cycle is running or queued.
+    private func signalCompletionIfIdle() {
+        guard !refreshInFlight, !pendingOpenRefresh, !completionWaiters.isEmpty else { return }
+        let waiters = completionWaiters
+        completionWaiters.removeAll()
+        for waiter in waiters { waiter.resume() }
+    }
+
+    /// Runs a refresh that arrived while another cycle held the lock.
+    private func drainPendingRefresh() async {
+        guard pendingOpenRefresh, popoverOpen else {
+            pendingOpenRefresh = false
+            return
+        }
+        pendingOpenRefresh = false
+        await refresh(includeHeavy: true)
+    }
+
+    /// Reads that are only meaningful while the popover is open.
+    private func refreshOnOpen(cycle: Int) async {
+        guard isCurrent(cycle) else { return }
+        if let providers = try? await client.providers(), isCurrent(cycle) {
+            snapshot.providers = providers
+            snapshot.providersLoaded = true
+        }
+        // Re-check before each subsequent request: closing mid-flight should stop the
+        // sequence, not merely discard its results after paying for them.
+        guard isCurrent(cycle) else { return }
+        if let config = try? await client.config(), isCurrent(cycle) {
+            snapshot.defaultProvider = config.defaultProvider
+        }
+    }
+
+    /// Still the newest cycle, and still worth doing.
+    private func isCurrent(_ cycle: Int) -> Bool { cycle == generation && popoverOpen }
+    private func isCurrentCycle(_ cycle: Int) -> Bool { cycle == generation }
+
+    /// The expensive aggregation reads. Returns whether every read landed, so a partial
+    /// failure does not masquerade as a completed refresh.
+    private func refreshAggregation(cycle: Int) async -> Bool {
+        guard isCurrentCycle(cycle) else { return false }
+        var complete = true
+
+        // Each read is independent: one failing endpoint must not blank the others.
+        if let response = try? await client.companionSettings() {
+            guard isCurrentCycle(cycle) else { return false }
+            snapshot.settings = response.settings
+            snapshot.settingsLoaded = true
+        } else {
+            complete = false
+        }
+
+        guard isCurrentCycle(cycle) else { return false }
+        if let today = try? await client.usage(range: .today) {
+            guard isCurrentCycle(cycle) else { return false }
+            snapshot.today = today
+            snapshot.usage = today
+            snapshot.usageUpdated = Date()
+        } else {
+            complete = false
+        }
+
+        guard isCurrentCycle(cycle) else { return false }
+        if snapshot.settings.showChart, let timeline = try? await client.timeline(snapshot.settings) {
+            guard isCurrentCycle(cycle) else { return false }
+            snapshot.timeline = timeline
+            snapshot.timelineUpdated = Date()
+        } else if snapshot.settings.showChart {
+            complete = false
+        }
+
+        guard isCurrentCycle(cycle) else { return false }
+        if (popoverOpen || snapshot.settings.menuBarMetric == .quota), let quotas = try? await client.quotas() {
+            guard isCurrent(cycle) else { return false }
+            snapshot.quotas = quotas
+            snapshot.quotasLoaded = true
+        } else if popoverOpen || snapshot.settings.menuBarMetric == .quota {
+            complete = false
+        }
+
+        return complete
+    }
+
+    private func apply(_ error: ProxyError) {
+        snapshot.consecutiveFailures += 1
+        switch error {
+        case .unreachable:
+            snapshot.state = .unreachable
+        case .unauthorized:
+            snapshot.state = .unauthorized
+        case .http, .decoding, .transport, .inconclusive:
+            // A timeout is degraded, not stopped: something may well still be running.
+            snapshot.state = .degraded(error.userMessage)
+        }
+    }
+
+    private func publish() {
+        let value = snapshot
+        for handler in observers.values { handler(value) }
+    }
+}
diff --git a/app/Sources/MenuBarCore/ProxyClient.swift b/app/Sources/MenuBarCore/ProxyClient.swift
new file mode 100644
index 00000000000..e9a31984244
--- /dev/null
+++ b/app/Sources/MenuBarCore/ProxyClient.swift
@@ -0,0 +1,332 @@
+import Foundation
+
+public enum ProxyError: Error, Equatable {
+    /// The connection was refused — nothing is listening. This is the only transport
+    /// result that proves the proxy is gone; timeouts get `.inconclusive`.
+    case unreachable
+    /// 401 — a non-loopback bind that requires a credential.
+    case unauthorized
+    case http(Int)
+    case decoding
+    /// A transport failure that is not evidence the proxy is down (TLS, policy, and
+    /// other non-connectivity URLSession errors).
+    case transport
+    /// The request never completed — a timeout or a socket dropped mid-response. This
+    /// proves nothing either way, and must not be read as "the proxy is gone".
+    case inconclusive
+
+    /// Human sentences only. Response bodies can echo configuration values, so they
+    /// never reach the UI or a log.
+    public var userMessage: String {
+        switch self {
+        case .unreachable: return "The proxy is not running."
+        case .unauthorized: return "This proxy requires an API key."
+        case .http(let code): return "The proxy returned an unexpected status (\(code))."
+        case .decoding: return "The proxy returned a response this app could not read."
+        case .transport: return "The connection to the proxy failed."
+        case .inconclusive: return "The proxy did not respond in time."
+        }
+    }
+}
+
+/// Supplies the optional management API key. Injected so tests never touch the real
+/// Keychain and so the app can swap the source without touching transport code.
+public protocol CredentialStore: Sendable {
+    func loadAPIKey() -> String?
+}
+
+public struct KeychainCredentialStore: CredentialStore {
+    public init() {}
+    public func loadAPIKey() -> String? { Keychain.read() }
+}
+
+/// HTTP client for the OpenCodex management API.
+///
+/// An actor because the endpoint and key are mutated from both the polling loop and user
+/// actions; the isolation makes that data-race-free by construction rather than by
+/// convention.
+public actor ProxyClient {
+    private let session: URLSession
+    private let credentials: CredentialStore
+    private var endpoint: ProxyEndpoint
+    private var apiKey: String?
+    /// Ensures the lazy credential load happens at most once per client.
+    private var didAttemptCredentialLoad = false
+
+    public init(
+        endpoint: ProxyEndpoint,
+        session: URLSession? = nil,
+        credentials: CredentialStore = KeychainCredentialStore()
+    ) {
+        self.endpoint = endpoint
+        self.credentials = credentials
+        if let session {
+            self.session = session
+        } else {
+            let config = URLSessionConfiguration.ephemeral
+            config.timeoutIntervalForRequest = 4
+            config.waitsForConnectivity = false
+            self.session = URLSession(configuration: config)
+        }
+    }
+
+    public var currentEndpoint: ProxyEndpoint { endpoint }
+
+    public func updateEndpoint(_ endpoint: ProxyEndpoint) { self.endpoint = endpoint }
+
+    public func setAPIKey(_ key: String?) {
+        self.apiKey = key
+        // An explicitly supplied key replaces the lazy path entirely.
+        self.didAttemptCredentialLoad = true
+    }
+
+    // MARK: - Reads
+
+    public func health() async throws -> StartupHealth { try await get("api/startup-health") }
+    public func settings() async throws -> ProxySettings { try await get("api/settings") }
+    public func config() async throws -> ProxyConfigSummary { try await get("api/config") }
+    public func providers() async throws -> [ProviderSummary] { try await get("api/providers") }
+
+    public func usage(range: UsageRange = .sevenDays) async throws -> UsageReport {
+        try await get("api/usage", query: [URLQueryItem(name: "range", value: range.rawValue)])
+    }
+
+    public func companionSettings() async throws -> CompanionSettingsResponse {
+        try await get("api/companion/settings")
+    }
+
+    public func timeline(_ settings: CompanionSettings) async throws -> UsageTimeline {
+        var query = [
+            URLQueryItem(name: "hours", value: String(settings.chartHours)),
+            URLQueryItem(name: "bucketMinutes", value: String(settings.bucketMinutes)),
+            URLQueryItem(name: "metric", value: settings.tokenMetric.rawValue),
+            URLQueryItem(name: "aggregation", value: settings.aggregation.rawValue),
+            URLQueryItem(name: "grouping", value: settings.chartGrouping.rawValue),
+        ]
+        if let models = settings.models, !models.isEmpty {
+            query.append(URLQueryItem(name: "models", value: models.joined(separator: ",")))
+        }
+        return try await get("api/usage/timeline", query: query)
+    }
+
+    public func quotas() async throws -> [QuotaReport] {
+        let envelope: QuotaEnvelope = try await get("api/provider-quotas")
+        return envelope.reports ?? []
+    }
+
+    /// What a liveness probe actually established.
+    ///
+    /// Three states, not two. "Did not get a usable answer" and "nothing is listening"
+    /// are different facts, and conflating them let a stop be reported as confirmed
+    /// while an HTTP server was still running behind a 500 or a decode failure.
+    public enum Liveness: Equatable, Sendable {
+        /// Something answered — any HTTP status, including 401/403/500, or a body we
+        /// could not decode. The port is occupied.
+        case reachable
+        /// The connection was refused. This is the only proof that the proxy is gone.
+        case refused
+        /// A timeout or other transport failure: no conclusion either way.
+        case indeterminate
+    }
+
+    /// A short probe: the default 4s read timeout would let a single liveness check
+    /// overrun the stop deadline it is supposed to respect.
+    public func liveness(timeout: TimeInterval = 1.5) async -> Liveness {
+        do {
+            // Deliberately bypasses `send()`: its 401 credential retry would spend a
+            // second full timeout re-asking a question the 401 already answered, and a
+            // failed retry would downgrade a known-reachable result to indeterminate.
+            _ = try await perform(
+                method: "GET", path: "api/settings", query: [],
+                body: nil as EmptyBody?, timeout: timeout
+            )
+            return .reachable
+        } catch ProxyError.unauthorized, ProxyError.decoding {
+            // Both prove a server answered.
+            return .reachable
+        } catch ProxyError.http {
+            return .reachable
+        } catch ProxyError.unreachable {
+            // Connection refused: nothing is listening on the port.
+            return .refused
+        } catch {
+            // Timeouts, dropped sockets, and anything else: no conclusion.
+            return .indeterminate
+        }
+    }
+
+    /// Convenience for callers that only need "is anything there".
+    public func isReachable() async -> Bool {
+        await liveness() != .refused
+    }
+
+    // MARK: - Writes
+
+    /// `POST /api/stop`. Returns once the proxy has accepted the request.
+    ///
+    /// The proxy answers 200 *before* draining, and it stops the launchd service first so
+    /// nothing respawns it. Callers must poll `liveness()` rather than treat this return
+    /// as "stopped".
+    ///
+    /// The response carries `success: false` when `restoreNativeCodex()` failed
+    /// (`src/server/management-api.ts:145-147`): the proxy still shuts down, but native
+    /// Codex was left pointing at a port that is about to close. Only the boolean is
+    /// decoded — the accompanying message is a server-formatted string and never reaches
+    /// the UI.
+    @discardableResult
+    public func stop() async throws -> Bool {
+        let data = try await send(method: "POST", path: "api/stop", body: nil as EmptyBody?)
+        guard let result = try? JSONDecoder().decode(StopResult.self, from: data) else {
+            // An undecodable body is not a reason to claim the restore failed.
+            return true
+        }
+        return result.success ?? true
+    }
+
+    /// `PATCH /api/providers?name=<name>` with a body of exactly `{"disabled": <bool>}`.
+    ///
+    /// A disabled-only patch skips the proxy's heavier merged-shape validators, so adding
+    /// any second field would silently change the request class.
+    public func setProviderDisabled(_ name: String, disabled: Bool) async throws {
+        _ = try await send(
+            method: "PATCH",
+            path: "api/providers",
+            query: [URLQueryItem(name: "name", value: name)],
+            body: ProviderDisabledPatch(disabled: disabled)
+        )
+    }
+
+    // MARK: - Transport
+
+    private func get<T: Decodable>(
+        _ path: String,
+        query: [URLQueryItem] = [],
+        timeout: TimeInterval? = nil
+    ) async throws -> T {
+        let data = try await send(
+            method: "GET", path: path, query: query,
+            body: nil as EmptyBody?, timeout: timeout
+        )
+        do {
+            return try JSONDecoder().decode(T.self, from: data)
+        } catch {
+            throw ProxyError.decoding
+        }
+    }
+
+    private func send<Body: Encodable>(
+        method: String,
+        path: String,
+        query: [URLQueryItem] = [],
+        body: Body?,
+        timeout: TimeInterval? = nil
+    ) async throws -> Data {
+        let keyAtStart = apiKey
+        do {
+            return try await perform(method: method, path: path, query: query, body: body, timeout: timeout)
+        } catch ProxyError.unauthorized {
+            // A loopback proxy needs no credential, so a 401 means this install is bound
+            // to a non-loopback host.
+            //
+            // Reentrancy matters here: the actor suspends across the request, so several
+            // calls can be in flight and all receive 401. Retry eligibility is therefore
+            // decided per request, against the key THAT request actually sent — not
+            // against a single global "already tried" flag. A concurrent caller that
+            // started before the key was loaded must still get to retry with it.
+            guard let key = try await credentialForRetry(after: keyAtStart) else {
+                throw ProxyError.unauthorized
+            }
+            return try await perform(method: method, path: path, query: query, body: body, key: key, timeout: timeout)
+        }
+    }
+
+    /// The key to retry with, or `nil` when this request already used the current
+    /// credential (so retrying would repeat an identical, failing call).
+    private func credentialForRetry(after keyAtStart: String?) async throws -> String? {
+        // Another in-flight call already loaded a key this request did not use.
+        if let current = apiKey, current != keyAtStart { return current }
+        // This request already carried the newest key: a stale credential, not a
+        // missing one. Never loop.
+        if apiKey != nil, apiKey == keyAtStart { return nil }
+
+        guard !didAttemptCredentialLoad else { return nil }
+        didAttemptCredentialLoad = true
+        guard let stored = credentials.loadAPIKey(), !stored.isEmpty else { return nil }
+        apiKey = stored
+        return stored
+    }
+
+    private func perform<Body: Encodable>(
+        method: String,
+        path: String,
+        query: [URLQueryItem],
+        body: Body?,
+        key: String? = nil,
+        timeout: TimeInterval? = nil
+    ) async throws -> Data {
+        guard var components = URLComponents(
+            url: endpoint.baseURL.appendingPathComponent(path),
+            resolvingAgainstBaseURL: false
+        ) else { throw ProxyError.decoding }
+        if !query.isEmpty { components.queryItems = query }
+        guard let url = components.url else { throw ProxyError.decoding }
+
+        var request = URLRequest(url: url)
+        request.httpMethod = method
+        request.timeoutInterval = timeout ?? (method == "GET" ? 4 : 6)
+        let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? "dev"
+        request.setValue("OpenCodexWidget/\(version)", forHTTPHeaderField: "User-Agent")
+        if let credential = key ?? apiKey {
+            request.setValue(credential, forHTTPHeaderField: "x-opencodex-api-key")
+        }
+        if let body {
+            request.setValue("application/json", forHTTPHeaderField: "content-type")
+            request.httpBody = try? JSONEncoder().encode(body)
+        }
+
+        do {
+            let (data, response) = try await session.data(for: request)
+            guard let http = response as? HTTPURLResponse else { throw ProxyError.decoding }
+            if http.statusCode == 401 { throw ProxyError.unauthorized }
+            guard (200..<300).contains(http.statusCode) else {
+                throw ProxyError.http(http.statusCode)
+            }
+            return data
+        } catch let error as ProxyError {
+            throw error
+        } catch let error as URLError {
+            switch error.code {
+            case .cancelled:
+                // Propagate cancellation rather than reporting a stopped proxy: the
+                // polling coordinator cancels in-flight work whenever the popover closes.
+                throw CancellationError()
+            case .cannotConnectToHost:
+                // The one code that actually proves nothing is listening.
+                throw ProxyError.unreachable
+            case .timedOut, .networkConnectionLost, .cannotFindHost,
+                 .notConnectedToInternet, .dnsLookupFailed:
+                // A timeout or a dropped socket says the request failed, not that the
+                // server is gone. Collapsing these into `.unreachable` is what let a
+                // stop be reported as confirmed while the proxy was still running.
+                throw ProxyError.inconclusive
+            default:
+                throw ProxyError.transport
+            }
+        }
+    }
+}
+
+private struct QuotaEnvelope: Decodable {
+    let generatedAt: Double?
+    let reports: [QuotaReport]?
+}
+
+private struct ProviderDisabledPatch: Encodable {
+    let disabled: Bool
+}
+
+private struct StopResult: Decodable {
+    let success: Bool?
+}
+
+private struct EmptyBody: Encodable {}
diff --git a/app/Sources/MenuBarCore/ProxyModels.swift b/app/Sources/MenuBarCore/ProxyModels.swift
new file mode 100644
index 00000000000..b79034e394b
--- /dev/null
+++ b/app/Sources/MenuBarCore/ProxyModels.swift
@@ -0,0 +1,285 @@
+import Foundation
+
+// Codable mirrors of the management API payloads inventoried in
+// devlog/_plan/260725_macos_menubar_app/002_api_surface.md.
+//
+// Every field the proxy may omit is optional. The proxy is a fast-moving local service;
+// a companion that fails to decode because one field moved is worse than one that shows
+// an em dash.
+
+/// `GET /api/startup-health`
+public struct StartupHealth: Decodable, Equatable, Sendable {
+    public let status: String?
+    public let protection: String?
+    public let platform: String?
+    public let routingKind: String?
+    public let serviceRunning: Bool?
+    public let serviceInstalled: Bool?
+    public let serviceEnabled: Bool?
+    public let rebootSafe: Bool?
+    public let recommendedCommand: String?
+
+    public init(
+        status: String? = nil,
+        protection: String? = nil,
+        platform: String? = nil,
+        routingKind: String? = nil,
+        serviceRunning: Bool? = nil,
+        serviceInstalled: Bool? = nil,
+        serviceEnabled: Bool? = nil,
+        rebootSafe: Bool? = nil,
+        recommendedCommand: String? = nil
+    ) {
+        self.status = status
+        self.protection = protection
+        self.platform = platform
+        self.routingKind = routingKind
+        self.serviceRunning = serviceRunning
+        self.serviceInstalled = serviceInstalled
+        self.serviceEnabled = serviceEnabled
+        self.rebootSafe = rebootSafe
+        self.recommendedCommand = recommendedCommand
+    }
+
+    /// `status` is treated as an open string: unknown values degrade to a neutral state
+    /// rather than crashing or being coerced into "healthy".
+    public var isProtected: Bool { status == "protected" }
+
+    /// True when a supervisor owns the process lifecycle. Used only for the qualifier
+    /// line — it deliberately does not gate any action, because `/api/stop` stops the
+    /// service on purpose and nothing restarts the proxy automatically.
+    public var isServiceManaged: Bool {
+        (serviceInstalled ?? false) && (serviceEnabled ?? false)
+    }
+
+    /// The command to show the user when the proxy is not running.
+    public var manualStartCommand: String {
+        isServiceManaged ? "ocx service start" : "ocx start"
+    }
+}
+
+/// `GET /api/settings`. Note the absence of `defaultProvider` — it lives on
+/// `/api/config`, verified against the live key set.
+public struct ProxySettings: Decodable, Equatable, Sendable {
+    public let port: Int?
+    public let hostname: String?
+    public let streamMode: String?
+    public let codexAutoStart: Bool?
+}
+
+/// `GET /api/config` — the only source of `defaultProvider`.
+public struct ProxyConfigSummary: Decodable, Equatable, Sendable {
+    public let port: Int?
+    public let hostname: String?
+    public let defaultProvider: String?
+}
+
+/// Ranges accepted by `parseRange()` in `src/usage/summary.ts`.
+///
+/// Closed on purpose: the server silently degrades anything else to `30d`, so a
+/// stringly-typed range would let a caller ask for `24h`, receive thirty days of data,
+/// and label it wrongly.
+public enum UsageRange: String, Sendable, CaseIterable {
+    case today = "today"
+    case sevenDays = "7d"
+    case thirtyDays = "30d"
+    case all
+}
+
+public struct UsageSummary: Decodable, Equatable, Sendable {
+    public let requests: Int?
+    public let measuredRequests: Int?
+    public let estimatedRequests: Int?
+    public let totalTokens: Int?
+    public let inputTokens: Int?
+    public let outputTokens: Int?
+    public let estimatedCostUsd: Double?
+    public let coverageRatio: Double?
+
+    public var hasEstimates: Bool { (estimatedRequests ?? 0) > 0 }
+}
+
+public struct UsageDay: Decodable, Equatable, Sendable {
+    public let date: String
+    public let requests: Int?
+    public let totalTokens: Int?
+}
+
+public struct UsageReport: Decodable, Equatable, Sendable {
+    public let range: String?
+    public let surface: String?
+    public let generatedAt: Double?
+    public let summary: UsageSummary?
+    public let days: [UsageDay]?
+    public let models: [UsageModelRow]?
+    public let accounts: [UsageAccountRow]?
+
+    /// The range the server actually applied, which is not always the one requested.
+    public var effectiveRange: UsageRange? {
+        range.flatMap(UsageRange.init(rawValue:))
+    }
+
+    /// Header text driven by the response, never by the request.
+    public var rangeLabel: String {
+        switch effectiveRange {
+        case .today: return "TODAY"
+        case .sevenDays: return "LAST 7 DAYS"
+        case .thirtyDays: return "LAST 30 DAYS"
+        case .all: return "ALL TIME"
+        case nil: return "USAGE"
+        }
+    }
+
+    public var isEmpty: Bool {
+        isEmptyOrUnknown == true
+    }
+
+    /// Three states, not two: `nil` means the proxy did not report a request count, and
+    /// `true` means it explicitly reported zero. Collapsing those would let the UI print
+    /// "No requests" for data it simply does not have.
+    public var isEmptyOrUnknown: Bool? {
+        guard let requests = summary?.requests else { return nil }
+        return requests == 0
+    }
+}
+
+public struct UsageModelRow: Decodable, Equatable, Sendable {
+    public let provider: String?
+    public let model: String?
+    public let requests: Int?
+    public let totalTokens: Int?
+    public let estimatedCostUsd: Double?
+}
+
+public struct UsageAccountRow: Decodable, Equatable, Sendable {
+    public let accountLogLabel: String?
+    public let requests: Int?
+    public let totalTokens: Int?
+    public let estimatedCostUsd: Double?
+}
+
+public struct QuotaWindow: Decodable, Equatable, Sendable {
+    public let label: String?
+    public let percent: Double?
+    public let resetAt: Double?
+}
+
+public struct ProviderQuota: Decodable, Equatable, Sendable {
+    public let weeklyPercent: Double?
+    public let monthlyPercent: Double?
+    public let fiveHourPercent: Double?
+    public let weeklyResetAt: Double?
+    public let monthlyResetAt: Double?
+    public let fiveHourResetAt: Double?
+    public let customWindows: [QuotaWindow]?
+    public let updatedAt: Double?
+}
+
+public struct QuotaReport: Decodable, Equatable, Sendable {
+    public let provider: String
+    public let label: String?
+    public let source: String?
+    public let quota: ProviderQuota?
+}
+
+/// A provider-agnostic view of quota, since the window key differs per provider.
+public struct NormalizedQuota: Equatable, Sendable {
+    public let provider: String
+    public let providerLabel: String
+    public let percent: Double?
+    public let windowLabel: String
+    public let resetAt: Date?
+
+    public var hasPercent: Bool { percent != nil }
+}
+
+public extension QuotaReport {
+    /// Timestamps in this payload are not uniform: the live proxy returns
+    /// `weeklyResetAt` in seconds for `openai` and in milliseconds for `anthropic`,
+    /// within the same array. Disambiguate by magnitude — 1e12 is 2001 read as
+    /// milliseconds and year 33658 read as seconds, so the boundary is unambiguous for
+    /// any timestamp this app will ever see.
+    static func date(from value: Double?) -> Date? {
+        guard let value, value > 0 else { return nil }
+        let seconds = value >= 1_000_000_000_000 ? value / 1000 : value
+        return Date(timeIntervalSince1970: seconds)
+    }
+
+    /// Every window the provider reported, in display order.
+    ///
+    /// The live proxy is not uniform: `openai` and `xai` report a single named window,
+    /// `kimi` reports both `weeklyPercent` and `fiveHourPercent`, and `cursor` and
+    /// `google-antigravity` carry two `customWindows` each. Returning only one window
+    /// would silently hide real quota pressure.
+    func normalizedWindows() -> [NormalizedQuota] {
+        let name = label ?? provider
+        var windows: [NormalizedQuota] = []
+
+        func append(_ percent: Double?, _ windowLabel: String, _ resetAt: Double?) {
+            guard percent != nil || resetAt != nil else { return }
+            windows.append(NormalizedQuota(
+                provider: provider, providerLabel: name, percent: percent,
+                windowLabel: windowLabel, resetAt: Self.date(from: resetAt)
+            ))
+        }
+
+        append(quota?.fiveHourPercent, "5h", quota?.fiveHourResetAt)
+        append(quota?.weeklyPercent, "week", quota?.weeklyResetAt)
+        append(quota?.monthlyPercent, "month", quota?.monthlyResetAt)
+
+        for window in quota?.customWindows ?? [] {
+            append(window.percent, window.label ?? "window", window.resetAt)
+        }
+
+        return windows
+    }
+
+    /// The single window that best represents current pressure, for the compact row.
+    ///
+    /// Selection is **highest reported usage**, not longest horizon. Every window can
+    /// stop work: a provider at 99% of a five-hour limit and 10% of its monthly limit is
+    /// blocked right now, and showing the monthly 10% would paint that row green while
+    /// the user cannot make a request. Ties break toward the longer horizon, since that
+    /// is the one that will not recover on its own.
+    ///
+    /// Providers with no numeric window normalize to a nil percent so the UI renders an
+    /// em dash rather than a misleading zero.
+    func normalized() -> NormalizedQuota {
+        let name = label ?? provider
+        let windows = normalizedWindows()
+
+        // Longer horizons rank higher only as a tie-breaker.
+        func horizonRank(_ label: String) -> Int {
+            switch label {
+            case "month": return 3
+            case "week": return 2
+            case "5h": return 1
+            default: return 0
+            }
+        }
+
+        let measured = windows.filter(\.hasPercent)
+        let preferred = measured.max { lhs, rhs in
+            let left = lhs.percent ?? 0
+            let right = rhs.percent ?? 0
+            if left != right { return left < right }
+            return horizonRank(lhs.windowLabel) < horizonRank(rhs.windowLabel)
+        } ?? windows.first
+
+        return preferred ?? NormalizedQuota(
+            provider: provider, providerLabel: name, percent: nil,
+            windowLabel: "—", resetAt: nil
+        )
+    }
+}
+
+/// `GET /api/providers`. `hasApiKey` is a presence flag; the key never leaves the proxy.
+public struct ProviderSummary: Decodable, Equatable, Sendable {
+    public let name: String
+    public let adapter: String?
+    public let authMode: String?
+    public let hasApiKey: Bool?
+    public let disabled: Bool?
+
+    public var isEnabled: Bool { !(disabled ?? false) }
+}
diff --git a/app/Sources/MenuBarCore/ProxySnapshot.swift b/app/Sources/MenuBarCore/ProxySnapshot.swift
new file mode 100644
index 00000000000..30416a5a7f9
--- /dev/null
+++ b/app/Sources/MenuBarCore/ProxySnapshot.swift
@@ -0,0 +1,201 @@
+import Foundation
+
+/// Everything the UI can show, as one value.
+///
+/// Views are pure functions of this snapshot, so no view invents its own loading flag or
+/// decides independently whether data is missing.
+public enum ProxyState: Equatable, Sendable {
+    /// First fetch in flight; nothing is known yet.
+    case loading
+    case running(StartupHealth)
+    /// Connection refused — the proxy is not running.
+    case unreachable
+    /// 401 with no usable credential.
+    case unauthorized
+    /// Reachable but erroring. The message is proxy-free human text.
+    case degraded(String)
+
+    public var isRunning: Bool {
+        if case .running = self { return true }
+        return false
+    }
+
+    /// Short label shown beside the status dot. Colour is never the only carrier of
+    /// meaning, so every state has a word.
+    public var title: String {
+        switch self {
+        case .loading: return "Checking…"
+        case .running: return "Running"
+        case .unreachable: return "Stopped"
+        case .unauthorized: return "Needs API key"
+        case .degraded: return "Degraded"
+        }
+    }
+
+    public enum Tone: Sendable { case neutral, good, warning, bad }
+
+    public var tone: Tone {
+        switch self {
+        case .loading: return .neutral
+        case .running(let health): return health.isProtected ? .good : .warning
+        case .unreachable: return .bad
+        case .unauthorized: return .warning
+        case .degraded: return .warning
+        }
+    }
+
+    /// Secondary line under the title.
+    public var detail: String? {
+        switch self {
+        case .loading:
+            return nil
+        case .running(let health):
+            let parts = [health.status, health.protection]
+                .compactMap { $0 }
+                .filter { !$0.isEmpty && $0 != "none" }
+            return parts.isEmpty ? nil : parts.joined(separator: " · ")
+        case .unreachable:
+            return "The proxy is not running."
+        case .unauthorized:
+            return "This proxy requires an API key."
+        case .degraded(let message):
+            return message
+        }
+    }
+}
+
+/// What the user should do next. `loading` deliberately has none — there is nothing to
+/// act on yet — but every other non-running state names one.
+public enum NextAction: Equatable, Sendable {
+    case none
+    /// A command to run, shown as selectable text. The app never spawns processes.
+    case runCommand(String)
+    case addAPIKey
+    case retry
+}
+
+public struct ProxySnapshot: Equatable, Sendable {
+    public var state: ProxyState
+    public var endpoint: ProxyEndpoint
+    public var usage: UsageReport?
+    public var settings: CompanionSettings
+    public var settingsLoaded: Bool
+    public var today: UsageReport?
+    public var timeline: UsageTimeline?
+    public var timelineUpdated: Date?
+    public var quotas: [QuotaReport]
+    public var providers: [ProviderSummary]
+    public var defaultProvider: String?
+    public var lastUpdated: Date?
+    public var consecutiveFailures: Int
+    /// Remembered from the last successful health read, so a stopped proxy can still
+    /// tell the user the right start command for their install.
+    public var lastKnownStartCommand: String?
+    /// The proxy's own remediation hint (for example `ocx service install`). Displayed
+    /// as selectable text, never executed.
+    public var recommendedCommand: String?
+    /// Whether a section has actually been read, so "not fetched yet" and "the proxy
+    /// reported none" render differently.
+    public var providersLoaded: Bool
+    public var quotasLoaded: Bool
+    /// When the aggregation data last succeeded, which is NOT when health last
+    /// succeeded. Conflating them let a degraded state claim "showing data from 5s ago"
+    /// while holding no metrics at all.
+    public var usageUpdated: Date?
+
+    public init(
+        state: ProxyState = .loading,
+        endpoint: ProxyEndpoint,
+        usage: UsageReport? = nil,
+        settings: CompanionSettings = .defaults,
+        settingsLoaded: Bool = false,
+        today: UsageReport? = nil,
+        timeline: UsageTimeline? = nil,
+        timelineUpdated: Date? = nil,
+        quotas: [QuotaReport] = [],
+        providers: [ProviderSummary] = [],
+        defaultProvider: String? = nil,
+        lastUpdated: Date? = nil,
+        consecutiveFailures: Int = 0,
+        lastKnownStartCommand: String? = nil,
+        recommendedCommand: String? = nil,
+        providersLoaded: Bool = false,
+        quotasLoaded: Bool = false,
+        usageUpdated: Date? = nil
+    ) {
+        self.state = state
+        self.endpoint = endpoint
+        self.usage = usage
+        self.settings = settings
+        self.settingsLoaded = settingsLoaded
+        self.today = today
+        self.timeline = timeline
+        self.timelineUpdated = timelineUpdated
+        self.quotas = quotas
+        self.providers = providers
+        self.defaultProvider = defaultProvider
+        self.lastUpdated = lastUpdated
+        self.consecutiveFailures = consecutiveFailures
+        self.lastKnownStartCommand = lastKnownStartCommand
+        self.recommendedCommand = recommendedCommand
+        self.providersLoaded = providersLoaded
+        self.quotasLoaded = quotasLoaded
+        self.usageUpdated = usageUpdated
+    }
+
+    /// Whether the data sections are worth rendering at all.
+    ///
+    /// `degraded` keeps them: the plan requires stale-but-labelled over blank, because a
+    /// user who can still see last-known numbers with an explicit age is better served
+    /// than one staring at an empty panel.
+    public var showsData: Bool {
+        switch state {
+        case .running: return true
+        // Only claim stale data when data was actually loaded. Health succeeding while
+        // the popover was closed is not the same as having metrics to show.
+        case .degraded: return usage != nil || quotasLoaded
+        case .loading, .unreachable, .unauthorized: return false
+        }
+    }
+
+    /// Age of the DATA, not of the last health probe.
+    public var dataAge: Date? { usageUpdated }
+
+    /// True once the proxy has been read at least once, so `loading` can show skeletons
+    /// rather than empty copy.
+    public var hasEverLoaded: Bool { lastUpdated != nil }
+
+    public var nextAction: NextAction {
+        switch state {
+        case .loading: return .none
+        case .running: return .none
+        case .unreachable:
+            return .runCommand(lastKnownStartCommand ?? "ocx start")
+        case .unauthorized: return .addAPIKey
+        case .degraded: return .retry
+        }
+    }
+
+    /// One normalized row per provider for the compact quota list.
+    public var quotaRows: [NormalizedQuota] {
+        quotas.map { $0.normalized() }
+    }
+
+    public var visibleProviders: [ProviderSummary] {
+        providers.filter { !settings.hiddenProviders.contains($0.name) }
+    }
+
+    public var menuBarTitle: String? {
+        MenuBarTitle.render(settings: settings, today: today ?? usage, quotas: quotaRows)
+    }
+
+    public var todayRows: [UsageModelRow] { today?.models ?? [] }
+
+    /// Whether the metrics section should render its empty copy. `nil` means unknown,
+    /// which renders em dashes instead.
+    public var usageIsEmpty: Bool? { usage?.isEmptyOrUnknown }
+
+    public func canToggle(_ provider: ProviderSummary) -> Bool {
+        provider.name != defaultProvider
+    }
+}
diff --git a/app/Sources/MenuBarCore/UsageTimeline.swift b/app/Sources/MenuBarCore/UsageTimeline.swift
new file mode 100644
index 00000000000..6291272bcc2
--- /dev/null
+++ b/app/Sources/MenuBarCore/UsageTimeline.swift
@@ -0,0 +1,39 @@
+import Foundation
+
+public struct TimelineSeries: Decodable, Equatable, Sendable {
+    public let id: String
+    public let provider: String
+    public let model: String
+    public let accountLogLabel: String?
+    public let total: Double
+    public let points: [Double]
+}
+
+public struct UsageTimeline: Decodable, Equatable, Sendable {
+    public let start: Double
+    public let end: Double
+    public let bucketSeconds: Int
+    public let buckets: Int
+    public let metric: String
+    public let aggregation: String
+    public let grouping: String
+    public let series: [TimelineSeries]
+    public let availableModels: [String]
+    public let missingMeasurements: Int
+    public let truncated: Bool?
+
+    public var maxPoint: Double {
+        series.flatMap(\.points).max() ?? 0
+    }
+
+    public var stackedMax: Double {
+        guard buckets > 0 else { return 0 }
+        return (0..<buckets).map { index in
+            series.reduce(0) { $0 + ($1.points.indices.contains(index) ? $1.points[index] : 0) }
+        }.max() ?? 0
+    }
+
+    public var isEmpty: Bool {
+        series.allSatisfy { $0.total == 0 }
+    }
+}
diff --git a/app/Sources/MenuBarCore/WidgetSnapshot.swift b/app/Sources/MenuBarCore/WidgetSnapshot.swift
new file mode 100644
index 00000000000..6ea48c89783
--- /dev/null
+++ b/app/Sources/MenuBarCore/WidgetSnapshot.swift
@@ -0,0 +1,190 @@
+import Foundation
+import os
+#if canImport(WidgetKit)
+import WidgetKit
+#endif
+
+public struct WidgetSnapshot: Codable, Equatable, Sendable {
+    public struct Today: Codable, Equatable, Sendable {
+        public let requests: Int?
+        public let totalTokens: Int?
+        public let estimatedCostUsd: Double?
+
+        public init(requests: Int?, totalTokens: Int?, estimatedCostUsd: Double?) {
+            self.requests = requests
+            self.totalTokens = totalTokens
+            self.estimatedCostUsd = estimatedCostUsd
+        }
+    }
+
+    public struct Quota: Codable, Equatable, Sendable {
+        public let providerLabel: String
+        public let windowLabel: String
+        public let percent: Double?
+        public let resetAt: Double?
+
+        public init(providerLabel: String, windowLabel: String, percent: Double?, resetAt: Double?) {
+            self.providerLabel = providerLabel
+            self.windowLabel = windowLabel
+            self.percent = percent
+            self.resetAt = resetAt
+        }
+    }
+
+    public struct Chart: Codable, Equatable, Sendable {
+        public let start: Double
+        public let bucketSeconds: Int
+        public let style: String
+        public let series: [Series]
+
+        public init(start: Double, bucketSeconds: Int, style: String, series: [Series]) {
+            self.start = start
+            self.bucketSeconds = bucketSeconds
+            self.style = style
+            self.series = series
+        }
+
+        public struct Series: Codable, Equatable, Sendable {
+            public let id: String
+            public let points: [Double]
+
+            public init(id: String, points: [Double]) {
+                self.id = id
+                self.points = points
+            }
+        }
+    }
+
+    public let schemaVersion: Int
+    public let generatedAt: Double
+    public let state: String
+    public let stateTitle: String
+    public let detail: String?
+    public let endpointDisplay: String
+    public let menuTitle: String?
+    public let today: Today?
+    public let quotas: [Quota]
+    public let chart: Chart?
+    public let lastUpdated: Double?
+
+    public init(
+        schemaVersion: Int, generatedAt: Double, state: String, stateTitle: String, detail: String?,
+        endpointDisplay: String, menuTitle: String?, today: Today?, quotas: [Quota],
+        chart: Chart?, lastUpdated: Double?
+    ) {
+        self.schemaVersion = schemaVersion
+        self.generatedAt = generatedAt
+        self.state = state
+        self.stateTitle = stateTitle
+        self.detail = detail
+        self.endpointDisplay = endpointDisplay
+        self.menuTitle = menuTitle
+        self.today = today
+        self.quotas = quotas
+        self.chart = chart
+        self.lastUpdated = lastUpdated
+    }
+
+    public static func make(from snapshot: ProxySnapshot, now: Date = Date()) -> WidgetSnapshot {
+        let state: String
+        switch snapshot.state {
+        case .loading: state = "loading"
+        case .running: state = "running"
+        case .unreachable: state = "unreachable"
+        case .unauthorized: state = "unauthorized"
+        case .degraded: state = "degraded"
+        }
+        let report = snapshot.today ?? snapshot.usage
+        let today = report?.summary.map {
+            Today(requests: $0.requests, totalTokens: $0.totalTokens, estimatedCostUsd: $0.estimatedCostUsd)
+        }
+        let quotas = snapshot.quotaRows.map {
+            Quota(providerLabel: $0.providerLabel, windowLabel: $0.windowLabel, percent: $0.percent, resetAt: $0.resetAt?.timeIntervalSince1970)
+        }
+        let chart = snapshot.timeline.map {
+            Chart(
+                start: $0.start, bucketSeconds: $0.bucketSeconds, style: snapshot.settings.chartStyle.rawValue,
+                series: Array($0.series.prefix(6)).map { Chart.Series(id: $0.id, points: $0.points) }
+            )
+        }
+        return WidgetSnapshot(
+            schemaVersion: 1, generatedAt: now.timeIntervalSince1970,
+            state: state, stateTitle: snapshot.state.title, detail: snapshot.state.detail,
+            endpointDisplay: snapshot.endpoint.display, menuTitle: snapshot.menuBarTitle,
+            today: today, quotas: quotas, chart: chart,
+            lastUpdated: (snapshot.timelineUpdated ?? snapshot.usageUpdated)?.timeIntervalSince1970
+        )
+    }
+}
+
+public final class WidgetSnapshotStore: @unchecked Sendable {
+    private let fileManager: FileManager
+    private let homeDirectory: URL
+    private let widgetBundleID: String
+    private let lock = NSLock()
+    private var lastWritten: WidgetSnapshot?
+    private let logger = Logger(subsystem: "ai.opencodex.menubar", category: "widget-snapshot")
+    private var loggedFailures = Set<String>()
+
+    public init(
+        widgetBundleID: String = "com.opencodex.desktop.widget",
+        fileManager: FileManager = .default,
+        homeDirectory: URL = FileManager.default.homeDirectoryForCurrentUser
+    ) {
+        self.widgetBundleID = widgetBundleID
+        self.fileManager = fileManager
+        self.homeDirectory = homeDirectory
+    }
+
+    public var url: URL {
+        homeDirectory
+            .appendingPathComponent("Library/Containers/\(widgetBundleID)/Data/Library/Application Support/OpenCodex", isDirectory: true)
+            .appendingPathComponent("snapshot.json")
+    }
+
+    public func write(_ snapshot: WidgetSnapshot) throws {
+        let directory = url.deletingLastPathComponent()
+        try fileManager.createDirectory(at: directory, withIntermediateDirectories: true)
+        let data = try JSONEncoder().encode(snapshot)
+        let temporary = directory.appendingPathComponent(".snapshot-\(UUID().uuidString).tmp")
+        try data.write(to: temporary, options: .atomic)
+        try fileManager.setAttributes([.posixPermissions: 0o600], ofItemAtPath: temporary.path)
+        if fileManager.fileExists(atPath: url.path) { try fileManager.removeItem(at: url) }
+        try fileManager.moveItem(at: temporary, to: url)
+        Self.reloadTimelines()
+    }
+
+    public func writeIfChanged(_ snapshot: WidgetSnapshot) {
+        lock.lock()
+        let previous = lastWritten
+        if previous?.withoutGeneratedAt == snapshot.withoutGeneratedAt {
+            lock.unlock()
+            return
+        }
+        do {
+            try write(snapshot)
+            lastWritten = snapshot
+            lock.unlock()
+        } catch {
+            let key = String(describing: type(of: error))
+            if loggedFailures.insert(key).inserted { logger.error("Widget snapshot write failed: \(key, privacy: .public)") }
+            lock.unlock()
+        }
+    }
+
+    public static func reloadTimelines() {
+        #if canImport(WidgetKit)
+        if #available(macOS 14, *) { WidgetCenter.shared.reloadAllTimelines() }
+        #endif
+    }
+}
+
+private extension WidgetSnapshot {
+    var withoutGeneratedAt: WidgetSnapshot {
+        WidgetSnapshot(
+            schemaVersion: schemaVersion, generatedAt: 0, state: state, stateTitle: stateTitle,
+            detail: detail, endpointDisplay: endpointDisplay, menuTitle: menuTitle, today: today,
+            quotas: quotas, chart: chart, lastUpdated: lastUpdated
+        )
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/ActionSuite.swift b/app/Sources/MenuBarCoreTests/ActionSuite.swift
new file mode 100644
index 00000000000..8f11cc350f7
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/ActionSuite.swift
@@ -0,0 +1,356 @@
+import Foundation
+import MenuBarCore
+
+/// Write-action behaviour, especially the timing: `/api/stop` answers before it drains,
+/// so "returned 200" and "actually stopped" are different facts.
+enum ActionSuite {
+    private static func makeSession() -> URLSession {
+        let config = URLSessionConfiguration.ephemeral
+        config.protocolClasses = [StubProtocol.self]
+        return URLSession(configuration: config)
+    }
+
+    private static func sync<T>(_ operation: @escaping () async -> T) -> T {
+        let semaphore = DispatchSemaphore(value: 0)
+        let box = Box<T>()
+        Task {
+            box.value = await operation()
+            semaphore.signal()
+        }
+        semaphore.wait()
+        return box.value!
+    }
+
+    private final class Box<T>: @unchecked Sendable { var value: T? }
+    private struct NoCredentials: CredentialStore { func loadAPIKey() -> String? { nil } }
+
+    /// A clock the test drives, so the timeout path runs in milliseconds.
+    private final class FakeClock: @unchecked Sendable {
+        private let lock = NSLock()
+        private var current = Date(timeIntervalSince1970: 1_784_915_000)
+        func now() -> Date { lock.lock(); defer { lock.unlock() }; return current }
+        func advance(_ seconds: TimeInterval) {
+            lock.lock(); current = current.addingTimeInterval(seconds); lock.unlock()
+        }
+    }
+
+    private static func makeCoordinator(clock: FakeClock = FakeClock()) -> ActionCoordinator {
+        let client = ProxyClient(endpoint: .default, session: makeSession(), credentials: NoCredentials())
+        // Skip the real wall-clock wait, but advance the clock by the same amount so the
+        // deadline still expires.
+        return ActionCoordinator(
+            client: client,
+            sleeper: { seconds in clock.advance(seconds) },
+            now: { clock.now() }
+        )
+    }
+
+    private static func paths() -> [String] {
+        StubProtocol.recorded.compactMap { $0.url?.path }
+    }
+
+    static func run(_ t: TestRunner) {
+        // The proxy stops the launchd service on purpose, so a successful stop is
+        // reported as "you will have to start it again", not as a plain success.
+        t.test("stop: reports manual-start once the port stops answering") {
+            StubProtocol.reset([
+                .init(status: 200, body: "{}", urlError: nil),                    // POST /api/stop
+                .init(status: 0, body: "", urlError: .cannotConnectToHost),       // probe: gone
+            ])
+            let outcome = sync { await makeCoordinator().stop(startCommand: "ocx service start") }
+            t.equal(outcome, .requiresManualStart("ocx service start"))
+            t.expect(paths().first == "/api/stop", "stop called first, got \(paths())")
+        }
+
+        // A 200 that never drains must not be reported as success.
+        t.test("stop: a proxy that keeps answering is a failure, not a success") {
+            // The stub falls back to "connection refused" once its queue drains, which
+            // would look like a successful stop. Queue well past the poll count so the
+            // timeout path is what actually runs.
+            var responses: [StubProtocol.Response] = [.init(status: 200, body: "{}", urlError: nil)]
+            responses.append(contentsOf: Array(
+                repeating: .init(status: 200, body: #"{"port":10100}"#, urlError: nil),
+                count: 400
+            ))
+            StubProtocol.reset(responses)
+            let clock = FakeClock()
+            let outcome = sync { await makeCoordinator(clock: clock).stop(startCommand: "ocx start") }
+            if case .failed(let message) = outcome {
+                t.expect(message.contains("still responding"), "expected a timeout message, got \(message)")
+            } else {
+                t.expect(false, "expected .failed, got \(outcome)")
+            }
+        }
+
+        t.test("stop: an unreachable proxy fails without claiming it stopped anything") {
+            StubProtocol.reset([.init(status: 0, body: "", urlError: .cannotConnectToHost)])
+            let outcome = sync { await makeCoordinator().stop(startCommand: "ocx start") }
+            t.equal(outcome, .failed(ProxyError.unreachable.userMessage))
+        }
+
+        t.test("stop: a failure message never carries the response body") {
+            StubProtocol.reset([.init(status: 500, body: "SECRET-CONFIG", urlError: nil)])
+            let outcome = sync { await makeCoordinator().stop(startCommand: "ocx start") }
+            if case .failed(let message) = outcome {
+                t.expect(!message.contains("SECRET"), "leaked body: \(message)")
+            } else {
+                t.expect(false, "expected .failed, got \(outcome)")
+            }
+        }
+
+        t.test("provider: disabling sends exactly one PATCH and succeeds") {
+            StubProtocol.reset([.init(status: 200, body: "{}", urlError: nil)])
+            let outcome = sync {
+                await makeCoordinator().setProvider("anthropic", disabled: true, defaultProvider: "openai")
+            }
+            t.equal(outcome, .succeeded)
+            t.equal(StubProtocol.recorded.count, 1)
+            t.equal(StubProtocol.recorded.first?.httpMethod, "PATCH")
+            let url = StubProtocol.recorded.first?.url?.absoluteString ?? ""
+            t.expect(url.contains("name=anthropic"), "expected name=anthropic in \(url)")
+        }
+
+        // The proxy answers 400 for this, so the request is never sent at all.
+        t.test("provider: the default provider is refused before any request") {
+            StubProtocol.reset([.init(status: 200, body: "{}", urlError: nil)])
+            let outcome = sync {
+                await makeCoordinator().setProvider("openai", disabled: true, defaultProvider: "openai")
+            }
+            if case .failed(let message) = outcome {
+                t.expect(message.contains("default provider"), "expected an explanation, got \(message)")
+            } else {
+                t.expect(false, "expected .failed, got \(outcome)")
+            }
+            t.equal(StubProtocol.recorded.count, 0, "no request should be sent")
+        }
+
+        t.test("provider: enabling the default provider is allowed") {
+            StubProtocol.reset([.init(status: 200, body: "{}", urlError: nil)])
+            let outcome = sync {
+                await makeCoordinator().setProvider("openai", disabled: false, defaultProvider: "openai")
+            }
+            t.equal(outcome, .succeeded)
+        }
+
+        t.test("provider: a 400 from the proxy surfaces without quoting its body") {
+            StubProtocol.reset([.init(status: 400, body: "cannot disable the default provider", urlError: nil)])
+            let outcome = sync {
+                await makeCoordinator().setProvider("x", disabled: true, defaultProvider: "openai")
+            }
+            if case .failed(let message) = outcome {
+                t.expect(!message.contains("cannot disable"), "leaked body: \(message)")
+                t.expect(message.contains("refused"), "expected a refusal message, got \(message)")
+            } else {
+                t.expect(false, "expected .failed, got \(outcome)")
+            }
+        }
+
+        t.test("provider: an unreachable proxy fails cleanly") {
+            StubProtocol.reset([.init(status: 0, body: "", urlError: .cannotConnectToHost)])
+            let outcome = sync {
+                await makeCoordinator().setProvider("x", disabled: false, defaultProvider: nil)
+            }
+            t.equal(outcome, .failed(ProxyError.unreachable.userMessage))
+        }
+        // Was tautological: it built its own non-empty literals and then asserted they
+        // were non-empty. Now drives real failures and checks the message the user sees.
+        t.test("actions: every real failure path produces a usable message") {
+            StubProtocol.reset([.init(status: 0, body: "", urlError: .cannotConnectToHost)])
+            let unreachable = sync { await makeCoordinator().setProvider("x", disabled: false, defaultProvider: nil) }
+
+            StubProtocol.reset([.init(status: 400, body: "raw body", urlError: nil)])
+            let rejected = sync { await makeCoordinator().setProvider("x", disabled: true, defaultProvider: "openai") }
+
+            let guarded = sync { await makeCoordinator().setProvider("openai", disabled: true, defaultProvider: "openai") }
+
+            for outcome in [unreachable, rejected, guarded] {
+                guard case .failed(let message) = outcome else {
+                    t.expect(false, "expected .failed, got \(outcome)")
+                    continue
+                }
+                t.expect(!message.isEmpty, "empty failure message")
+                t.expect(message.hasSuffix(".") || message.hasSuffix("!"),
+                         "message should read as a sentence: \(message)")
+                t.expect(!message.contains("raw body"), "leaked body: \(message)")
+            }
+        }
+
+        // The stop response carries success:false when restoreNativeCodex() failed
+        // (src/server/management-api.ts:145-147). The proxy still shuts down, but native
+        // Codex is left pointing at a port that is closing.
+        t.test("stop: a restore failure is reported, not swallowed as success") {
+            StubProtocol.reset([
+                .init(status: 200, body: #"{"success":false,"message":"restore failed: /some/path"}"#, urlError: nil),
+                .init(status: 0, body: "", urlError: .cannotConnectToHost),
+            ])
+            let outcome = sync { await makeCoordinator().stop(startCommand: "ocx start") }
+            t.equal(outcome, .stoppedWithRestoreFailure("ocx start"))
+        }
+
+        t.test("stop: a success:true body reports the ordinary manual-start outcome") {
+            StubProtocol.reset([
+                .init(status: 200, body: #"{"success":true,"message":"ok"}"#, urlError: nil),
+                .init(status: 0, body: "", urlError: .cannotConnectToHost),
+            ])
+            t.equal(sync { await makeCoordinator().stop(startCommand: "ocx start") },
+                    .requiresManualStart("ocx start"))
+        }
+
+        // Only a refused connection proves the proxy is gone. A 500 or an undecodable
+        // 200 means an HTTP server is still listening.
+        t.test("stop: a 500 during polling is not mistaken for a stopped proxy") {
+            var responses: [StubProtocol.Response] = [.init(status: 200, body: "{}", urlError: nil)]
+            responses.append(contentsOf: Array(
+                repeating: .init(status: 500, body: "", urlError: nil), count: 400))
+            StubProtocol.reset(responses)
+            let clock = FakeClock()
+            let outcome = sync { await makeCoordinator(clock: clock).stop(startCommand: "ocx start") }
+            if case .failed(let message) = outcome {
+                t.expect(message.contains("still responding"), "expected a timeout, got \(message)")
+            } else {
+                t.expect(false, "expected .failed, got \(outcome)")
+            }
+        }
+
+        t.test("stop: an undecodable 200 during polling still counts as reachable") {
+            var responses: [StubProtocol.Response] = [.init(status: 200, body: "{}", urlError: nil)]
+            responses.append(contentsOf: Array(
+                repeating: .init(status: 200, body: "not json", urlError: nil), count: 400))
+            StubProtocol.reset(responses)
+            let clock = FakeClock()
+            let outcome = sync { await makeCoordinator(clock: clock).stop(startCommand: "ocx start") }
+            if case .failed = outcome {
+                t.expect(true, "timed out rather than claiming success")
+            } else {
+                t.expect(false, "expected .failed, got \(outcome)")
+            }
+        }
+
+        t.test("provider: a second write while one is in flight is refused, not raced") {
+            StubProtocol.reset([
+                .init(status: 200, body: "{}", urlError: nil),
+                .init(status: 200, body: "{}", urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            let outcomes: [ActionOutcome] = sync {
+                async let first = coordinator.setProvider("x", disabled: true, defaultProvider: nil)
+                async let second = coordinator.setProvider("x", disabled: false, defaultProvider: nil)
+                return await [first, second]
+            }
+            let refused = outcomes.filter { if case .failed = $0 { return true }; return false }
+            t.equal(refused.count, 1, "exactly one of the two concurrent writes is refused")
+        }
+
+        t.test("provider: writes to different providers are not blocked by each other") {
+            StubProtocol.reset([
+                .init(status: 200, body: "{}", urlError: nil),
+                .init(status: 200, body: "{}", urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            let outcomes: [ActionOutcome] = sync {
+                async let a = coordinator.setProvider("a", disabled: true, defaultProvider: nil)
+                async let b = coordinator.setProvider("b", disabled: true, defaultProvider: nil)
+                return await [a, b]
+            }
+            t.equal(outcomes, [.succeeded, .succeeded])
+        }
+
+        // The distinction that matters: only a refused connection proves the proxy is
+        // gone. Collapsing timeouts into "unreachable" is what made a stop report as
+        // confirmed while the proxy was still running.
+        t.test("liveness: only a refused connection reads as gone") {
+            let cases: [(URLError.Code, ProxyClient.Liveness, String)] = [
+                (.cannotConnectToHost, .refused, "connection refused"),
+                (.timedOut, .indeterminate, "timeout"),
+                (.networkConnectionLost, .indeterminate, "socket dropped"),
+                (.cannotFindHost, .indeterminate, "host lookup"),
+                (.notConnectedToInternet, .indeterminate, "no network"),
+            ]
+            for (code, expected, label) in cases {
+                StubProtocol.reset([.init(status: 0, body: "", urlError: code)])
+                let client = ProxyClient(endpoint: .default, session: makeSession(), credentials: NoCredentials())
+                t.equal(sync { await client.liveness() }, expected, label)
+            }
+        }
+
+        t.test("liveness: any HTTP answer proves the port is occupied") {
+            for status in [200, 401, 403, 500] {
+                let body = status == 200 ? #"{"port":10100}"# : ""
+                StubProtocol.reset([
+                    .init(status: status, body: body, urlError: nil),
+                    .init(status: status, body: body, urlError: nil),
+                ])
+                let client = ProxyClient(endpoint: .default, session: makeSession(),
+                                         credentials: StubCredentialsFixed(key: "k"))
+                t.equal(sync { await client.liveness() }, .reachable, "status \(status)")
+            }
+        }
+
+        t.test("liveness: an undecodable 200 is reachable, not gone") {
+            StubProtocol.reset([.init(status: 200, body: "not json at all", urlError: nil)])
+            let client = ProxyClient(endpoint: .default, session: makeSession(), credentials: NoCredentials())
+            t.equal(sync { await client.liveness() }, .reachable)
+        }
+
+        // A timeout must not end the stop as a confirmed success.
+        t.test("stop: a timeout during polling never confirms the stop") {
+            var responses: [StubProtocol.Response] = [.init(status: 200, body: "{}", urlError: nil)]
+            responses.append(contentsOf: Array(
+                repeating: .init(status: 0, body: "", urlError: .timedOut), count: 400))
+            StubProtocol.reset(responses)
+            let clock = FakeClock()
+            let outcome = sync { await makeCoordinator(clock: clock).stop(startCommand: "ocx start") }
+            if case .failed(let message) = outcome {
+                t.expect(message.contains("could not be confirmed"),
+                         "expected an inconclusive message, got \(message)")
+            } else {
+                t.expect(false, "expected .failed, got \(outcome)")
+            }
+        }
+
+        // A 401 already answers "is anything listening". Retrying it through the normal
+        // credential path spent a second full timeout and could downgrade a
+        // known-reachable result to indeterminate if the retry failed.
+        t.test("liveness: a 401 answers immediately without a credential retry") {
+            StubProtocol.reset([
+                .init(status: 401, body: "", urlError: nil),
+                .init(status: 0, body: "", urlError: .timedOut),   // must never be used
+            ])
+            let client = ProxyClient(endpoint: .default, session: makeSession(),
+                                     credentials: StubCredentialsFixed(key: "stored-key"))
+            t.equal(sync { await client.liveness() }, .reachable)
+            t.equal(StubProtocol.recorded.count, 1, "liveness must be a single attempt")
+        }
+
+        t.test("liveness: the probe honours a caller-supplied timeout") {
+            StubProtocol.reset([.init(status: 200, body: #"{"port":10100}"#, urlError: nil)])
+            let client = ProxyClient(endpoint: .default, session: makeSession(), credentials: NoCredentials())
+            _ = sync { await client.liveness(timeout: 0.25) }
+            t.equal(StubProtocol.recorded.first?.timeoutInterval, 0.25)
+        }
+
+        // The final probe must not overrun the stop deadline by its own timeout.
+        t.test("stop: the last probe is capped to the remaining deadline") {
+            var responses: [StubProtocol.Response] = [.init(status: 200, body: "{}", urlError: nil)]
+            responses.append(contentsOf: Array(
+                repeating: .init(status: 200, body: #"{"port":10100}"#, urlError: nil), count: 400))
+            StubProtocol.reset(responses)
+            let clock = FakeClock()
+            _ = sync { await makeCoordinator(clock: clock).stop(startCommand: "ocx start") }
+
+            // Every liveness probe after the POST must request no more than 1.5s, and
+            // the last must be clamped to whatever remained.
+            let probes = StubProtocol.recorded.dropFirst()
+            t.expect(!probes.isEmpty, "expected liveness probes")
+            for probe in probes {
+                t.expect(probe.timeoutInterval <= 1.5,
+                         "probe timeout \(probe.timeoutInterval) exceeds the cap")
+            }
+        }
+    }
+
+    private struct StubCredentialsFixed: CredentialStore {
+        let key: String?
+        func loadAPIKey() -> String? { key }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/CompanionSettingsSuite.swift b/app/Sources/MenuBarCoreTests/CompanionSettingsSuite.swift
new file mode 100644
index 00000000000..bed663b8e2d
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/CompanionSettingsSuite.swift
@@ -0,0 +1,27 @@
+import Foundation
+import MenuBarCore
+
+enum CompanionSettingsSuite {
+    static func run(_ t: TestRunner) {
+        let decoder = JSONDecoder()
+        t.test("companion settings: empty JSON uses defaults") {
+            let settings = try decoder.decode(CompanionSettings.self, from: Data("{}".utf8))
+            t.equal(settings, .defaults)
+        }
+        t.test("companion settings: unknown enum uses its default") {
+            let settings = try decoder.decode(CompanionSettings.self, from: Data(#"{"menuBarMetric":"future","chartStyle":"future","tokenMetric":"future","aggregation":"future","chartGrouping":"future"}"#.utf8))
+            t.equal(settings.menuBarMetric, .tokens)
+            t.equal(settings.chartStyle, .line)
+            t.equal(settings.tokenMetric, .total)
+            t.equal(settings.aggregation, .sum)
+            t.equal(settings.chartGrouping, .model)
+        }
+        t.test("companion settings: full payload decodes") {
+            let settings = try decoder.decode(CompanionSettings.self, from: Data(#"{"menuBarMetric":"quota","menuBarTemplate":"{requests}","showToday":false,"showChart":false,"showModels":false,"showCost":false,"showAccounts":false,"chartHours":72,"bucketMinutes":180,"chartStyle":"stackedBar","tokenMetric":"cached","aggregation":"max","chartGrouping":"modelAccount","models":["openai/gpt"],"hiddenProviders":["openai"]}"#.utf8))
+            t.equal(settings.chartHours, 72)
+            t.equal(settings.chartStyle, .stackedBar)
+            t.equal(settings.models, ["openai/gpt"])
+            t.equal(settings.hiddenProviders, ["openai"])
+        }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/DiscoverySuite.swift b/app/Sources/MenuBarCoreTests/DiscoverySuite.swift
new file mode 100644
index 00000000000..e8aa2acf1bd
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/DiscoverySuite.swift
@@ -0,0 +1,82 @@
+import Foundation
+import MenuBarCore
+
+enum DiscoverySuite {
+    static func run(_ t: TestRunner) {
+        let root = URL(fileURLWithPath: NSTemporaryDirectory())
+            .appendingPathComponent("ocx-discovery-\(UUID().uuidString)", isDirectory: true)
+        try? FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: root) }
+
+        func writeRecord(_ contents: String) throws {
+            try contents.write(
+                to: root.appendingPathComponent("runtime-port.json"),
+                atomically: true,
+                encoding: .utf8
+            )
+        }
+
+        t.test("discovery: honours a valid record") {
+            try writeRecord(#"{"pid": 14582, "port": 10100}"#)
+            t.equal(ProxyDiscovery.resolve(configDirectory: root).port, 10100)
+        }
+
+        t.test("discovery: honours a non-default port") {
+            try writeRecord(#"{"pid": 1, "port": 18080}"#)
+            t.equal(ProxyDiscovery.resolve(configDirectory: root).port, 18080)
+        }
+
+        t.test("discovery: a record without pid still resolves") {
+            try writeRecord(#"{"port": 10250}"#)
+            t.equal(ProxyDiscovery.resolve(configDirectory: root).port, 10250)
+        }
+
+        t.test("discovery: malformed JSON falls back to the default port") {
+            try writeRecord("{not json at all")
+            t.equal(ProxyDiscovery.resolve(configDirectory: root).port, ProxyDiscovery.defaultPort)
+        }
+
+        t.test("discovery: out-of-range ports fall back to the default") {
+            for invalid in ["0", "70000", "-1"] {
+                try writeRecord(#"{"port": \#(invalid)}"#)
+                t.equal(
+                    ProxyDiscovery.resolve(configDirectory: root).port,
+                    ProxyDiscovery.defaultPort,
+                    "port \(invalid)"
+                )
+            }
+        }
+
+        t.test("discovery: a missing file falls back to the default port") {
+            let empty = root.appendingPathComponent("empty-\(UUID().uuidString)", isDirectory: true)
+            try FileManager.default.createDirectory(at: empty, withIntermediateDirectories: true)
+            t.equal(ProxyDiscovery.resolve(configDirectory: empty).port, ProxyDiscovery.defaultPort)
+        }
+
+        // The record may carry a hostname, but the app must never follow it: the port
+        // file is a convenience, not a redirection mechanism.
+        t.test("discovery: host stays loopback even when the record names another host") {
+            try writeRecord(#"{"pid": 1, "port": 10100, "hostname": "10.0.0.5"}"#)
+            let endpoint = ProxyDiscovery.resolve(configDirectory: root)
+            t.equal(endpoint.host, "127.0.0.1")
+            t.equal(endpoint.baseURL.absoluteString, "http://127.0.0.1:10100")
+        }
+
+        t.test("discovery: OPENCODEX_HOME overrides the default directory") {
+            let resolved = ProxyDiscovery.configDirectory(
+                environment: ["OPENCODEX_HOME": root.path],
+                home: URL(fileURLWithPath: "/nonexistent")
+            )
+            t.equal(resolved.path, root.path)
+        }
+
+        t.test("discovery: a blank OPENCODEX_HOME falls back to the home directory") {
+            let home = URL(fileURLWithPath: "/Users/example")
+            let resolved = ProxyDiscovery.configDirectory(
+                environment: ["OPENCODEX_HOME": "   "],
+                home: home
+            )
+            t.equal(resolved.path, home.appendingPathComponent(".opencodex").path)
+        }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/FormattingSuite.swift b/app/Sources/MenuBarCoreTests/FormattingSuite.swift
new file mode 100644
index 00000000000..00b816cdeb9
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/FormattingSuite.swift
@@ -0,0 +1,77 @@
+import Foundation
+import MenuBarCore
+
+/// Magnitudes are taken from the live proxy capture in 002_api_surface.md.
+enum FormattingSuite {
+    static func run(_ t: TestRunner) {
+        t.test("format: counts group below 10k and suffix above") {
+            t.equal(Format.count(0), "0")
+            t.equal(Format.count(1_746), "1,746")
+            t.equal(Format.count(9_999), "9,999")
+            t.equal(Format.count(232_507), "233K")
+            t.equal(Format.count(1_200_000), "1.20M")
+        }
+
+        // Rounding can push a value across its own unit boundary: 999_999 scales to
+        // 999.999K and must promote to 1.00M rather than render "1000K".
+        t.test("format: values promote at suffix rollover boundaries") {
+            t.equal(Format.count(999_999), "1.00M")
+            t.equal(Format.count(999_499), "999K")
+        t.equal(Format.tokens(999_999_999), "1B")
+        t.equal(Format.tokens(999_999_999_999), "1T")
+            t.equal(Format.cost(999_999), "$1.00M")
+        }
+
+        t.test("format: exact unit thresholds render as the new unit") {
+        t.equal(Format.tokens(1_000), "1K")
+        t.equal(Format.tokens(1_000_000), "1M")
+        t.equal(Format.tokens(1_000_000_000), "1B")
+        }
+
+        t.test("format: tokens are suffixed at scale") {
+            t.equal(Format.tokens(999), "999")
+        t.equal(Format.tokens(12_400_000), "12M")
+        t.equal(Format.tokens(36_536_664_705), "37B")
+        }
+
+        t.test("format: cost switches to a suffix above one thousand") {
+            t.equal(Format.cost(8.21), "$8.21")
+            t.equal(Format.cost(999.99), "$999.99")
+            t.equal(Format.cost(34_018.25204647066), "$34.0K")
+        }
+
+        // Unknown and zero are different facts. Rendering nil as "0" is the fake-data
+        // tell that 003 section 6 bans.
+        t.test("format: nil renders an em dash while zero renders zero") {
+            t.equal(Format.count(nil), "—")
+            t.equal(Format.tokens(nil), "—")
+            t.equal(Format.cost(nil), "—")
+            t.equal(Format.percent(nil), "—")
+            t.equal(Format.count(0), "0")
+            t.equal(Format.cost(0), "$0.00")
+        }
+
+        t.test("format: percent rounds") {
+            t.equal(Format.percent(44), "44%")
+            t.equal(Format.percent(86.82666666666667), "87%")
+            t.equal(Format.percent(9.976811594202898), "10%")
+        }
+
+        t.test("format: reset countdowns are coarse") {
+            let now = Date(timeIntervalSince1970: 1_784_915_000)
+            t.equal(Format.resetsIn(now.addingTimeInterval(60 * 30), now: now), "30m")
+            t.equal(Format.resetsIn(now.addingTimeInterval(3600 * 5), now: now), "5h")
+            t.equal(Format.resetsIn(now.addingTimeInterval(86_400 * 3 + 3600 * 4), now: now), "3d 4h")
+            t.equal(Format.resetsIn(now.addingTimeInterval(-60), now: now), "expired")
+            t.equal(Format.resetsIn(nil), "—")
+        }
+
+        t.test("format: staleness ages read naturally") {
+            let now = Date(timeIntervalSince1970: 1_784_915_000)
+            t.equal(Format.age(now.addingTimeInterval(-10), now: now), "just now")
+            t.equal(Format.age(now.addingTimeInterval(-120), now: now), "2m ago")
+            t.equal(Format.age(now.addingTimeInterval(-7200), now: now), "2h ago")
+            t.equal(Format.age(nil), "—")
+        }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/Harness.swift b/app/Sources/MenuBarCoreTests/Harness.swift
new file mode 100644
index 00000000000..0deb1d6ae46
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/Harness.swift
@@ -0,0 +1,105 @@
+import Foundation
+
+/// A dependency-free assertion harness.
+///
+/// Why not XCTest or swift-testing: neither ships a usable runtime in Xcode Command Line
+/// Tools. `import XCTest` fails module resolution outright, and swift-testing compiles
+/// but cannot `dlopen` `Testing.framework` at run time. Requiring a full Xcode install to
+/// run the unit tests of a menu bar companion would put the tests out of reach for most
+/// contributors and for any CI runner without Xcode selected.
+///
+/// This harness is ~60 lines, runs as a plain executable, and prints TAP-ish output that
+/// both a human and CI can read. If the package ever gains a full-Xcode requirement for
+/// other reasons, migrating these cases to swift-testing is mechanical.
+public struct TestFailure {
+    let test: String
+    let message: String
+    let file: String
+    let line: Int
+}
+
+public final class TestRunner {
+    private(set) var passed = 0
+    private(set) var failures: [TestFailure] = []
+    private var current = "<none>"
+
+    public init() {}
+
+    public func test(_ name: String, _ body: () throws -> Void) {
+        current = name
+        let failuresBefore = failures.count
+        do {
+            try body()
+        } catch {
+            failures.append(TestFailure(test: name, message: "threw \(error)", file: #file, line: #line))
+            print("FAIL — \(name): threw \(error)")
+            return
+        }
+        // A case that recorded an expectation failure is not a pass, even though its
+        // body returned normally.
+        if failures.count == failuresBefore {
+            passed += 1
+            print("ok — \(name)")
+        }
+    }
+
+    public func expect(
+        _ condition: Bool,
+        _ message: @autoclosure () -> String,
+        file: String = #file,
+        line: Int = #line
+    ) {
+        guard !condition else { return }
+        let failure = TestFailure(test: current, message: message(), file: file, line: line)
+        failures.append(failure)
+        print("FAIL — \(current): \(failure.message) (\(URL(fileURLWithPath: file).lastPathComponent):\(line))")
+    }
+
+    public func equal<T: Equatable>(
+        _ actual: T,
+        _ expected: T,
+        _ label: String = "",
+        file: String = #file,
+        line: Int = #line
+    ) {
+        expect(
+            actual == expected,
+            "\(label.isEmpty ? "" : label + ": ")expected \(expected), got \(actual)",
+            file: file,
+            line: line
+        )
+    }
+
+    public func notNil<T>(
+        _ value: T?,
+        _ label: String,
+        file: String = #file,
+        line: Int = #line
+    ) -> T? {
+        expect(value != nil, "\(label) should not be nil", file: file, line: line)
+        return value
+    }
+
+    public func isNil<T>(
+        _ value: T?,
+        _ label: String,
+        file: String = #file,
+        line: Int = #line
+    ) {
+        expect(value == nil, "\(label) should be nil, got \(String(describing: value))", file: file, line: line)
+    }
+
+    /// Prints the summary and returns the process exit code.
+    public func summarize() -> Int32 {
+        print("")
+        if failures.isEmpty {
+            print("\(passed) passed, 0 failed")
+            return 0
+        }
+        print("\(passed) passed, \(failures.count) FAILED")
+        for failure in failures {
+            print("  - \(failure.test): \(failure.message)")
+        }
+        return 1
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/MenuBarTitleSuite.swift b/app/Sources/MenuBarCoreTests/MenuBarTitleSuite.swift
new file mode 100644
index 00000000000..286502ac91c
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/MenuBarTitleSuite.swift
@@ -0,0 +1,36 @@
+import Foundation
+import MenuBarCore
+
+enum MenuBarTitleSuite {
+    private static let reportJSON = #"{"range":"today","summary":{"requests":12,"totalTokens":3456,"inputTokens":1000,"outputTokens":2000,"estimatedCostUsd":1.25}}"#
+
+    static func run(_ t: TestRunner) {
+        let report = try! JSONDecoder().decode(UsageReport.self, from: Data(reportJSON.utf8))
+        for metric in [CompanionSettings.MenuBarMetric.requests, .tokens, .cost] {
+            t.test("menu title: \(metric.rawValue) metric") {
+                let settings = CompanionSettings(menuBarMetric: metric)
+                t.expect(MenuBarTitle.render(settings: settings, today: report, quotas: []) != nil, "title")
+            }
+        }
+        t.test("menu title: quota picks the lowest percent") {
+            let settings = CompanionSettings(menuBarMetric: .quota)
+            let quotas = try! JSONDecoder().decode([QuotaReport].self, from: Data(#"[{"provider":"a","quota":{"weeklyPercent":80}},{"provider":"b","quota":{"weeklyPercent":20}}]"#.utf8)).map { $0.normalized() }
+            t.equal(MenuBarTitle.render(settings: settings, today: report, quotas: quotas), "20%")
+        }
+        t.test("menu title: template replaces placeholders") {
+            let settings = CompanionSettings(menuBarTemplate: "{requests}/{totalTokens}/{costUsd}")
+            t.equal(MenuBarTitle.render(settings: settings, today: report, quotas: []), "12/3K/$1.25")
+        }
+        t.test("menu title: none is nil and unknowns are em dashes") {
+            t.isNil(MenuBarTitle.render(settings: CompanionSettings(menuBarMetric: .none), today: report, quotas: []), "none")
+            let settings = CompanionSettings(menuBarTemplate: "{inputTokens}")
+            t.equal(MenuBarTitle.render(settings: settings, today: nil, quotas: []), "—")
+        }
+        t.test("menu title: long output is truncated") {
+            let settings = CompanionSettings(menuBarTemplate: "012345678901234567890123456789")
+            let title = MenuBarTitle.render(settings: settings, today: report, quotas: [])
+            t.equal(title?.count, 24)
+            t.expect(title?.hasSuffix("…") == true, "ellipsis")
+        }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/ModelDecodingSuite.swift b/app/Sources/MenuBarCoreTests/ModelDecodingSuite.swift
new file mode 100644
index 00000000000..0ec0012e621
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/ModelDecodingSuite.swift
@@ -0,0 +1,258 @@
+import Foundation
+import MenuBarCore
+
+/// Fixtures are verbatim captures from the live proxy on 2026-07-25, recorded in
+/// devlog/_plan/260725_macos_menubar_app/002_api_surface.md. Hand-written fixtures would
+/// only prove the models decode themselves.
+enum ModelDecodingSuite {
+    private static func decode<T: Decodable>(_ type: T.Type, _ json: String) throws -> T {
+        try JSONDecoder().decode(type, from: Data(json.utf8))
+    }
+
+    private struct Envelope: Decodable { let reports: [QuotaReport]? }
+
+    private static let liveHealth = """
+    {"routingKind":"opencodex-local","autostartEnabled":false,"serviceInstalled":true,
+     "serviceViable":true,"serviceEnabled":true,"serviceRunning":true,"serviceStale":false,
+     "serviceConflict":false,"serviceSupported":true,"shimInstalled":false,
+     "shimHealthy":false,"platform":"darwin","diagnosticStale":true,"routingInjected":true,
+     "localRoutingDependency":true,"status":"at-risk","rebootSafe":false,"protection":"none",
+     "shimCoverage":"none","recommendedCommand":"ocx service install",
+     "commands":{"installService":"ocx service install","installShim":"ocx codex-shim install",
+     "restoreNative":"ocx restore"}}
+    """
+
+    private static let liveQuotas = """
+    {"generatedAt":1784915336899,"reports":[
+      {"provider":"openai","label":"OpenAI (Codex login)","source":"chatgpt:wham",
+       "quota":{"updatedAt":1784915090763,"weeklyPercent":44,"weeklyResetAt":1785258443,
+                "resetCredits":3}},
+      {"provider":"anthropic","label":"Anthropic Claude","source":"anthropic:oauth-usage",
+       "quota":{"weeklyPercent":58,"weeklyResetAt":1785265199718,
+                "customWindows":[{"label":"5h","percent":1,"resetAt":1784928599718}]}},
+      {"provider":"xai","label":"xAI Grok","source":"xai:grok-billing",
+       "quota":{"monthlyPercent":86.82666666666667,"monthlyResetAt":1785542400000}}]}
+    """
+
+    static func run(_ t: TestRunner) {
+        t.test("health: decodes the live startup-health payload") {
+            let health = try decode(StartupHealth.self, liveHealth)
+            t.equal(health.status, "at-risk")
+            t.equal(health.platform, "darwin")
+            t.equal(health.recommendedCommand, "ocx service install")
+            t.equal(health.isProtected, false)
+            t.equal(health.isServiceManaged, true)
+            t.equal(health.manualStartCommand, "ocx service start")
+        }
+
+        t.test("health: an unknown status string decodes without throwing") {
+            let health = try decode(StartupHealth.self, #"{"status":"some-future-state"}"#)
+            t.equal(health.status, "some-future-state")
+            t.equal(health.isProtected, false)
+        }
+
+        t.test("health: without service fields it is not service-managed") {
+            let health = try decode(StartupHealth.self, #"{"status":"protected"}"#)
+            t.equal(health.isProtected, true)
+            t.equal(health.isServiceManaged, false)
+            t.equal(health.manualStartCommand, "ocx start")
+        }
+
+        // The live /api/settings key set contains no defaultProvider. Decoding must
+        // succeed anyway — an earlier plan draft expected the field here and was wrong.
+        t.test("settings: decodes without a defaultProvider field") {
+            let json = """
+            {"codexAutoStart":false,"port":10100,"hostname":"127.0.0.1","streamMode":"auto",
+             "startupHealth":{"status":"protected"},"codexRuntime":{}}
+            """
+            let settings = try decode(ProxySettings.self, json)
+            t.equal(settings.port, 10100)
+            t.equal(settings.hostname, "127.0.0.1")
+            t.equal(settings.streamMode, "auto")
+        }
+
+        t.test("config: supplies defaultProvider") {
+            let json = """
+            {"port":10100,"hostname":"127.0.0.1","defaultProvider":"openai",
+             "codexAutoStart":false,"websockets":{},"providers":{}}
+            """
+            t.equal(try decode(ProxyConfigSummary.self, json).defaultProvider, "openai")
+        }
+
+        t.test("usage: decodes the live summary at real magnitudes") {
+            let json = """
+            {"range":"30d","surface":"all","since":1782323333603,"generatedAt":1784915333603,
+             "summary":{"requests":232507,"measuredRequests":225380,"estimatedRequests":14618,
+              "inputTokens":33521662469,"outputTokens":127401110,"totalTokens":36536664705,
+              "coverageRatio":0.969347159440361,"estimatedCostUsd":34018.25204647066},
+             "days":[{"date":"2026-06-28","requests":1746,"totalTokens":0,"models":[]}]}
+            """
+            let report = try decode(UsageReport.self, json)
+            t.equal(report.summary?.requests, 232_507)
+            t.equal(report.summary?.totalTokens, 36_536_664_705)
+            t.equal(report.effectiveRange, .thirtyDays)
+            t.equal(report.rangeLabel, "LAST 30 DAYS")
+            t.equal(report.summary?.hasEstimates, true)
+            t.equal(report.isEmpty, false)
+        }
+
+        // The server silently degrades an unrecognized range to 30d, so the label must
+        // follow the response and never the request.
+        t.test("usage: an unknown range degrades to a neutral label") {
+            let report = try decode(UsageReport.self, #"{"range":"24h"}"#)
+            t.isNil(report.effectiveRange, "effectiveRange for 24h")
+            t.equal(report.rangeLabel, "USAGE")
+        }
+
+        t.test("usage: zero requests reads as empty") {
+            let report = try decode(UsageReport.self, #"{"range":"7d","summary":{"requests":0}}"#)
+            t.equal(report.isEmpty, true)
+            t.equal(report.isEmptyOrUnknown, true)
+        }
+
+        // Unknown and zero are different facts: an omitted count must not render as
+        // "No requests".
+        t.test("usage: an omitted request count is unknown, not empty") {
+            let report = try decode(UsageReport.self, #"{"range":"7d","summary":{"totalTokens":5}}"#)
+            t.isNil(report.isEmptyOrUnknown, "isEmptyOrUnknown for an omitted count")
+            t.equal(report.isEmpty, false, "isEmpty must not claim empty for unknown")
+        }
+
+        t.test("usage: the range enum is closed") {
+            t.isNil(UsageRange(rawValue: "24h"), "UsageRange(24h)")
+            t.equal(UsageRange.allCases.map(\.rawValue), ["today", "7d", "30d", "all"])
+        }
+
+        // The decisive trap: openai sends weeklyResetAt in SECONDS (1785258443) while
+        // anthropic sends MILLISECONDS (1785265199718) in the same array.
+        t.test("quotas: mixed second and millisecond timestamps both resolve to 2026") {
+            let reports = try decode(Envelope.self, liveQuotas).reports ?? []
+            t.equal(reports.count, 3)
+            let calendar = Calendar(identifier: .gregorian)
+            for report in reports {
+                let normalized = report.normalized()
+                guard let date = t.notNil(normalized.resetAt, "\(report.provider) resetAt") else { continue }
+                t.equal(calendar.component(.year, from: date), 2026, "\(report.provider) year")
+            }
+        }
+
+        t.test("quotas: normalization picks the right window per provider") {
+            let reports = try decode(Envelope.self, liveQuotas).reports ?? []
+            let byProvider = Dictionary(uniqueKeysWithValues: reports.map { ($0.provider, $0.normalized()) })
+            t.equal(byProvider["openai"]?.windowLabel, "week")
+            t.equal(byProvider["openai"]?.percent, 44)
+            t.equal(byProvider["anthropic"]?.windowLabel, "week")
+            t.equal(byProvider["xai"]?.windowLabel, "month")
+            t.equal(byProvider["xai"]?.providerLabel, "xAI Grok")
+        }
+
+        t.test("quotas: a custom-window-only quota uses its own label") {
+            let json = """
+            {"provider":"p","quota":{"customWindows":[{"label":"5h","percent":12,"resetAt":1784928599718}]}}
+            """
+            let normalized = try decode(QuotaReport.self, json).normalized()
+            t.equal(normalized.windowLabel, "5h")
+            t.equal(normalized.percent, 12)
+        }
+
+        // Live kimi reports weeklyPercent AND fiveHourPercent; live cursor and
+        // google-antigravity each carry two customWindows. Returning one window would
+        // hide real quota pressure.
+        t.test("quotas: kimi exposes both its five-hour and weekly windows") {
+            let json = """
+            {"provider":"kimi","label":"Kimi","quota":{"fiveHourPercent":22,
+             "fiveHourResetAt":1784928599718,"weeklyPercent":61,"weeklyResetAt":1785265199718}}
+            """
+            let report = try decode(QuotaReport.self, json)
+            let windows = report.normalizedWindows()
+            t.equal(windows.count, 2)
+            t.equal(windows.map(\.windowLabel), ["5h", "week"])
+            // The compact row prefers the longer horizon.
+            t.equal(report.normalized().windowLabel, "week")
+            t.equal(report.normalized().percent, 61)
+        }
+
+        t.test("quotas: multiple custom windows are all retained") {
+            let json = """
+            {"provider":"cursor","label":"Cursor","quota":{"monthlyPercent":10,
+             "monthlyResetAt":1785256304000,
+             "customWindows":[{"label":"First-party models","percent":4,"resetAt":1785256304000},
+                              {"label":"API usage","percent":1,"resetAt":1785256304000}]}}
+            """
+            let report = try decode(QuotaReport.self, json)
+            let windows = report.normalizedWindows()
+            t.equal(windows.count, 3)
+            t.equal(windows.map(\.windowLabel), ["month", "First-party models", "API usage"])
+            t.equal(report.normalized().windowLabel, "month")
+        }
+
+        t.test("quotas: a provider with only custom windows still normalizes") {
+            let json = """
+            {"provider":"google-antigravity","label":"Google","quota":{
+             "customWindows":[{"label":"Gem","percent":30,"resetAt":1785256304000},
+                              {"label":"Cla","percent":12,"resetAt":1785256304000}]}}
+            """
+            let report = try decode(QuotaReport.self, json)
+            t.equal(report.normalizedWindows().count, 2)
+            t.equal(report.normalized().windowLabel, "Gem")
+            t.equal(report.normalized().percent, 30)
+        }
+
+        // Every window can stop work. A provider at 99% of a five-hour limit is blocked
+        // right now even if its monthly usage is 10%; picking the longer horizon would
+        // paint that row green while the user cannot make a request.
+        t.test("quotas: the compact row shows the window under the most pressure") {
+            let json = """
+            {"provider":"kimi","label":"Kimi","quota":{"fiveHourPercent":99,
+             "fiveHourResetAt":1784928599718,"monthlyPercent":10,"monthlyResetAt":1785542400000}}
+            """
+            let report = try decode(QuotaReport.self, json)
+            t.equal(report.normalized().windowLabel, "5h")
+            t.equal(report.normalized().percent, 99)
+            t.equal(report.normalizedWindows().count, 2)
+        }
+
+        t.test("quotas: equal pressure breaks toward the longer horizon") {
+            let json = """
+            {"provider":"p","quota":{"fiveHourPercent":50,"fiveHourResetAt":1784928599718,
+             "weeklyPercent":50,"weeklyResetAt":1785265199718}}
+            """
+            t.equal(try decode(QuotaReport.self, json).normalized().windowLabel, "week")
+        }
+
+        t.test("quotas: a window reporting only a reset time does not outrank a measured one") {
+            let json = """
+            {"provider":"p","quota":{"weeklyPercent":12,"weeklyResetAt":1785265199718,
+             "customWindows":[{"label":"unmeasured","resetAt":1785265199718}]}}
+            """
+            let report = try decode(QuotaReport.self, json)
+            t.equal(report.normalized().windowLabel, "week")
+            t.equal(report.normalized().percent, 12)
+        }
+
+        t.test("quotas: an absent quota normalizes to a nil percent") {
+            let normalized = try decode(QuotaReport.self, #"{"provider":"p","label":"P"}"#).normalized()
+            t.isNil(normalized.percent, "percent")
+            t.equal(normalized.hasPercent, false)
+            t.isNil(normalized.resetAt, "resetAt")
+        }
+
+        t.test("providers: decodes the live list") {
+            let json = """
+            [{"name":"openai","adapter":"openai-responses","hasApiKey":false,
+              "authMode":"forward","disabled":false,"codexAccountMode":"pool"},
+             {"name":"anthropic","adapter":"anthropic","hasApiKey":false,
+              "authMode":"oauth","disabled":true}]
+            """
+            let providers = try decode([ProviderSummary].self, json)
+            t.equal(providers.count, 2)
+            t.equal(providers[0].name, "openai")
+            t.equal(providers[0].isEnabled, true)
+            t.equal(providers[1].isEnabled, false)
+        }
+
+        t.test("providers: a provider without a disabled field is enabled") {
+            t.equal(try decode(ProviderSummary.self, #"{"name":"custom"}"#).isEnabled, true)
+        }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/PollingSuite.swift b/app/Sources/MenuBarCoreTests/PollingSuite.swift
new file mode 100644
index 00000000000..838249be4c0
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/PollingSuite.swift
@@ -0,0 +1,408 @@
+import Foundation
+import MenuBarCore
+
+/// Exercises the polling contract against a stubbed transport instead of asserting that
+/// four constants still hold the values they were declared with.
+enum PollingSuite {
+    private static func makeSession() -> URLSession {
+        let config = URLSessionConfiguration.ephemeral
+        config.protocolClasses = [StubProtocol.self]
+        return URLSession(configuration: config)
+    }
+
+    private static func sync<T>(_ operation: @escaping () async -> T) -> T {
+        let semaphore = DispatchSemaphore(value: 0)
+        let box = Box<T>()
+        Task {
+            box.value = await operation()
+            semaphore.signal()
+        }
+        semaphore.wait()
+        return box.value!
+    }
+
+    private final class Box<T>: @unchecked Sendable { var value: T? }
+
+    /// Polls the coordinator's own waiter count, so registration is observed rather
+    /// than assumed from elapsed time.
+    private static func waitForWaiter(_ coordinator: PollingCoordinator, timeout: TimeInterval = 5) async -> Bool {
+        let deadline = Date().addingTimeInterval(timeout)
+        while Date() < deadline {
+            if await coordinator.waiterCount > 0 { return true }
+            try? await Task.sleep(nanoseconds: 5_000_000)
+        }
+        return false
+    }
+
+    private final class Flag: @unchecked Sendable {
+        private let lock = NSLock()
+        private var flag = false
+        var value: Bool { lock.lock(); defer { lock.unlock() }; return flag }
+        func set() { lock.lock(); flag = true; lock.unlock() }
+    }
+
+    private static let healthOK = #"{"status":"protected","serviceInstalled":true,"serviceEnabled":true}"#
+    private static let usageOK = #"{"range":"7d","summary":{"requests":10},"days":[{"date":"d","requests":10}]}"#
+    private static let quotasOK = #"{"reports":[{"provider":"p","quota":{"weeklyPercent":5}}]}"#
+    private static let providersOK = #"[{"name":"openai"}]"#
+    private static let configOK = #"{"defaultProvider":"openai"}"#
+
+    private static func paths() -> [String] {
+        StubProtocol.recorded.compactMap { $0.url?.path }
+    }
+
+    static func run(_ t: TestRunner) {
+        let endpoint = ProxyEndpoint.default
+
+        func makeCoordinator() -> PollingCoordinator {
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: NoCredentials())
+            return PollingCoordinator(client: client, endpoint: endpoint)
+        }
+
+        // The whole point of gating: a closed popover must not trigger aggregation.
+        t.test("polling: a closed popover fetches only liveness") {
+            StubProtocol.reset([.init(status: 200, body: healthOK, urlError: nil)])
+            let coordinator = makeCoordinator()
+            sync { await coordinator.refresh() }
+            t.equal(paths(), ["/api/startup-health", "/api/companion/settings", "/api/usage", "/api/usage/timeline"])
+        }
+
+        t.test("polling: opening the popover fetches on-open and aggregation reads") {
+            StubProtocol.reset([
+                .init(status: 200, body: healthOK, urlError: nil),
+                .init(status: 200, body: providersOK, urlError: nil),
+                .init(status: 200, body: configOK, urlError: nil),
+                .init(status: 200, body: usageOK, urlError: nil),
+                .init(status: 200, body: quotasOK, urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            let snapshot = sync { () -> ProxySnapshot in
+                await coordinator.setPopoverOpen(true)
+                return await coordinator.current
+            }
+            t.expect(paths().contains("/api/providers"), "providers fetched on open")
+            t.expect(paths().contains("/api/usage"), "usage fetched on open")
+            t.expect(paths().contains("/api/provider-quotas"), "quotas fetched on open")
+            t.equal(snapshot.providersLoaded, true)
+            t.equal(snapshot.quotasLoaded, true)
+            t.equal(snapshot.defaultProvider, "openai")
+        }
+
+        // Reopening within the aggregation window should refresh cheap reads only.
+        t.test("polling: a second open reuses aggregation but refreshes on-open reads") {
+            StubProtocol.reset([
+                .init(status: 200, body: healthOK, urlError: nil),
+                .init(status: 200, body: providersOK, urlError: nil),
+                .init(status: 200, body: configOK, urlError: nil),
+                .init(status: 200, body: usageOK, urlError: nil),
+                .init(status: 200, body: quotasOK, urlError: nil),
+                .init(status: 200, body: healthOK, urlError: nil),
+                .init(status: 200, body: providersOK, urlError: nil),
+                .init(status: 200, body: configOK, urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            sync {
+                await coordinator.setPopoverOpen(true)
+                await coordinator.setPopoverOpen(false)
+                await coordinator.setPopoverOpen(true)
+            }
+            let usageCalls = paths().filter { $0 == "/api/usage" }.count
+            let providerCalls = paths().filter { $0 == "/api/providers" }.count
+            t.equal(usageCalls, 1, "aggregation respects its interval")
+            t.equal(providerCalls, 2, "on-open reads run every open")
+        }
+
+        t.test("polling: a refused proxy becomes unreachable and counts a failure") {
+            StubProtocol.reset([.init(status: 0, body: "", urlError: .cannotConnectToHost)])
+            let coordinator = makeCoordinator()
+            let snapshot = sync { () -> ProxySnapshot in
+                await coordinator.refresh()
+                return await coordinator.current
+            }
+            t.equal(snapshot.state, .unreachable)
+            t.equal(snapshot.consecutiveFailures, 1)
+            t.equal(snapshot.showsData, false)
+        }
+
+        t.test("polling: repeated failures widen the interval to the backoff value") {
+            StubProtocol.reset(Array(repeating: .init(status: 0, body: "", urlError: .cannotConnectToHost), count: 4))
+            let coordinator = makeCoordinator()
+            let interval = sync { () -> TimeInterval in
+                for _ in 0..<3 { await coordinator.refresh() }
+                return await coordinator.currentInterval
+            }
+            t.equal(interval, PollingCoordinator.backoffInterval)
+        }
+
+        t.test("polling: a recovered proxy resets the failure count and interval") {
+            StubProtocol.reset([
+                .init(status: 0, body: "", urlError: .cannotConnectToHost),
+                .init(status: 200, body: healthOK, urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            let snapshot = sync { () -> ProxySnapshot in
+                await coordinator.refresh()
+                await coordinator.refresh()
+                return await coordinator.current
+            }
+            t.equal(snapshot.consecutiveFailures, 0)
+            t.equal(snapshot.state.isRunning, true)
+        }
+
+        // A degraded proxy keeps its last-known numbers with an explicit age, rather
+        // than blanking the panel.
+        t.test("polling: a 500 degrades while retaining previously loaded data") {
+            StubProtocol.reset([
+                .init(status: 200, body: healthOK, urlError: nil),
+                .init(status: 200, body: providersOK, urlError: nil),
+                .init(status: 200, body: configOK, urlError: nil),
+                .init(status: 200, body: usageOK, urlError: nil),
+                .init(status: 200, body: quotasOK, urlError: nil),
+                .init(status: 500, body: "", urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            let snapshot = sync { () -> ProxySnapshot in
+                await coordinator.setPopoverOpen(true)
+                await coordinator.refresh()
+                return await coordinator.current
+            }
+            if case .degraded = snapshot.state {
+                t.expect(true, "degraded")
+            } else {
+                t.expect(false, "expected degraded, got \(snapshot.state)")
+            }
+            t.equal(snapshot.showsData, true, "stale-but-labelled beats blank")
+            _ = t.notNil(snapshot.usage, "usage retained")
+        }
+
+        t.test("polling: the recommended command is carried into the snapshot") {
+            StubProtocol.reset([
+                .init(status: 200,
+                      body: #"{"status":"at-risk","recommendedCommand":"ocx service install"}"#,
+                      urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            let snapshot = sync { () -> ProxySnapshot in
+                await coordinator.refresh()
+                return await coordinator.current
+            }
+            t.equal(snapshot.recommendedCommand, "ocx service install")
+        }
+
+        t.test("polling: observers receive the snapshot on registration and on change") {
+            StubProtocol.reset([.init(status: 200, body: healthOK, urlError: nil)])
+            let coordinator = makeCoordinator()
+            let counter = Counter()
+            sync {
+                await coordinator.observe { _ in counter.bump() }
+                await coordinator.refresh()
+            }
+            t.expect(counter.count >= 2, "expected at least 2 notifications, got \(counter.count)")
+        }
+
+        // On-open reads are cheap but not free: running them on every liveness tick
+        // turned two rarely-changing endpoints into 5-second pollers.
+        t.test("polling: a background tick while open does not refetch on-open reads") {
+            StubProtocol.reset([
+                .init(status: 200, body: healthOK, urlError: nil),
+                .init(status: 200, body: providersOK, urlError: nil),
+                .init(status: 200, body: configOK, urlError: nil),
+                .init(status: 200, body: usageOK, urlError: nil),
+                .init(status: 200, body: quotasOK, urlError: nil),
+                .init(status: 200, body: healthOK, urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            sync {
+                await coordinator.setPopoverOpen(true)
+                await coordinator.refresh()          // ordinary liveness tick
+            }
+            t.equal(paths().filter { $0 == "/api/providers" }.count, 1, "providers fetched once")
+            t.equal(paths().filter { $0 == "/api/config" }.count, 1, "config fetched once")
+            t.equal(paths().filter { $0 == "/api/startup-health" }.count, 2, "health fetched twice")
+        }
+
+        t.test("polling: a closed popover skips on-open reads entirely") {
+            StubProtocol.reset([
+                .init(status: 200, body: healthOK, urlError: nil),
+                .init(status: 200, body: healthOK, urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            sync {
+                await coordinator.refresh()
+                await coordinator.refresh()
+            }
+            t.equal(paths().filter { $0 == "/api/providers" }.count, 0)
+            t.equal(paths().filter { $0 == "/api/usage" }.count, 1)
+        }
+
+        // A failing quota endpoint must not drag its healthy sibling into the 5s tick.
+        t.test("polling: a partial aggregation failure still consumes the interval") {
+            StubProtocol.reset([
+                .init(status: 200, body: healthOK, urlError: nil),
+                .init(status: 200, body: providersOK, urlError: nil),
+                .init(status: 200, body: configOK, urlError: nil),
+                .init(status: 200, body: usageOK, urlError: nil),
+                .init(status: 500, body: "", urlError: nil),        // quotas fail
+                .init(status: 200, body: healthOK, urlError: nil),  // next tick
+            ])
+            let coordinator = makeCoordinator()
+            sync {
+                await coordinator.setPopoverOpen(true)
+                await coordinator.refresh()
+            }
+            t.equal(paths().filter { $0 == "/api/usage" }.count, 1, "usage not refetched after a sibling failure")
+        }
+
+        t.test("polling: degraded without any loaded data does not claim to show data") {
+            StubProtocol.reset([.init(status: 500, body: "", urlError: nil)])
+            let coordinator = makeCoordinator()
+            let snapshot = sync { () -> ProxySnapshot in
+                await coordinator.refresh()
+                return await coordinator.current
+            }
+            t.equal(snapshot.showsData, false, "no data was ever loaded")
+            t.isNil(snapshot.dataAge, "dataAge")
+        }
+
+        // refresh() coalesces, so a caller that needs authoritative state afterwards
+        // must wait for the cycle that absorbed its request — not just for its own
+        // immediate return.
+        t.test("polling: refreshAndWait returns only after a cycle has published") {
+            // setPopoverOpen already runs a full cycle, so queue enough for both it and
+            // the refreshAndWait that follows; the stub falls back to connection-refused
+            // once drained, which would look like a stopped proxy.
+            StubProtocol.reset([
+                .init(status: 200, body: healthOK, urlError: nil),
+                .init(status: 200, body: providersOK, urlError: nil),
+                .init(status: 200, body: configOK, urlError: nil),
+                .init(status: 200, body: usageOK, urlError: nil),
+                .init(status: 200, body: quotasOK, urlError: nil),
+                .init(status: 200, body: healthOK, urlError: nil),
+                .init(status: 200, body: providersOK, urlError: nil),
+                .init(status: 200, body: configOK, urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            let snapshot = sync { () -> ProxySnapshot in
+                await coordinator.setPopoverOpen(true)
+                await coordinator.refreshAndWait()
+                return await coordinator.current
+            }
+            // If it returned early the health read would not have landed yet.
+            t.equal(snapshot.state.isRunning, true)
+            _ = t.notNil(snapshot.lastUpdated, "lastUpdated after refreshAndWait")
+        }
+
+        // The first two refreshAndWait tests ran with refreshInFlight == false, so they
+        // never entered waitForCompletion() at all. These hold a cycle suspended in the
+        // stub so the coalescing path is the one under test.
+        t.test("polling: refreshAndWait suspends behind an in-flight cycle and resumes") {
+            StubProtocol.reset(Array(
+                repeating: .init(status: 200, body: healthOK, urlError: nil), count: 20))
+            let gate = DispatchSemaphore(value: 0)
+            StubProtocol.setGate(gate)
+            defer {
+                StubProtocol.setGate(nil)
+                for _ in 0..<40 { gate.signal() }
+            }
+
+            let coordinator = makeCoordinator()
+            let returned = Flag()
+
+            let first = Task { await coordinator.refresh() }
+            // Wait for the request to actually reach the gate rather than guessing.
+            t.equal(StubProtocol.gateEntered.wait(timeout: .now() + 5), .success,
+                    "cycle 1 should reach the gate")
+
+            let waiter = Task {
+                await coordinator.refreshAndWait()
+                returned.set()
+            }
+            // Wait for the waiter to actually REGISTER, rather than sleeping and hoping
+            // it was scheduled. A fixed sleep let this test pass without ever entering
+            // the continuation path.
+            t.equal(sync { await waitForWaiter(coordinator) }, true, "waiter should register")
+            t.equal(returned.value, false, "refreshAndWait must not return while a cycle is in flight")
+
+            StubProtocol.setGate(nil)
+            for _ in 0..<40 { gate.signal() }
+            sync { _ = await first.value; _ = await waiter.value }
+            t.equal(returned.value, true, "refreshAndWait must resume once the queued cycle publishes")
+            t.equal(sync { await coordinator.waiterCount }, 0, "no waiter should remain registered")
+        }
+
+        // The queued cycle must FAIL here. Two contract details drive the setup:
+        // drainPendingRefresh only runs while the popover is OPEN, and an open cycle
+        // consumes health + providers + config + usage + quotas. So the popover is
+        // opened first (consuming its own cycle), then one gated 200 lets cycle 1 reach
+        // the gate, and every response after that is a refusal. An earlier version
+        // queued three 200s with the popover closed and silently re-tested the success
+        // path — which is exactly what the new state assertion caught.
+        t.test("polling: a waiter is released when the queued cycle fails") {
+            StubProtocol.reset([
+                .init(status: 200, body: healthOK, urlError: nil),
+                .init(status: 200, body: providersOK, urlError: nil),
+                .init(status: 200, body: configOK, urlError: nil),
+                .init(status: 200, body: usageOK, urlError: nil),
+                .init(status: 200, body: quotasOK, urlError: nil),
+            ])
+            let coordinator = makeCoordinator()
+            sync { await coordinator.setPopoverOpen(true) }
+
+            var responses: [StubProtocol.Response] = [.init(status: 200, body: healthOK, urlError: nil)]
+            responses.append(contentsOf: Array(
+                repeating: .init(status: 0, body: "", urlError: .cannotConnectToHost), count: 30))
+            StubProtocol.reset(responses)
+            let gate = DispatchSemaphore(value: 0)
+            StubProtocol.setGate(gate)
+            defer {
+                StubProtocol.setGate(nil)
+                for _ in 0..<60 { gate.signal() }
+            }
+
+            let returned = Flag()
+            let first = Task { await coordinator.refresh() }
+            t.equal(StubProtocol.gateEntered.wait(timeout: .now() + 5), .success,
+                    "cycle 1 should reach the gate")
+
+            let waiter = Task {
+                await coordinator.refreshAndWait()
+                returned.set()
+            }
+            t.equal(sync { await waitForWaiter(coordinator) }, true, "waiter should register")
+            t.equal(returned.value, false, "must still be suspended")
+
+            StubProtocol.setGate(nil)
+            for _ in 0..<60 { gate.signal() }
+            let snapshot = sync { () -> ProxySnapshot in
+                _ = await first.value
+                _ = await waiter.value
+                return await coordinator.current
+            }
+            t.equal(returned.value, true, "a failing queued cycle must still release its waiter")
+            // Proves the refusal was actually consumed, not a second 200.
+            t.equal(snapshot.state, .unreachable, "the queued cycle must have failed")
+        }
+
+        t.test("polling: refreshAndWait survives a failing cycle without hanging") {
+            StubProtocol.reset([.init(status: 0, body: "", urlError: .cannotConnectToHost)])
+            let coordinator = makeCoordinator()
+            let snapshot = sync { () -> ProxySnapshot in
+                await coordinator.refreshAndWait()
+                return await coordinator.current
+            }
+            t.equal(snapshot.state, .unreachable)
+        }
+    }
+
+    private struct NoCredentials: CredentialStore {
+        func loadAPIKey() -> String? { nil }
+    }
+
+    private final class Counter: @unchecked Sendable {
+        private let lock = NSLock()
+        private var value = 0
+        var count: Int { lock.lock(); defer { lock.unlock() }; return value }
+        func bump() { lock.lock(); value += 1; lock.unlock() }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/SnapshotStateSuite.swift b/app/Sources/MenuBarCoreTests/SnapshotStateSuite.swift
new file mode 100644
index 00000000000..b9cb5d8146c
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/SnapshotStateSuite.swift
@@ -0,0 +1,106 @@
+import Foundation
+import MenuBarCore
+
+enum SnapshotStateSuite {
+    private static func health(_ status: String?, service: Bool = false) -> StartupHealth {
+        StartupHealth(
+            status: status,
+            protection: service ? "service" : "none",
+            serviceInstalled: service,
+            serviceEnabled: service
+        )
+    }
+
+    static func run(_ t: TestRunner) {
+        let endpoint = ProxyEndpoint.default
+
+        t.test("state: every state has a word, so colour is never the only signal") {
+            let states: [ProxyState] = [
+                .loading, .running(health("protected")), .unreachable,
+                .unauthorized, .degraded("boom"),
+            ]
+            for state in states {
+                t.expect(!state.title.isEmpty, "state \(state) must have a title")
+            }
+            t.equal(ProxyState.unreachable.title, "Stopped")
+            t.equal(ProxyState.unauthorized.title, "Needs API key")
+        }
+
+        t.test("state: an unprotected but running proxy reads as a warning, not healthy") {
+            t.equal(ProxyState.running(health("protected")).tone, .good)
+            t.equal(ProxyState.running(health("at-risk")).tone, .warning)
+            t.equal(ProxyState.unreachable.tone, .bad)
+        }
+
+        // loading is the one state with nothing to act on; every other non-running
+        // state must name a next step rather than dead-ending the user.
+        t.test("actions: loading has none, and every other non-running state names one") {
+            let loading = ProxySnapshot(state: .loading, endpoint: endpoint)
+            t.equal(loading.nextAction, NextAction.none)
+
+            let unauthorized = ProxySnapshot(state: .unauthorized, endpoint: endpoint)
+            t.equal(unauthorized.nextAction, NextAction.addAPIKey)
+
+            let degraded = ProxySnapshot(state: .degraded("x"), endpoint: endpoint)
+            t.equal(degraded.nextAction, NextAction.retry)
+        }
+
+        t.test("actions: a stopped proxy offers the start command for its own install") {
+            let plain = ProxySnapshot(state: .unreachable, endpoint: endpoint)
+            t.equal(plain.nextAction, NextAction.runCommand("ocx start"))
+
+            let managed = ProxySnapshot(
+                state: .unreachable, endpoint: endpoint,
+                lastKnownStartCommand: "ocx service start"
+            )
+            t.equal(managed.nextAction, NextAction.runCommand("ocx service start"))
+        }
+
+        t.test("state: the running detail line drops empty and 'none' qualifiers") {
+            let protectedDetail = ProxyState.running(health("protected", service: true)).detail
+            t.equal(protectedDetail, "protected · service")
+            // protection "none" is noise, not information.
+            t.equal(ProxyState.running(health("at-risk")).detail, "at-risk")
+        }
+
+        t.test("snapshot: quota rows normalize one row per provider") {
+            let json = """
+            [{"provider":"kimi","label":"Kimi","quota":{"fiveHourPercent":99,
+              "fiveHourResetAt":1784928599718,"monthlyPercent":10,"monthlyResetAt":1785542400000}}]
+            """
+            let quotas = try JSONDecoder().decode([QuotaReport].self, from: Data(json.utf8))
+            let snapshot = ProxySnapshot(state: .running(health("protected")), endpoint: endpoint, quotas: quotas)
+            t.equal(snapshot.quotaRows.count, 1)
+            t.equal(snapshot.quotaRows[0].windowLabel, "5h")
+        }
+
+        t.test("snapshot: the default provider cannot be toggled") {
+            let providers = try JSONDecoder().decode(
+                [ProviderSummary].self,
+                from: Data(#"[{"name":"openai"},{"name":"anthropic"}]"#.utf8)
+            )
+            let snapshot = ProxySnapshot(
+                state: .running(health("protected")), endpoint: endpoint,
+                providers: providers, defaultProvider: "openai"
+            )
+            t.equal(snapshot.canToggle(providers[0]), false, "default provider")
+            t.equal(snapshot.canToggle(providers[1]), true, "non-default provider")
+        }
+
+        t.test("snapshot: an omitted usage count stays unknown rather than empty") {
+            let usage = try JSONDecoder().decode(
+                UsageReport.self,
+                from: Data(#"{"range":"7d","summary":{"totalTokens":5}}"#.utf8)
+            )
+            let snapshot = ProxySnapshot(state: .running(health("protected")), endpoint: endpoint, usage: usage)
+            t.isNil(snapshot.usageIsEmpty, "usageIsEmpty for an omitted count")
+        }
+
+        t.test("polling: the interval backs off only after repeated failures") {
+            t.equal(PollingCoordinator.livenessInterval, 5)
+            t.equal(PollingCoordinator.heavyInterval, 60)
+            t.equal(PollingCoordinator.backoffInterval, 30)
+            t.equal(PollingCoordinator.backoffAfterFailures, 3)
+        }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/TimelineDecodingSuite.swift b/app/Sources/MenuBarCoreTests/TimelineDecodingSuite.swift
new file mode 100644
index 00000000000..eb2b2b5ca05
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/TimelineDecodingSuite.swift
@@ -0,0 +1,15 @@
+import Foundation
+import MenuBarCore
+
+enum TimelineDecodingSuite {
+    static func run(_ t: TestRunner) {
+        t.test("timeline: decodes series and derived maxima") {
+            let json = #"{"start":0,"end":3600,"bucketSeconds":1800,"buckets":2,"metric":"total","aggregation":"sum","grouping":"model","series":[{"id":"a","provider":"p","model":"m","total":3,"points":[1,2]},{"id":"b","provider":"p","model":"n","total":4,"points":[4,0]}],"availableModels":["p/m","p/n"],"missingMeasurements":1,"truncated":true}"#
+            let timeline = try JSONDecoder().decode(UsageTimeline.self, from: Data(json.utf8))
+            t.equal(timeline.maxPoint, 4)
+            t.equal(timeline.stackedMax, 5)
+            t.equal(timeline.isEmpty, false)
+            t.equal(timeline.truncated, true)
+        }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/TransportSuite.swift b/app/Sources/MenuBarCoreTests/TransportSuite.swift
new file mode 100644
index 00000000000..d46a667e0fe
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/TransportSuite.swift
@@ -0,0 +1,362 @@
+import Foundation
+import MenuBarCore
+
+/// Stubs the network so status mapping, the 401 retry, cancellation, request shape, and
+/// body privacy are covered without a live proxy.
+final class StubProtocol: URLProtocol, @unchecked Sendable {
+    struct Response {
+        var status: Int
+        var body: String
+        var urlError: URLError.Code?
+    }
+
+    nonisolated(unsafe) static var queue: [Response] = []
+    nonisolated(unsafe) static var recorded: [URLRequest] = []
+    private static let lock = NSLock()
+
+    static func reset(_ responses: [Response]) {
+        lock.lock(); defer { lock.unlock() }
+        queue = responses
+        recorded = []
+        bodies = []
+        gateStorage = nil
+    }
+
+    nonisolated(unsafe) static var bodies: [Data] = []
+    /// When set, `startLoading` blocks until the gate is opened. Lets a test hold a
+    /// refresh suspended so the coalescing/continuation path is genuinely exercised.
+    ///
+    /// Access goes through `setGate`/`currentGate` under the same lock as the rest of
+    /// the stub state: an unsynchronised read here is a data race, and `gateEntered`
+    /// lets a test wait for the request to actually reach the gate instead of inferring
+    /// it from elapsed time.
+    nonisolated(unsafe) private static var gateStorage: DispatchSemaphore?
+    static let gateEntered = DispatchSemaphore(value: 0)
+
+    static func setGate(_ gate: DispatchSemaphore?) {
+        lock.lock(); gateStorage = gate; lock.unlock()
+    }
+
+    static func currentGate() -> DispatchSemaphore? {
+        lock.lock(); defer { lock.unlock() }
+        return gateStorage
+    }
+
+    static func record(_ request: URLRequest) {
+        lock.lock(); defer { lock.unlock() }
+        recorded.append(request)
+        // URLProtocol replaces httpBody with a stream, so read it here or the body is
+        // unobservable — which let an "exact body" assertion pass with no body at all.
+        if let body = request.httpBody {
+            bodies.append(body)
+        } else if let stream = request.httpBodyStream {
+            stream.open()
+            var data = Data()
+            var buffer = [UInt8](repeating: 0, count: 1024)
+            while stream.hasBytesAvailable {
+                let read = stream.read(&buffer, maxLength: buffer.count)
+                if read <= 0 { break }
+                data.append(buffer, count: read)
+            }
+            stream.close()
+            bodies.append(data)
+        }
+    }
+
+    static func next() -> Response? {
+        lock.lock(); defer { lock.unlock() }
+        return queue.isEmpty ? nil : queue.removeFirst()
+    }
+
+    override class func canInit(with request: URLRequest) -> Bool { true }
+    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
+
+    override func startLoading() {
+        Self.record(request)
+        // Held open by tests that need a request to stay in flight.
+        if let gate = Self.currentGate() {
+            Self.gateEntered.signal()
+            gate.wait()
+        }
+        if request.url?.path == "/api/companion/settings" {
+            let body = #"{"settings":{"menuBarMetric":"requests","showToday":true,"showChart":true,"showModels":true,"showCost":true,"showAccounts":true,"chartHours":24,"bucketMinutes":60,"chartStyle":"line","tokenMetric":"total","aggregation":"sum","chartGrouping":"model","hiddenProviders":[]}}"#
+            let http = HTTPURLResponse(url: request.url!, statusCode: 200, httpVersion: "HTTP/1.1", headerFields: nil)!
+            client?.urlProtocol(self, didReceive: http, cacheStoragePolicy: .notAllowed)
+            client?.urlProtocol(self, didLoad: Data(body.utf8))
+            client?.urlProtocolDidFinishLoading(self)
+            return
+        }
+        if request.url?.path == "/api/usage/timeline" {
+            let body = #"{"start":0,"end":3600,"bucketSeconds":3600,"buckets":1,"metric":"total","aggregation":"sum","grouping":"model","series":[],"availableModels":[],"missingMeasurements":0}"#
+            let http = HTTPURLResponse(url: request.url!, statusCode: 200, httpVersion: "HTTP/1.1", headerFields: nil)!
+            client?.urlProtocol(self, didReceive: http, cacheStoragePolicy: .notAllowed)
+            client?.urlProtocol(self, didLoad: Data(body.utf8))
+            client?.urlProtocolDidFinishLoading(self)
+            return
+        }
+        guard let response = Self.next() else {
+            client?.urlProtocol(self, didFailWithError: URLError(.cannotConnectToHost))
+            return
+        }
+        if let code = response.urlError {
+            client?.urlProtocol(self, didFailWithError: URLError(code))
+            return
+        }
+        let http = HTTPURLResponse(
+            url: request.url!, statusCode: response.status,
+            httpVersion: "HTTP/1.1", headerFields: nil
+        )!
+        client?.urlProtocol(self, didReceive: http, cacheStoragePolicy: .notAllowed)
+        client?.urlProtocol(self, didLoad: Data(response.body.utf8))
+        client?.urlProtocolDidFinishLoading(self)
+    }
+
+    override func stopLoading() {}
+}
+
+private struct StubCredentials: CredentialStore {
+    let key: String?
+    let counter: Counter
+
+    final class Counter: @unchecked Sendable {
+        private(set) var loads = 0
+        private let lock = NSLock()
+        func bump() { lock.lock(); loads += 1; lock.unlock() }
+    }
+
+    func loadAPIKey() -> String? {
+        counter.bump()
+        return key
+    }
+}
+
+enum TransportSuite {
+    private static func makeSession() -> URLSession {
+        let config = URLSessionConfiguration.ephemeral
+        config.protocolClasses = [StubProtocol.self]
+        return URLSession(configuration: config)
+    }
+
+    private static func sync<T>(_ operation: @escaping () async -> T) -> T {
+        let semaphore = DispatchSemaphore(value: 0)
+        let box = ResultBox<T>()
+        Task {
+            box.value = await operation()
+            semaphore.signal()
+        }
+        semaphore.wait()
+        return box.value!
+    }
+
+    private final class ResultBox<T>: @unchecked Sendable { var value: T? }
+
+    static func run(_ t: TestRunner) {
+        let endpoint = ProxyEndpoint.default
+
+        t.test("transport: a 200 decodes into the model") {
+            StubProtocol.reset([.init(status: 200, body: #"{"status":"protected"}"#, urlError: nil)])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: nil, counter: .init()))
+            let result: String? = sync {
+                try? await client.health().status
+            }
+            t.equal(result, "protected")
+        }
+
+        t.test("transport: a 500 maps to .http and never carries the body") {
+            StubProtocol.reset([.init(status: 500, body: "SECRET-CONFIG-VALUE", urlError: nil)])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: nil, counter: .init()))
+            let error: ProxyError? = sync {
+                do { _ = try await client.health(); return nil }
+                catch let error as ProxyError { return error }
+                catch { return nil }
+            }
+            t.equal(error, .http(500))
+            let message = error?.userMessage ?? ""
+            t.expect(!message.contains("SECRET"), "error message must not echo the body: \(message)")
+        }
+
+        t.test("transport: malformed JSON maps to .decoding") {
+            StubProtocol.reset([.init(status: 200, body: "{not json", urlError: nil)])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: nil, counter: .init()))
+            let error: ProxyError? = sync {
+                do { _ = try await client.health(); return nil }
+                catch let error as ProxyError { return error }
+                catch { return nil }
+            }
+            t.equal(error, .decoding)
+        }
+
+        t.test("transport: connection refused maps to .unreachable") {
+            StubProtocol.reset([.init(status: 0, body: "", urlError: .cannotConnectToHost)])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: nil, counter: .init()))
+            let error: ProxyError? = sync {
+                do { _ = try await client.health(); return nil }
+                catch let error as ProxyError { return error }
+                catch { return nil }
+            }
+            t.equal(error, .unreachable)
+        }
+
+        // A policy failure is not evidence the proxy is down; conflating them would put
+        // the UI in "Stopped" for a running proxy.
+        t.test("transport: an unrelated URLError maps to .transport, not .unreachable") {
+            StubProtocol.reset([.init(status: 0, body: "", urlError: .appTransportSecurityRequiresSecureConnection)])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: nil, counter: .init()))
+            let error: ProxyError? = sync {
+                do { _ = try await client.health(); return nil }
+                catch let error as ProxyError { return error }
+                catch { return nil }
+            }
+            t.equal(error, .transport)
+        }
+
+        t.test("transport: cancellation propagates instead of reading as a stopped proxy") {
+            StubProtocol.reset([.init(status: 0, body: "", urlError: .cancelled)])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: nil, counter: .init()))
+            let wasCancellation: Bool = sync {
+                do { _ = try await client.health(); return false }
+                catch is CancellationError { return true }
+                catch { return false }
+            }
+            t.equal(wasCancellation, true)
+        }
+
+        t.test("auth: a 401 with a stored key retries once and succeeds") {
+            StubProtocol.reset([
+                .init(status: 401, body: "", urlError: nil),
+                .init(status: 200, body: #"{"status":"protected"}"#, urlError: nil),
+            ])
+            let counter = StubCredentials.Counter()
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: "test-key", counter: counter))
+            let status: String? = sync { try? await client.health().status }
+            t.equal(status, "protected")
+            t.equal(counter.loads, 1, "credential loaded exactly once")
+            t.equal(StubProtocol.recorded.count, 2, "one retry")
+            let retry = StubProtocol.recorded.last
+            t.equal(retry?.value(forHTTPHeaderField: "x-opencodex-api-key"), "test-key")
+        }
+
+        t.test("auth: a 401 with no stored key surfaces .unauthorized without retrying") {
+            StubProtocol.reset([.init(status: 401, body: "", urlError: nil)])
+            let counter = StubCredentials.Counter()
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: nil, counter: counter))
+            let error: ProxyError? = sync {
+                do { _ = try await client.health(); return nil }
+                catch let error as ProxyError { return error }
+                catch { return nil }
+            }
+            t.equal(error, .unauthorized)
+            t.equal(StubProtocol.recorded.count, 1, "no retry without a key")
+        }
+
+        // A stale stored key must not spin: one retry, then surface the failure.
+        t.test("auth: repeated 401s retry exactly once, never looping") {
+            StubProtocol.reset([
+                .init(status: 401, body: "", urlError: nil),
+                .init(status: 401, body: "", urlError: nil),
+                .init(status: 401, body: "", urlError: nil),
+            ])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: "stale", counter: .init()))
+            let error: ProxyError? = sync {
+                do { _ = try await client.health(); return nil }
+                catch let error as ProxyError { return error }
+                catch { return nil }
+            }
+            t.equal(error, .unauthorized)
+            t.equal(StubProtocol.recorded.count, 2, "exactly one retry")
+        }
+
+        t.test("requests: usage sends the enum range as a query item") {
+            StubProtocol.reset([.init(status: 200, body: #"{"range":"7d"}"#, urlError: nil)])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: nil, counter: .init()))
+            _ = sync { try? await client.usage(range: .sevenDays) }
+            let url = StubProtocol.recorded.first?.url?.absoluteString ?? ""
+            t.expect(url.contains("range=7d"), "expected range=7d in \(url)")
+            t.expect(url.contains("/api/usage"), "expected /api/usage in \(url)")
+            t.equal(StubProtocol.recorded.first?.value(forHTTPHeaderField: "User-Agent"), "OpenCodexWidget/dev")
+        }
+
+        t.test("requests: the provider patch sends exactly {\"disabled\":true}") {
+            StubProtocol.reset([.init(status: 200, body: "{}", urlError: nil)])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: nil, counter: .init()))
+            _ = sync {
+                try? await client.setProviderDisabled("anthropic", disabled: true)
+            }
+            let request = StubProtocol.recorded.first
+            t.equal(request?.httpMethod, "PATCH")
+            let url = request?.url?.absoluteString ?? ""
+            t.expect(url.contains("name=anthropic"), "expected name=anthropic in \(url)")
+
+            // Assert on the ACTUAL request body. An earlier version encoded its own
+            // dictionary and compared that, so it would have passed with no body at all.
+            guard let body = StubProtocol.bodies.first else {
+                t.expect(false, "no request body captured")
+                return
+            }
+            let decoded = try JSONSerialization.jsonObject(with: body) as? [String: Any]
+            t.equal(decoded?.keys.sorted() ?? [], ["disabled"], "body must carry only 'disabled'")
+            t.equal(decoded?["disabled"] as? Bool, true)
+        }
+
+        t.test("liveness: a 401 still proves something is listening") {
+            StubProtocol.reset([
+                .init(status: 401, body: "", urlError: nil),
+                .init(status: 401, body: "", urlError: nil),
+            ])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: "k", counter: .init()))
+            t.equal(sync { await client.isReachable() }, true)
+        }
+
+        t.test("liveness: connection refused reads as not reachable") {
+            StubProtocol.reset([.init(status: 0, body: "", urlError: .cannotConnectToHost)])
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: nil, counter: .init()))
+            t.equal(sync { await client.isReachable() }, false)
+        }
+
+        t.test("endpoint: an out-of-range port cannot be constructed") {
+            t.isNil(ProxyEndpoint(port: 0), "port 0")
+            t.isNil(ProxyEndpoint(port: -1), "port -1")
+            t.isNil(ProxyEndpoint(port: 70_000), "port 70000")
+            t.equal(ProxyEndpoint(port: 10_100)?.baseURL.absoluteString, "http://127.0.0.1:10100")
+        }
+
+        // The actor suspends across each request, so several calls can be in flight and
+        // all receive 401. A single global "already tried" flag made the second caller
+        // fail even though the first had just loaded a usable key.
+        t.test("auth: concurrent initial 401s both succeed once a key is loaded") {
+            StubProtocol.reset([
+                .init(status: 401, body: "", urlError: nil),
+                .init(status: 401, body: "", urlError: nil),
+                .init(status: 200, body: #"{"status":"protected"}"#, urlError: nil),
+                .init(status: 200, body: #"{"status":"protected"}"#, urlError: nil),
+            ])
+            let counter = StubCredentials.Counter()
+            let client = ProxyClient(endpoint: endpoint, session: makeSession(),
+                                     credentials: StubCredentials(key: "test-key", counter: counter))
+
+            let outcomes: [String] = sync {
+                async let first = try? await client.health().status
+                async let second = try? await client.health().status
+                let results = await [first, second]
+                return results.map { $0 ?? "error" }
+            }
+
+            t.equal(outcomes.filter { $0 == "protected" }.count, 2, "both calls should succeed")
+            t.equal(counter.loads, 1, "credentials loaded exactly once")
+            t.equal(StubProtocol.recorded.count, 4, "two initial calls plus two retries")
+        }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/WidgetSnapshotSuite.swift b/app/Sources/MenuBarCoreTests/WidgetSnapshotSuite.swift
new file mode 100644
index 00000000000..66f25176b68
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/WidgetSnapshotSuite.swift
@@ -0,0 +1,37 @@
+import Foundation
+import MenuBarCore
+
+enum WidgetSnapshotSuite {
+    static func run(_ t: TestRunner) {
+        t.test("widget snapshot: maps today and caps chart series") {
+            var series: [String] = []
+            for index in 0..<7 {
+                series.append(#"{"id":"s\#(index)","provider":"p","model":"m\#(index)","total":1,"points":[1]}"#)
+            }
+            let timelineJSON = #"{"start":1,"end":2,"bucketSeconds":60,"buckets":1,"metric":"total","aggregation":"sum","grouping":"model","series":[\#(series.joined(separator: ","))],"availableModels":[],"missingMeasurements":0}"#
+            let timeline = try! JSONDecoder().decode(UsageTimeline.self, from: Data(timelineJSON.utf8))
+            let report = try! JSONDecoder().decode(UsageReport.self, from: Data(#"{"range":"today","summary":{"requests":2,"totalTokens":3,"estimatedCostUsd":4}}"#.utf8))
+            var snapshot = ProxySnapshot(endpoint: .default, usage: report, today: report, timeline: timeline)
+            snapshot.state = .running(try! JSONDecoder().decode(StartupHealth.self, from: Data(#"{"status":"protected"}"#.utf8)))
+            let widget = WidgetSnapshot.make(from: snapshot, now: Date(timeIntervalSince1970: 100))
+            t.equal(widget.schemaVersion, 1)
+            t.equal(widget.today?.requests, 2)
+            t.equal(widget.chart?.series.count, 6)
+        }
+        t.test("widget snapshot: encoded payload contains no credentials") {
+            let snapshot = WidgetSnapshot.make(from: ProxySnapshot(endpoint: .default), now: Date())
+            let data = try! JSONEncoder().encode(snapshot)
+            let text = String(decoding: data, as: UTF8.self)
+            t.expect(!text.contains("apiKey") && !text.contains("x-opencodex"), "privacy")
+        }
+        t.test("widget snapshot: store writes to injected home") {
+            let home = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+            let store = WidgetSnapshotStore(homeDirectory: home)
+            let snapshot = WidgetSnapshot.make(from: ProxySnapshot(endpoint: .default), now: Date())
+            store.writeIfChanged(snapshot)
+            t.expect(FileManager.default.fileExists(atPath: store.url.path), "snapshot file")
+            let mode = (try? FileManager.default.attributesOfItem(atPath: store.url.path)[.posixPermissions] as? NSNumber)?.intValue
+            t.equal(mode, 0o600)
+        }
+    }
+}
diff --git a/app/Sources/MenuBarCoreTests/main.swift b/app/Sources/MenuBarCoreTests/main.swift
new file mode 100644
index 00000000000..41928f17a1c
--- /dev/null
+++ b/app/Sources/MenuBarCoreTests/main.swift
@@ -0,0 +1,20 @@
+import Foundation
+
+// Entry point for `swift run --package-path app MenuBarCoreTests`.
+// See Harness.swift for why this is an executable rather than an XCTest bundle.
+
+let runner = TestRunner()
+
+DiscoverySuite.run(runner)
+ModelDecodingSuite.run(runner)
+FormattingSuite.run(runner)
+CompanionSettingsSuite.run(runner)
+TimelineDecodingSuite.run(runner)
+MenuBarTitleSuite.run(runner)
+WidgetSnapshotSuite.run(runner)
+TransportSuite.run(runner)
+SnapshotStateSuite.run(runner)
+PollingSuite.run(runner)
+ActionSuite.run(runner)
+
+exit(runner.summarize())
diff --git a/app/Sources/OpenCodexWidget/Provider.swift b/app/Sources/OpenCodexWidget/Provider.swift
new file mode 100644
index 00000000000..e23d55f6042
--- /dev/null
+++ b/app/Sources/OpenCodexWidget/Provider.swift
@@ -0,0 +1,47 @@
+import Foundation
+import WidgetKit
+import MenuBarCore
+
+public struct SnapshotEntry: TimelineEntry {
+    public let date: Date
+    public let snapshot: WidgetSnapshot?
+    public let failure: ReadFailure?
+    public let stale: Bool
+}
+
+public struct SnapshotProvider: TimelineProvider {
+    private let reader = SnapshotReader()
+
+    public init() {}
+
+    public func placeholder(in context: Context) -> SnapshotEntry {
+        SnapshotEntry(date: Date(), snapshot: Self.sample, failure: nil, stale: false)
+    }
+
+    public func getSnapshot(in context: Context, completion: @escaping (SnapshotEntry) -> Void) {
+        completion(readEntry())
+    }
+
+    public func getTimeline(in context: Context, completion: @escaping (Timeline<SnapshotEntry>) -> Void) {
+        let now = Date()
+        completion(Timeline(entries: [readEntry(now: now)], policy: .after(now.addingTimeInterval(300))))
+    }
+
+    private func readEntry(now: Date = Date()) -> SnapshotEntry {
+        switch reader.read() {
+        case .failure(let failure):
+            return SnapshotEntry(date: now, snapshot: nil, failure: failure, stale: false)
+        case .success(let snapshot):
+            return SnapshotEntry(date: now, snapshot: snapshot, failure: nil, stale: snapshot.isStale(now: now))
+        }
+    }
+
+    private static let sample = WidgetSnapshot(
+        schemaVersion: 1, generatedAt: Date().timeIntervalSince1970,
+        state: "running", stateTitle: "Running", detail: "protected",
+        endpointDisplay: "127.0.0.1:10100", menuTitle: "12",
+        today: .init(requests: 12, totalTokens: 4_200, estimatedCostUsd: 0.12),
+        quotas: [.init(providerLabel: "OpenAI", windowLabel: "week", percent: 42, resetAt: Date().addingTimeInterval(86_400).timeIntervalSince1970)],
+        chart: nil, lastUpdated: Date().timeIntervalSince1970
+    )
+}
diff --git a/app/Sources/OpenCodexWidget/SnapshotReader.swift b/app/Sources/OpenCodexWidget/SnapshotReader.swift
new file mode 100644
index 00000000000..0c3b8fc66be
--- /dev/null
+++ b/app/Sources/OpenCodexWidget/SnapshotReader.swift
@@ -0,0 +1,31 @@
+import Foundation
+import MenuBarCore
+
+public enum ReadFailure: String, Error, Equatable, Sendable {
+    case missing
+    case corrupt
+}
+
+public extension WidgetSnapshot {
+    func isStale(now: Date = Date()) -> Bool {
+        now.timeIntervalSince1970 - generatedAt > 600
+    }
+}
+
+public struct SnapshotReader: Sendable {
+    public init() {}
+
+    public func read() -> Result<WidgetSnapshot, ReadFailure> {
+        let directory = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+        let url = directory.appendingPathComponent("OpenCodex/snapshot.json")
+        guard let data = try? Data(contentsOf: url) else { return .failure(.missing) }
+        guard let snapshot = try? JSONDecoder().decode(WidgetSnapshot.self, from: data) else {
+            return .failure(.corrupt)
+        }
+        return .success(snapshot)
+    }
+
+    public func isStale(_ snapshot: WidgetSnapshot, now: Date = Date()) -> Bool {
+        snapshot.isStale(now: now)
+    }
+}
diff --git a/app/Sources/OpenCodexWidget/Views.swift b/app/Sources/OpenCodexWidget/Views.swift
new file mode 100644
index 00000000000..7b8d6fc346c
--- /dev/null
+++ b/app/Sources/OpenCodexWidget/Views.swift
@@ -0,0 +1,321 @@
+import SwiftUI
+import WidgetKit
+import MenuBarCore
+
+struct OpenCodexWidgetView: View {
+    let entry: SnapshotEntry
+    @Environment(\.widgetFamily) private var family
+    @Environment(\.widgetRenderingMode) private var renderingMode
+
+    var body: some View {
+        Group {
+            if let failure = entry.failure {
+                failureView(failure)
+            } else if let snapshot = entry.snapshot {
+                content(snapshot)
+            } else {
+                failureView(.missing)
+            }
+        }
+        .containerBackground(.background, for: .widget)
+        .widgetURL(widgetURL)
+    }
+
+    private var widgetURL: URL? {
+        guard let display = entry.snapshot?.endpointDisplay,
+              let endpoint = URL(string: "http://\(display)"),
+              endpoint.host != nil, endpoint.port != nil
+        else { return nil }
+        return URL(string: "http://\(display)/#/usage")
+    }
+
+    @ViewBuilder
+    private func content(_ snapshot: WidgetSnapshot) -> some View {
+        switch family {
+        case .systemSmall:
+            small(snapshot)
+        case .systemLarge:
+            large(snapshot)
+        default:
+            medium(snapshot)
+        }
+    }
+
+    private func tone(_ snapshot: WidgetSnapshot) -> Color {
+        switch snapshot.state {
+        case "running": return .green
+        case "degraded": return .orange
+        case "unreachable", "unauthorized": return .red
+        default: return .secondary
+        }
+    }
+
+    private func small(_ snapshot: WidgetSnapshot) -> some View {
+        VStack(alignment: .leading, spacing: 7) {
+            HStack(spacing: 5) {
+                Circle().fill(tone(snapshot)).frame(width: 7, height: 7)
+                Text("OpenCodex").font(.caption).foregroundStyle(.secondary)
+            }
+            Text(Format.tokens(snapshot.today?.totalTokens))
+                .font(.system(size: 28, weight: .semibold, design: .rounded))
+                .lineLimit(1)
+                .widgetAccentable()
+            Text("tokens today").font(.caption).foregroundStyle(.secondary)
+            HStack(spacing: 4) {
+                Text("\(Format.count(snapshot.today?.requests)) req")
+                if let cost = snapshot.today?.estimatedCostUsd {
+                    Text("·")
+                    Text(Format.cost(cost))
+                }
+            }
+            .font(.caption2)
+            .foregroundStyle(.secondary)
+            .lineLimit(1)
+            updated(snapshot)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+    }
+
+    private func medium(_ snapshot: WidgetSnapshot) -> some View {
+        HStack(alignment: .top, spacing: 14) {
+            VStack(alignment: .leading, spacing: 5) {
+                status(snapshot)
+                metric("Tokens", Format.tokens(snapshot.today?.totalTokens))
+                metric("Requests", Format.count(snapshot.today?.requests))
+                if let cost = snapshot.today?.estimatedCostUsd { metric("Cost", Format.cost(cost)) }
+                updated(snapshot)
+            }
+            Divider()
+            if hasQuota(snapshot) {
+                quotaView(snapshot)
+            } else if let chart = snapshot.chart {
+                VStack(alignment: .leading, spacing: 5) {
+                    Text("Last \(windowLabel(chart))").font(.caption).foregroundStyle(.secondary)
+                    chartView(chart, flexible: false).widgetAccentable()
+                }
+            } else {
+                VStack(alignment: .leading, spacing: 4) {
+                    Text("No quota sources").font(.caption).foregroundStyle(.secondary)
+                    Text("Quota appears for providers that report limits")
+                        .font(.caption2).foregroundStyle(.secondary).lineLimit(2)
+                }
+            }
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+    }
+
+    private func large(_ snapshot: WidgetSnapshot) -> some View {
+        VStack(alignment: .leading, spacing: 10) {
+            status(snapshot)
+            metricsRow(snapshot)
+            if !snapshot.quotas.isEmpty {
+                VStack(alignment: .leading, spacing: 5) {
+                    ForEach(Array(snapshot.quotas.prefix(4).enumerated()), id: \.offset) { _, quota in
+                        quotaRow(quota)
+                    }
+                }
+            }
+            if let chart = snapshot.chart {
+                Text("Last \(windowLabel(chart)) · \(chart.series.count) models")
+                    .font(.caption).foregroundStyle(.secondary)
+                chartView(chart, flexible: true)
+                    .frame(maxHeight: .infinity)
+                    .widgetAccentable()
+                legend(chart)
+            }
+            updated(snapshot)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+    }
+
+    private func status(_ snapshot: WidgetSnapshot) -> some View {
+        HStack(spacing: 5) {
+            Circle().fill(tone(snapshot)).frame(width: 7, height: 7)
+            Text(([snapshot.stateTitle, snapshot.detail].compactMap { $0?.isEmpty == false ? $0 : nil }).joined(separator: " · "))
+                .font(.caption)
+                .foregroundStyle(.secondary)
+                .lineLimit(1)
+        }
+    }
+
+    private func metric(_ label: String, _ value: String) -> some View {
+        HStack {
+            Text(label).font(.caption).foregroundStyle(.secondary)
+            Spacer()
+            Text(value).font(.system(.body, design: .monospaced))
+        }
+    }
+
+    private func metricsRow(_ snapshot: WidgetSnapshot) -> some View {
+        HStack(spacing: 10) {
+            metricColumn("TOKENS", Format.tokens(snapshot.today?.totalTokens))
+            metricColumn("REQUESTS", Format.count(snapshot.today?.requests))
+            metricColumn("COST", Format.cost(snapshot.today?.estimatedCostUsd))
+        }
+    }
+
+    private func metricColumn(_ label: String, _ value: String) -> some View {
+        VStack(alignment: .leading, spacing: 2) {
+            Text(label).font(.caption2).foregroundStyle(.secondary)
+            Text(value).font(.system(.body, design: .monospaced)).lineLimit(1)
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+    }
+
+    private func hasQuota(_ snapshot: WidgetSnapshot) -> Bool {
+        snapshot.quotas.contains { $0.percent != nil }
+    }
+
+    private func quotaView(_ snapshot: WidgetSnapshot) -> some View {
+        Group {
+            if let quota = snapshot.quotas.compactMap({ $0.percent == nil ? nil : $0 }).min(by: { ($0.percent ?? 100) < ($1.percent ?? 100) }) {
+                VStack(alignment: .leading, spacing: 5) {
+                    Text(quota.providerLabel).font(.caption).lineLimit(1)
+                    ProgressView(value: (quota.percent ?? 0) / 100)
+                        .tint((quota.percent ?? 0) > 80 ? .orange : .green)
+                    Text("\(quota.windowLabel) · \(resets(in: quota.resetAt))")
+                        .font(.caption2).foregroundStyle(.secondary).lineLimit(1)
+                }
+            } else {
+                Text("No quota sources").font(.caption).foregroundStyle(.secondary)
+            }
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+    }
+
+    private func quotaRow(_ quota: WidgetSnapshot.Quota) -> some View {
+        HStack {
+            Text(quota.providerLabel).lineLimit(1)
+            Spacer()
+            Text("\(Format.percent(quota.percent)) · \(quota.windowLabel)")
+                .font(.caption).foregroundStyle(.secondary)
+        }
+    }
+
+    private func chartView(_ chart: WidgetSnapshot.Chart, flexible: Bool) -> some View {
+        GeometryReader { geometry in
+            if chart.style == "stackedBar" {
+                stackedBars(chart, in: geometry.size)
+            } else {
+                lineChart(chart, in: geometry.size)
+            }
+        }
+        .frame(minHeight: 72, maxHeight: flexible ? .infinity : 72)
+    }
+
+    private func legend(_ chart: WidgetSnapshot.Chart) -> some View {
+        LazyVGrid(columns: [GridItem(.flexible()), GridItem(.flexible())], alignment: .leading, spacing: 4) {
+            ForEach(Array(chart.series.prefix(5).enumerated()), id: \.offset) { index, series in
+                HStack(spacing: 4) {
+                    Circle().fill(seriesColor(index)).frame(width: 6, height: 6)
+                    Text(series.id)
+                        .font(.caption2)
+                        .lineLimit(1)
+                        .truncationMode(.middle)
+                }
+            }
+        }
+    }
+
+    private func lineChart(_ chart: WidgetSnapshot.Chart, in size: CGSize) -> some View {
+        ZStack {
+            ForEach(Array(chart.series.enumerated()), id: \.offset) { index, series in
+                Path { path in
+                    let maxValue = maxPoint(chart.series.flatMap(\.points))
+                    for pointIndex in series.points.indices {
+                        let x = series.points.count > 1
+                            ? size.width * CGFloat(pointIndex) / CGFloat(series.points.count - 1) : 0
+                        let y = size.height * (1 - CGFloat(series.points[pointIndex] / maxValue))
+                        if pointIndex == 0 { path.move(to: CGPoint(x: x, y: y)) }
+                        else { path.addLine(to: CGPoint(x: x, y: y)) }
+                    }
+                }
+                .stroke(seriesColor(index), lineWidth: 1.5)
+            }
+        }
+    }
+
+    private func stackedBars(_ chart: WidgetSnapshot.Chart, in size: CGSize) -> some View {
+        let count = chart.series.map(\.points.count).max() ?? 0
+        let maxValue = maxPoint((0..<count).map { index in
+            chart.series.reduce(0) { $0 + ($1.points.indices.contains(index) ? $1.points[index] : 0) }
+        })
+        return HStack(alignment: .bottom, spacing: 1) {
+            ForEach(0..<count, id: \.self) { index in
+                VStack(spacing: 0) {
+                    ForEach(Array(chart.series.enumerated()), id: \.offset) { seriesIndex, series in
+                        let value = series.points.indices.contains(index) ? series.points[index] : 0
+                        Rectangle()
+                            .fill(seriesColor(seriesIndex))
+                            .frame(height: max(0, size.height * value / maxValue))
+                    }
+                }
+            }
+        }
+    }
+
+    private let palette: [Color] = [
+        Color(red: 10 / 255, green: 132 / 255, blue: 1),
+        Color(red: 1, green: 159 / 255, blue: 10 / 255),
+        Color(red: 48 / 255, green: 209 / 255, blue: 88 / 255),
+        Color(red: 191 / 255, green: 90 / 255, blue: 242 / 255),
+        Color(red: 1, green: 69 / 255, blue: 58 / 255),
+        Color(red: 100 / 255, green: 210 / 255, blue: 1)
+    ]
+
+    private func seriesColor(_ index: Int) -> Color {
+        if renderingMode == .accented {
+            return .primary.opacity([1, 0.8, 0.6, 0.45, 0.3, 0.2][index % 6])
+        }
+        return palette[index % palette.count]
+    }
+
+    private func windowLabel(_ chart: WidgetSnapshot.Chart) -> String {
+        let hours = chart.bucketSeconds * (chart.series.map(\.points.count).max() ?? 0) / 3600
+        if hours < 48 { return "\(hours)h" }
+        return "\(hours / 24)d"
+    }
+
+    private func maxPoint(_ points: [Double]) -> Double { max(points.max() ?? 1, 1) }
+
+    private func resets(in timestamp: Double?) -> String {
+        Format.resetsIn(timestamp.map(Date.init(timeIntervalSince1970:)))
+    }
+
+    private func updated(_ snapshot: WidgetSnapshot) -> some View {
+        let text = snapshot.lastUpdated.map { "Updated \(Format.age(Date(timeIntervalSince1970: $0)))" } ?? "Not updated"
+        return Text(text).font(.caption2).foregroundStyle(entry.stale ? .orange : .secondary).lineLimit(1)
+    }
+
+    private func failureView(_ failure: ReadFailure) -> some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Image(systemName: failure == .missing ? "rectangle.on.rectangle" : "exclamationmark.triangle")
+                .font(.title2)
+            Text(failure == .missing
+                 ? "Open the OpenCodex desktop app to start sharing usage."
+                 : "Snapshot unreadable — refresh from the desktop app.")
+                .font(.caption)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+    }
+}
+
+@main
+struct OpenCodexWidgetBundle: WidgetBundle {
+    var body: some Widget {
+        OpenCodexWidget()
+    }
+}
+
+struct OpenCodexWidget: Widget {
+    let kind = "OpenCodexWidget"
+
+    var body: some WidgetConfiguration {
+        StaticConfiguration(kind: kind, provider: SnapshotProvider()) { entry in
+            OpenCodexWidgetView(entry: entry)
+        }
+        .configurationDisplayName("OpenCodex")
+        .description("Proxy status, today's usage, and quota at a glance.")
+        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
+    }
+}
diff --git a/app/Widget-Info.plist b/app/Widget-Info.plist
new file mode 100644
index 00000000000..df499104290
--- /dev/null
+++ b/app/Widget-Info.plist
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key><string>en</string>
+  <key>CFBundleExecutable</key><string>OpenCodexWidget</string>
+  <key>CFBundleIdentifier</key><string>com.opencodex.desktop.widget</string>
+  <key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
+  <key>CFBundleName</key><string>OpenCodex</string>
+  <key>CFBundleDisplayName</key><string>OpenCodex</string>
+  <!--
+    Every widget macOS itself ships declares a supported platform, and no third-party guidance
+    mentions it because Xcode writes it for you. A SwiftPM-assembled appex has no build system to
+    write it, and an extension bundle that does not say which platform it supports gives the
+    system no reason to consider it on this one.
+  -->
+  <key>CFBundleSupportedPlatforms</key>
+  <array><string>MacOSX</string></array>
+  <key>CFBundlePackageType</key><string>XPC!</string>
+  <key>CFBundleShortVersionString</key><string>0.0.0</string>
+  <key>CFBundleVersion</key><string>0.0.0</string>
+  <key>LSMinimumSystemVersion</key><string>14.0</string>
+  <key>NSHumanReadableCopyright</key><string>MIT — opencodex contributors</string>
+  <key>NSExtension</key>
+  <dict>
+    <key>NSExtensionPointIdentifier</key><string>com.apple.widgetkit-extension</string>
+  </dict>
+</dict>
+</plist>
diff --git a/app/Widget.entitlements b/app/Widget.entitlements
new file mode 100644
index 00000000000..1b44cd3cd24
--- /dev/null
+++ b/app/Widget.entitlements
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>com.apple.security.app-sandbox</key>
+  <true/>
+</dict>
+</plist>
diff --git a/assets/pr-screenshots/app-icon-finder-menubar.png b/assets/pr-screenshots/app-icon-finder-menubar.png
new file mode 100644
index 00000000000..794afb137d4
Binary files /dev/null and b/assets/pr-screenshots/app-icon-finder-menubar.png differ
diff --git a/assets/pr-screenshots/favicon-browser-tab.png b/assets/pr-screenshots/favicon-browser-tab.png
new file mode 100644
index 00000000000..3642c0afe15
Binary files /dev/null and b/assets/pr-screenshots/favicon-browser-tab.png differ
diff --git a/assets/pr-screenshots/favicon-light-tab.png b/assets/pr-screenshots/favicon-light-tab.png
new file mode 100644
index 00000000000..803ab3b32ad
Binary files /dev/null and b/assets/pr-screenshots/favicon-light-tab.png differ
diff --git a/bin/ocx.mjs b/bin/ocx.mjs
index 7b3a54eaa2c..fef7686638c 100755
--- a/bin/ocx.mjs
+++ b/bin/ocx.mjs
@@ -12,6 +12,21 @@ import { spawn, spawnSync } from "node:child_process";
 import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "../src/update/stop-contract.mjs";
 import { probeProxyLiveness } from "../src/update/proxy-liveness-probe.mjs";
 import { decidePostStopUpdate } from "../src/update/stop-decision.mjs";
+import {
+  inspectPackageRuntimeLiveness,
+  planStoppedRuntimeRecovery,
+  planUpdateRuntimeHandling,
+} from "../src/update/runtime-ownership.mjs";
+import {
+  inspectInstallStateBytes,
+  selectAuthoritativeServiceState,
+  serviceStateFilesFor,
+} from "../src/service/install-state-contract.mjs";
+import {
+  acquireOwnershipMutationLease,
+  ownershipMutationLeaseChildEnvironment,
+  unprivilegedOwnershipMutationEnvironment,
+} from "../src/service/ownership-mutation-lease.mjs";
 import { randomBytes } from "node:crypto";
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
@@ -41,6 +56,9 @@ import {
 } from "../src/update/codex-cli-update-launch-policy.mjs";
 
 const PKG = "@bitkyc08/opencodex";
+const UPDATE_RECOVERY_READY_MS = 30_000;
+const UPDATE_RECOVERY_POLL_MS = 100;
+const UPDATE_RECOVERY_SLEEP = new Int32Array(new SharedArrayBuffer(4));
 try {
   process.cwd();
 } catch {
@@ -256,8 +274,45 @@ function runPackageManagerSelfUpdate(manager) {
 
   // Remember whether a background service manages the proxy BEFORE stopping — `ocx stop`
   // unloads it, so a successful update must refresh and restart it afterwards.
-  const serviceStatePath = join(configDir(), "service-state.json");
-  const serviceWasInstalled = existsSync(serviceStatePath);
+  const allServiceStatePaths = serviceStateFilesFor(configDir(), join(homedir(), ".opencodex"));
+  // The test guard's legacy path is the developer's real home. Production always reads the
+  // same active-home + default-home observations as the Bun resolver.
+  const serviceStatePaths = process.env.OCX_TEST_HOME_GUARD === "1"
+    ? allServiceStatePaths.slice(0, 1)
+    : allServiceStatePaths;
+  const serviceWasInstalled = serviceStatePaths.some(path => existsSync(path));
+  // What this update may do to the runtime. The same rule the Bun updater applies, from the
+  // same module: a desktop takeover vetoes both the stop and the service refresh below.
+  const readServiceState = () => selectAuthoritativeServiceState(
+    serviceStatePaths.map(path => inspectInstallStateBytes(path, at => readFileSync(at, "utf8"))),
+  );
+  const readOwnership = () => {
+    const selected = readServiceState();
+    if (selected.kind === "unknown") return { ownership: null, ownershipUnknown: true, subjectToken: "unknown" };
+    if (selected.kind === "none") return {
+      ownership: null, ownershipUnknown: false, subjectToken: JSON.stringify(["none", selected.revision]),
+    };
+    const ownership = selected.state.ownership ?? null;
+    return {
+      ownership,
+      ownershipUnknown: false,
+      subjectToken: JSON.stringify(ownership
+        ? ["owned", selected.revision, ownership]
+        : ["none", selected.revision]),
+    };
+  };
+  const ownershipIdentity = observation => observation.ownershipUnknown
+    ? null
+    : JSON.stringify(observation.ownership
+      ? ["owned", observation.ownership.owner, observation.ownership.installId, observation.ownership.consentGeneration]
+      : ["none"]);
+  const initialOwnership = readOwnership();
+  let runtimePlan = planUpdateRuntimeHandling({ ...initialOwnership, serviceInstalled: serviceWasInstalled });
+  if (runtimePlan.notice) console.log(runtimePlan.notice);
+  if (!runtimePlan.mayReplacePackage) {
+    console.error("opencodex: update stopped before tray handoff, runtime stop, or package replacement because runtime ownership is unknown.");
+    process.exit(1);
+  }
   const trayBeforeUpdate = planWindowsTrayUpdate(
     process.platform === "win32" ? trayInstallState() : { installed: false, running: false },
   );
@@ -271,10 +326,11 @@ function runPackageManagerSelfUpdate(manager) {
   }
   /** Register from scratch, preserving the recorded backend. Only for a genuinely absent service. */
   function serviceInstallArgs() {
-    try {
-      const state = JSON.parse(readFileSync(serviceStatePath, "utf8"));
-      if (state.backend === "native") return [postUpdateLauncher, "service", "install", "--native"];
-    } catch { /* missing or corrupt — fall through to default */ }
+    const selected = readServiceState();
+    if (selected.kind === "unknown") throw new Error(`service backend is unknown: ${selected.reason}`);
+    if (selected.kind === "state" && selected.state.backend === "native") {
+      return [postUpdateLauncher, "service", "install", "--native"];
+    }
     return [postUpdateLauncher, "service", "install"];
   }
   /**
@@ -302,39 +358,45 @@ function runPackageManagerSelfUpdate(manager) {
     }
   }
 
-  // Capture listen target before stop clears runtime-port.json (mirrors GUI/CLI update worker).
-  // Do not treat a live runtime port of 10100 as "missing" — track whether the read succeeded.
+  function readCurrentRuntimeTarget() {
+    let raw;
+    try {
+      raw = readFileSync(join(configDir(), "runtime-port.json"), "utf8");
+    } catch (error) {
+      return error && typeof error === "object" && "code" in error && error.code === "ENOENT"
+        ? { kind: "absent" }
+        : { kind: "unknown" };
+    }
+    try {
+      const rt = JSON.parse(raw);
+      const pid = Number(rt?.pid);
+      if (!Number.isFinite(rt?.port) || rt.port <= 0 || rt.port > 65535
+        || !Number.isSafeInteger(pid) || pid <= 0) return { kind: "unknown" };
+      return { kind: "target", target: {
+        pid,
+        port: Math.trunc(rt.port),
+        hostname: typeof rt.hostname === "string" && rt.hostname.trim() !== ""
+          ? rt.hostname.trim()
+          : null,
+      } };
+    } catch { return { kind: "unknown" }; }
+  }
+
+  // Capture the recovery target before stop clears runtime-port.json. Replacement safety
+  // re-reads this record under the mutation lease instead of trusting this snapshot.
   let bakePort = 10100;
   // The hostname travels with the port: a proxy bound to ::1 or a specific interface is
   // invisible to a probe that assumes 127.0.0.1, and "no answer" would then read as
   // "stopped" for exactly the proxy the probe exists to find.
   let bakeHostname = "127.0.0.1";
-  let sawRuntimePort = false;
-  let sawRuntimeHostname = false;
-  try {
-    const rt = JSON.parse(readFileSync(join(configDir(), "runtime-port.json"), "utf8"));
-    if (Number.isFinite(rt?.port) && rt.port > 0 && rt.port <= 65535) {
-      // Only trust runtime when its pid still looks alive (stale crash leftovers fall back to config).
-      const rtPid = Number(rt?.pid);
-      let runtimeLive = false;
-      if (Number.isSafeInteger(rtPid) && rtPid > 0) {
-        try {
-          process.kill(rtPid, 0);
-          runtimeLive = true;
-        } catch (e) {
-          if (e && typeof e === "object" && "code" in e && e.code === "EPERM") runtimeLive = true;
-        }
-      }
-      if (runtimeLive) {
-        bakePort = Math.trunc(rt.port);
-        if (typeof rt?.hostname === "string" && rt.hostname.trim() !== "") {
-          bakeHostname = rt.hostname.trim();
-          sawRuntimeHostname = true;
-        }
-        sawRuntimePort = true;
-      }
-    }
-  } catch { /* fall through to config */ }
+  const initialRuntimeObservation = readCurrentRuntimeTarget();
+  const initialRuntimeTarget = initialRuntimeObservation.kind === "target" ? initialRuntimeObservation.target : null;
+  let sawRuntimePort = initialRuntimeTarget !== null;
+  let sawRuntimeHostname = initialRuntimeTarget?.hostname !== null && initialRuntimeTarget?.hostname !== undefined;
+  if (initialRuntimeTarget) {
+    bakePort = initialRuntimeTarget.port;
+    if (initialRuntimeTarget.hostname) bakeHostname = initialRuntimeTarget.hostname;
+  }
   // Port and hostname resolve INDEPENDENTLY: a legacy runtime record carries a port and no
   // hostname, and skipping config in that case probed 127.0.0.1 for a proxy bound to ::1.
   if (!sawRuntimePort || bakeHostname === "127.0.0.1") {
@@ -350,6 +412,18 @@ function runPackageManagerSelfUpdate(manager) {
   }
   // Wildcard and bracketed-IPv6 normalization lives in probeProxyLiveness, so both lanes
   // get it from one place.
+  function currentPackageRuntimeLiveness() {
+    return inspectPackageRuntimeLiveness({
+      capturedTarget: { port: bakePort, hostname: bakeHostname },
+      readCurrentTarget: () => {
+        const current = readCurrentRuntimeTarget();
+        return current.kind === "target"
+          ? { kind: "target", target: { port: current.target.port, hostname: current.target.hostname ?? bakeHostname } }
+          : current;
+      },
+      probe: target => probeProxyLiveness(target.port, target.hostname),
+    }).overall;
+  }
 
   const launcher = fileURLToPath(import.meta.url);
   // The pnpm owner preflight has verified this package tree and global group. Keep that exact
@@ -359,13 +433,17 @@ function runPackageManagerSelfUpdate(manager) {
     ? join(owner.packagePath, "bin", "ocx.mjs")
     : launcher;
   let postUpdateLauncherUsable = true;
+  let delegatedOwnershipMutationToken = null;
+  const mutationChildEnvironment = () => delegatedOwnershipMutationToken
+    ? ownershipMutationLeaseChildEnvironment(process.env, delegatedOwnershipMutationToken)
+    : unprivilegedOwnershipMutationEnvironment(process.env);
 
   function startProxyDirectly() {
     if (!postUpdateLauncherUsable || !existsSync(postUpdateLauncher)) {
       console.error("opencodex: cannot restart the proxy because the launcher is missing; reinstall opencodex manually.");
-      return;
+      return false;
     }
-    const env = { ...process.env };
+    const env = mutationChildEnvironment();
     delete env.OCX_SERVICE;
     console.log(`Attempting to restart the proxy on port ${bakePort}.`);
     const child = spawn(process.execPath, [postUpdateLauncher, "start", "--port", String(bakePort)], {
@@ -378,13 +456,24 @@ function runPackageManagerSelfUpdate(manager) {
       console.error(`opencodex: direct proxy restart failed: ${error.message}`);
     });
     child.unref();
+    const deadline = Date.now() + UPDATE_RECOVERY_READY_MS;
+    while (Date.now() < deadline) {
+      const current = readCurrentRuntimeTarget();
+      if (current.kind === "target"
+        && probeProxyLiveness(current.target.port, current.target.hostname ?? bakeHostname) === "live") return true;
+      Atomics.wait(UPDATE_RECOVERY_SLEEP, 0, 0, UPDATE_RECOVERY_POLL_MS);
+    }
+    console.error("opencodex: the recovery proxy did not publish a healthy runtime before the recovery deadline.");
+    return false;
   }
 
   function refreshBackgroundServiceOrStartDirect() {
     const prevBake = process.env.OCX_BAKE_PORT;
     process.env.OCX_BAKE_PORT = String(bakePort);
     try {
-      let svc = spawnSync(process.execPath, serviceRefreshArgs(), { stdio: "inherit", windowsHide: true });
+      let svc = spawnSync(process.execPath, serviceRefreshArgs(), {
+        stdio: "inherit", windowsHide: true, env: mutationChildEnvironment(),
+      });
       // `serviceWasInstalled` is inferred from service-state.json alone, which can be
       // STALE — present while the registration is gone. Repair refuses that case by
       // design, and its thrown Error is indistinguishable from any other failure at
@@ -395,7 +484,9 @@ function runPackageManagerSelfUpdate(manager) {
       // could re-register a service the user just uninstalled.
       if (svc.status !== 0 && readServiceInstalledFromStatus(postUpdateLauncher) === false) {
         console.log("No registered service found — installing it instead.");
-        svc = spawnSync(process.execPath, serviceInstallArgs(), { stdio: "inherit", windowsHide: true });
+        svc = spawnSync(process.execPath, serviceInstallArgs(), {
+          stdio: "inherit", windowsHide: true, env: mutationChildEnvironment(),
+        });
       }
       let needDirectStart = svc.status !== 0;
       if (!needDirectStart) {
@@ -421,6 +512,14 @@ function runPackageManagerSelfUpdate(manager) {
         }
       }
       if (needDirectStart) {
+        // Re-read rather than reuse the plan from before the package install: the app can
+        // claim the runtime during an update that takes minutes, and the refusal that repair
+        // just returned is indistinguishable from any other failure at this layer.
+        const nowOwned = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: true });
+        if (!nowOwned.mayStopRuntime) {
+          console.warn(nowOwned.notice ?? "opencodex: the background runtime is owned elsewhere; not starting a second proxy.");
+          return;
+        }
         // Repair normally avoids elevation for a healthy registration, but a stale Windows
         // scheduler definition can require it. It can also fail — or exit 0 while leaving
         // a non-viable manager. Fall back to a direct detached proxy start so the
@@ -439,189 +538,264 @@ function runPackageManagerSelfUpdate(manager) {
     }
   }
 
-  // Never replace package files under a live proxy — stop it first (full `ocx stop`
-  // semantics: graceful drain, service stop, native Codex restore). Gate on the service
-  // and the runtime-port record too: a service-managed or orphaned proxy can be live
-  // while ocx.pid is stale/missing.
-  if (trayBeforeUpdate.stopBeforeReplacement) {
-    console.log("⏹  Handing off the Windows tray before updating...");
-    try {
-      handoffWindowsTrayForUpdate(trayBeforeUpdate, {
-        stop: () => {
-          const stopped = runTrayLifecycle(launcher, "stop");
-          return { exitStatus: stopped.status, running: trayInstallState().running };
-        },
-        start: () => runTrayLifecycle(launcher, "start"),
-      });
-    } catch {
-      console.error("opencodex: could not stop the Windows tray; aborting before package replacement.");
+  const updateLease = acquireOwnershipMutationLease(serviceStatePaths);
+  delegatedOwnershipMutationToken = updateLease.token;
+  let updateLeaseReleased = false;
+  const releaseUpdateLease = () => {
+    if (updateLeaseReleased) return;
+    updateLeaseReleased = true;
+    delegatedOwnershipMutationToken = null;
+    updateLease.release();
+  };
+
+  let res;
+  try {
+    // Stop authority is decided under the same lease the child joins. A takeover between the
+    // earlier preflight and this boundary therefore blocks stop before it is sent.
+    const lockedOwnership = readOwnership();
+    const lockedPlan = planUpdateRuntimeHandling({ ...lockedOwnership, serviceInstalled: serviceWasInstalled });
+    if (lockedOwnership.subjectToken !== initialOwnership.subjectToken || !lockedPlan.mayReplacePackage) {
+      releaseUpdateLease();
+      console.error(lockedPlan.notice
+        ?? "opencodex: update stopped because runtime ownership changed before stop authorization; rerun from the beginning.");
       process.exit(1);
     }
-  }
-  const hasRuntimeState =
-    existsSync(join(configDir(), "ocx.pid")) || existsSync(join(configDir(), "runtime-port.json"));
+    runtimePlan = lockedPlan;
+    const stoppedOwnershipIdentity = ownershipIdentity(lockedOwnership);
 
-  function recoverStoppedRuntimeAfterFailure() {
-    if (!postUpdateLauncherUsable) {
-      console.error("opencodex: no verified active launcher remains for automatic recovery; reinstall opencodex manually.");
-      return;
+    // Never replace package files under a live proxy — stop it first (full `ocx stop`
+    // semantics: graceful drain, service stop, native Codex restore). Gate on the service
+    // and the runtime-port record too: a service-managed or orphaned proxy can be live
+    // while ocx.pid is stale/missing.
+    if (trayBeforeUpdate.stopBeforeReplacement) {
+      console.log("⏹  Handing off the Windows tray before updating...");
+      try {
+        handoffWindowsTrayForUpdate(trayBeforeUpdate, {
+          stop: () => {
+            const stopped = runTrayLifecycle(launcher, "stop");
+            return { exitStatus: stopped.status, running: trayInstallState().running };
+          },
+          start: () => runTrayLifecycle(launcher, "start"),
+        });
+      } catch {
+        releaseUpdateLease();
+        console.error("opencodex: could not stop the Windows tray; aborting before package replacement.");
+        process.exit(1);
+      }
     }
-    if (serviceWasInstalled) {
-      console.warn("opencodex: update failed after stopping the proxy — restoring the previous background service.");
-      refreshBackgroundServiceOrStartDirect();
-    } else if (hasRuntimeState) {
-      console.warn("opencodex: update failed after stopping the proxy — restarting the previous version directly.");
-      startProxyDirectly();
+    const hasRuntimeState =
+      existsSync(join(configDir(), "ocx.pid")) || existsSync(join(configDir(), "runtime-port.json"));
+    let stopAttempted = false;
+
+    function recoverStoppedRuntimeAfterFailure(reason) {
+      const recoveryOwnership = readOwnership();
+      const recoveryLiveness = currentPackageRuntimeLiveness();
+      const recovery = planStoppedRuntimeRecovery({
+        stopAttempted,
+        ...recoveryOwnership,
+        sameOwner: ownershipIdentity(recoveryOwnership) === stoppedOwnershipIdentity,
+        liveness: recoveryLiveness,
+        serviceInstalled: serviceWasInstalled,
+        launcherUsable: postUpdateLauncherUsable,
+        hadRuntimeState: hasRuntimeState,
+      });
+      if (recovery.reason === "ownership-unknown") {
+        console.error(`opencodex: ${reason}; runtime ownership is unknown, so automatic recovery was refused. Run 'ocx status --json' and repair the service-state record before retrying.`);
+      } else if (recovery.reason === "ownership-transferred") {
+        console.log("opencodex: runtime ownership moved to another installation; the stopped CLI runtime was not revived.");
+      } else if (recovery.reason.startsWith("runtime-")) {
+        console.error(`opencodex: ${reason}; package runtime liveness is ${recoveryLiveness}, so automatic recovery was refused.`);
+      } else if (recovery.reason === "launcher-unavailable") {
+        console.error("opencodex: no verified active launcher remains for automatic recovery; reinstall opencodex manually.");
+      } else if (recovery.action === "service") {
+        console.warn(`opencodex: ${reason} after stopping the proxy — restoring the previous background service.`);
+        refreshBackgroundServiceOrStartDirect();
+      } else if (recovery.action === "direct") {
+        console.warn(`opencodex: ${reason} after stopping the proxy — restarting the previous version directly.`);
+        startProxyDirectly();
+      }
+      return recovery;
     }
-  }
 
-  // An outstanding pending-teardown receipt is a fourth reason to run the stop. After a
-  // parent crashed mid-deferral the service, pid and runtime records can all be absent
-  // while the shared client config still points at a proxy that is gone; installing over
-  // that silently skips the recovery the receipt was written to trigger (#3008). Presence
-  // is the whole test here — the launcher cannot parse it, and `ocx stop` is what decides
-  // whether the obligation is safe to finish.
-  const hasPendingTeardown = hasPendingTeardownIn(readdirSync, configDir());
-  if (serviceWasInstalled || hasRuntimeState || hasPendingTeardown) {
-    console.log("⏹  Stopping the running proxy before updating...");
-    const stopRes = spawnSync(process.execPath, [launcher, "stop"], { stdio: "inherit", windowsHide: true });
-    const stillHasRuntimeState =
-      existsSync(join(configDir(), "ocx.pid")) || existsSync(join(configDir(), "runtime-port.json"));
-    // A history-only failure means teardown succeeded and a backup manifest is waiting for
-    // review: the proxy is down and replacing package files is safe. Every other nonzero
-    // status is a stop that did not finish, and a signal kill (status null) says nothing
-    // about whether it did - both abort, because replacing files under a live server
-    // leaves it running mixed old and new modules (#3008).
-    // The same decision the Bun updater makes, from the same module (#3008). Absent PID and
-    // runtime files are weak evidence, so the captured endpoint is asked; "unknown" aborts
-    // because a silent listener is exactly the state where replacing files is dangerous.
-    const decision = decidePostStopUpdate({
-      status: stopRes.status,
-      hasRuntimeState: stillHasRuntimeState,
-      // Re-checked AFTER the stop: a quarantined receipt lets the stop itself succeed
-      // (there is nothing left to stop), so a pre-stop check alone let the retry install
-      // over a teardown that never ran.
-      teardownOutstanding: hasPendingTeardownIn(readdirSync, configDir()),
-      liveness: probeProxyLiveness(bakePort, bakeHostname),
-    });
-    const historyOnlyStop = decision.reason === "history-only";
-    if (!decision.proceed) {
-      if (trayBeforeUpdate.restoreOnFailure) runTrayLifecycle(launcher, "start");
-      if (decision.reason === "teardown-outstanding") {
-        console.error("opencodex: a shared teardown from an earlier stop is still outstanding and needs manual review; aborting the update.");
-        console.error("opencodex: confirm no proxy is running, run 'ocx restore', then remove the pending-teardown file in the opencodex home.");
-      } else console.error(decision.reason === "proxy-unknown"
-        ? `opencodex: could not confirm the proxy on ${bakeHostname}:${bakePort} is stopped; aborting the update. Run 'ocx stop' and retry.`
-        : "opencodex: could not stop the running proxy; aborting the update. Run 'ocx stop' and retry.");
+    // An outstanding pending-teardown receipt is a fourth reason to run the stop. After a
+    // parent crashed mid-deferral the service, pid and runtime records can all be absent
+    // while the shared client config still points at a proxy that is gone; installing over
+    // that silently skips the recovery the receipt was written to trigger (#3008). Presence
+    // is the whole test here — the launcher cannot parse it, and `ocx stop` is what decides
+    // whether the obligation is safe to finish.
+    const hasPendingTeardown = hasPendingTeardownIn(readdirSync, configDir());
+    const stopNeeded = serviceWasInstalled || hasRuntimeState || hasPendingTeardown;
+    if (stopNeeded && !runtimePlan.mayStopRuntime) {
+      releaseUpdateLease();
+      console.error(runtimePlan.notice
+        ?? "opencodex: update stopped because this installation may not stop the current runtime.");
       process.exit(1);
     }
-    if (historyOnlyStop || historyRestoreIncomplete()) {
-      console.warn(
-        "opencodex: WARNING — Codex resume-history metadata restore is incomplete (a backup manifest remains).\n" +
-        "  The DB may be busy or the manifest/target may need review; untracked routed history is intentionally unchanged.\n" +
-        "  After the update: close the Codex app, run 'ocx doctor', then run 'ocx stop' once to retry.",
-      );
+    if (stopNeeded) {
+      stopAttempted = true;
+      console.log("⏹  Stopping the running proxy before updating...");
+      const stopRes = spawnSync(process.execPath, [launcher, "stop"], {
+        stdio: "inherit", windowsHide: true, env: mutationChildEnvironment(),
+      });
+      const stillHasRuntimeState =
+        existsSync(join(configDir(), "ocx.pid")) || existsSync(join(configDir(), "runtime-port.json"));
+      // A history-only failure means teardown succeeded and a backup manifest is waiting for
+      // review: the proxy is down and replacing package files is safe. Every other nonzero
+      // status is a stop that did not finish, and a signal kill (status null) says nothing
+      // about whether it did - both abort, because replacing files under a live server
+      // leaves it running mixed old and new modules (#3008).
+      // The same decision the Bun updater makes, from the same module (#3008). Absent PID and
+      // runtime files are weak evidence, so the captured endpoint is asked; "unknown" aborts
+      // because a silent listener is exactly the state where replacing files is dangerous.
+      const decision = decidePostStopUpdate({
+        status: stopRes.status,
+        hasRuntimeState: stillHasRuntimeState,
+        // Re-checked AFTER the stop: a quarantined receipt lets the stop itself succeed
+        // (there is nothing left to stop), so a pre-stop check alone let the retry install
+        // over a teardown that never ran.
+        teardownOutstanding: hasPendingTeardownIn(readdirSync, configDir()),
+        liveness: probeProxyLiveness(bakePort, bakeHostname),
+      });
+      const historyOnlyStop = decision.reason === "history-only";
+      if (!decision.proceed) {
+        if (trayBeforeUpdate.restoreOnFailure) runTrayLifecycle(launcher, "start");
+        if (decision.reason === "teardown-outstanding") {
+          console.error("opencodex: a shared teardown from an earlier stop is still outstanding and needs manual review; aborting the update.");
+          console.error("opencodex: confirm no proxy is running, run 'ocx restore', then remove the pending-teardown file in the opencodex home.");
+        } else console.error(decision.reason === "proxy-unknown"
+          ? `opencodex: could not confirm the proxy on ${bakeHostname}:${bakePort} is stopped; aborting the update. Run 'ocx stop' and retry.`
+          : "opencodex: could not stop the running proxy; aborting the update. Run 'ocx stop' and retry.");
+        releaseUpdateLease();
+        process.exit(1);
+      }
+      if (historyOnlyStop || historyRestoreIncomplete()) {
+        console.warn(
+          "opencodex: WARNING — Codex resume-history metadata restore is incomplete (a backup manifest remains).\n" +
+          "  The DB may be busy or the manifest/target may need review; untracked routed history is intentionally unchanged.\n" +
+          "  After the update: close the Codex app, run 'ocx doctor', then run 'ocx stop' once to retry.",
+        );
+      }
+      if (decision.reason === "history-deferred") {
+        // The reported #4718 path is this lane. Nothing was restored, so this is a different
+        // sentence from the manifest warning above: an operator told "history metadata is
+        // incomplete" would assume config and catalog already came back.
+        console.warn(
+          "opencodex: WARNING — the shared teardown was refused by the Codex history preflight and restored nothing.\n" +
+          "  Config, catalog, history and provenance were preserved, and the teardown receipt was kept.\n" +
+          "  The proxy is down, so the update continues; close the Codex app and run 'ocx stop' once afterwards to finish the restore.",
+        );
+      }
     }
-    if (decision.reason === "history-deferred") {
-      // The reported #4718 path is this lane. Nothing was restored, so this is a different
-      // sentence from the manifest warning above: an operator told "history metadata is
-      // incomplete" would assume config and catalog already came back.
-      console.warn(
-        "opencodex: WARNING — the shared teardown was refused by the Codex history preflight and restored nothing.\n" +
-        "  Config, catalog, history and provenance were preserved, and the teardown receipt was kept.\n" +
-        "  The proxy is down, so the update continues; close the Codex app and run 'ocx stop' once afterwards to finish the restore.",
-      );
+
+    const replacementOwnership = readOwnership();
+    const replacementPlan = planUpdateRuntimeHandling({ ...replacementOwnership, serviceInstalled: serviceWasInstalled });
+    const replacementLiveness = currentPackageRuntimeLiveness();
+    if (replacementOwnership.subjectToken !== initialOwnership.subjectToken
+      || !replacementPlan.mayReplacePackage
+      || replacementLiveness !== "dead") {
+      recoverStoppedRuntimeAfterFailure("replacement was refused");
+      releaseUpdateLease();
+      if (trayBeforeUpdate.restoreOnFailure) runTrayLifecycle(launcher, "start");
+      console.error(replacementPlan.notice
+        ?? "opencodex: update stopped because runtime ownership or liveness changed after the stop decision; rerun from the beginning.");
+      process.exit(1);
     }
-  }
 
-  // npm keeps the existing stage -> verify -> swap -> rollback flow. pnpm owns a
-  // content-addressable store and generated global shims, so its path uses pnpm's own
-  // global update operation and verifies the active group instead of renaming files.
-  console.log(`Updating${latest ? ` to v${latest}` : ""} (${manager === "npm" ? "transactional" : "pnpm-managed"})...`);
-  let res;
-  try {
-    if (manager === "npm") {
-      const packageDir = resolve(here, "..");
-      const tx = transactionalNpmUpdate({
-        packageDir,
-        pkgName: PKG,
-        targetVersion: latest || undefined,
-        tag,
-        runNpm: (args) => {
-          const invocation = npmInvocation(args);
-          if (!invocation) return { status: 1 };
-          return spawnSync(invocation.file, invocation.args, {
-            stdio: "inherit",
-            timeout: 180000,
-            windowsHide: true,
-            ...invocation.options,
-          });
-        },
-        log: (line) => console.log(line),
-      });
-      postUpdateLauncherUsable = tx.ok
-        || tx.rolledBack === true
-        || ["stage", "verify", "swap-backup"].includes(tx.phase);
-      if (tx.ok) {
-        res = { status: 0 };
-      } else if (tx.phase === "stage" || tx.phase === "verify") {
-        // Live tree untouched: report and stop. Nothing to roll back.
-        console.error(`opencodex: update aborted before touching the live install (${tx.phase}): ${tx.error}`);
-        res = { status: 1 };
-      } else {
-        console.error(`opencodex: update failed (${tx.phase}): ${tx.error}${tx.rolledBack ? " — previous version restored." : ""}`);
-        res = { status: 1 };
-      }
-    } else {
-      const update = runPnpmGlobalUpdate({
-        packageName: PKG,
-        currentVersion: current,
-        targetVersion: latest || undefined,
-        tag,
-        owner,
-        runningPackagePath: resolve(here, ".."),
-        runPnpm: (args, capture = false) => {
-          const invocation = pnpmOwnerInvocation(owner, args);
-          if (!invocation) return { status: 1 };
-          return spawnSync(invocation.file, invocation.args, {
-            stdio: capture ? "pipe" : "inherit",
-            encoding: "utf8",
-            timeout: 180000,
-            windowsHide: true,
-            env: invocation.env,
-            ...invocation.options,
-          });
-        },
-        log: line => console.log(line),
-      });
-      if (update.ok) {
-        // pnpm switches the active global group and updates its shim. Continue recovery
-        // through that fresh package tree, not the old group whose launcher is still
-        // executing this update.
-        postUpdateLauncher = join(update.path, "bin", "ocx.mjs");
-        res = { status: 0 };
+    // npm keeps the existing stage -> verify -> swap -> rollback flow. pnpm owns a
+    // content-addressable store and generated global shims, so its path uses pnpm's own
+    // global update operation and verifies the active group instead of renaming files.
+    console.log(`Updating${latest ? ` to v${latest}` : ""} (${manager === "npm" ? "transactional" : "pnpm-managed"})...`);
+    try {
+      if (manager === "npm") {
+        const packageDir = resolve(here, "..");
+        const tx = transactionalNpmUpdate({
+          packageDir,
+          pkgName: PKG,
+          targetVersion: latest || undefined,
+          tag,
+          runNpm: (args) => {
+            const invocation = npmInvocation(args);
+            if (!invocation) return { status: 1 };
+            return spawnSync(invocation.file, invocation.args, {
+              ...invocation.options,
+              stdio: "inherit",
+              timeout: 180000,
+              windowsHide: true,
+              env: unprivilegedOwnershipMutationEnvironment(invocation.options?.env ?? process.env),
+            });
+          },
+          log: (line) => console.log(line),
+        });
+        postUpdateLauncherUsable = tx.ok
+          || tx.rolledBack === true
+          || ["stage", "verify", "swap-backup"].includes(tx.phase);
+        if (tx.ok) {
+          res = { status: 0 };
+        } else if (tx.phase === "stage" || tx.phase === "verify") {
+          // Live tree untouched: report and stop. Nothing to roll back.
+          console.error(`opencodex: update aborted before touching the live install (${tx.phase}): ${tx.error}`);
+          res = { status: 1 };
+        } else {
+          console.error(`opencodex: update failed (${tx.phase}): ${tx.error}${tx.rolledBack ? " — previous version restored." : ""}`);
+          res = { status: 1 };
+        }
       } else {
-        console.error(`opencodex: ${update.error}${update.rolledBack ? "." : " Manual recovery may be required."}`);
-        postUpdateLauncherUsable = Boolean(update.activePath);
-        if (update.activePath) postUpdateLauncher = join(update.activePath, "bin", "ocx.mjs");
-        res = { status: 1 };
+        const update = runPnpmGlobalUpdate({
+          packageName: PKG,
+          currentVersion: current,
+          targetVersion: latest || undefined,
+          tag,
+          owner,
+          runningPackagePath: resolve(here, ".."),
+          runPnpm: (args, capture = false) => {
+            const invocation = pnpmOwnerInvocation(owner, args);
+            if (!invocation) return { status: 1 };
+            return spawnSync(invocation.file, invocation.args, {
+              ...invocation.options,
+              stdio: capture ? "pipe" : "inherit",
+              encoding: "utf8",
+              timeout: 180000,
+              windowsHide: true,
+              env: unprivilegedOwnershipMutationEnvironment(invocation.env ?? process.env),
+            });
+          },
+          log: line => console.log(line),
+        });
+        if (update.ok) {
+          // pnpm switches the active global group and updates its shim. Continue recovery
+          // through that fresh package tree, not the old group whose launcher is still
+          // executing this update.
+          postUpdateLauncher = join(update.path, "bin", "ocx.mjs");
+          res = { status: 0 };
+        } else {
+          console.error(`opencodex: ${update.error}${update.rolledBack ? "." : " Manual recovery may be required."}`);
+          postUpdateLauncherUsable = Boolean(update.activePath);
+          if (update.activePath) postUpdateLauncher = join(update.activePath, "bin", "ocx.mjs");
+          res = { status: 1 };
+        }
       }
+    } catch (error) {
+      // An unexpected throw means we cannot prove the live tree is untouched, so the
+      // legacy in-place install (which deletes live first) is exactly the wrong rescue —
+      // it recreates the #1849 destruction path. Report and stop; the boot probe and the
+      // recovery marker cover the swap-window states.
+      const manual = manager === "pnpm"
+        ? `pnpm add -g --allow-build=bun ${PKG}@${tag}`
+        : `npm install -g --allow-scripts=bun ${PKG}@${tag}`;
+      // An unexpected exception leaves the active package path unproven for either manager.
+      // Do not run service/tray/proxy recovery through a possibly half-swapped tree.
+      postUpdateLauncherUsable = false;
+      console.error(`opencodex: ${manager} update failed unexpectedly (${error?.message ?? error}). ` +
+        `The live install was not knowingly modified; run 'ocx update' again or reinstall with ${manual}.`);
+      res = { status: 1 };
     }
-  } catch (error) {
-    // An unexpected throw means we cannot prove the live tree is untouched, so the
-    // legacy in-place install (which deletes live first) is exactly the wrong rescue —
-    // it recreates the #1849 destruction path. Report and stop; the boot probe and the
-    // recovery marker cover the swap-window states.
-    const manual = manager === "pnpm"
-      ? `pnpm add -g --allow-build=bun ${PKG}@${tag}`
-      : `npm install -g --allow-scripts=bun ${PKG}@${tag}`;
-    // An unexpected exception leaves the active package path unproven for either manager.
-    // Do not run service/tray/proxy recovery through a possibly half-swapped tree.
-    postUpdateLauncherUsable = false;
-    console.error(`opencodex: ${manager} update failed unexpectedly (${error?.message ?? error}). ` +
-      `The live install was not knowingly modified; run 'ocx update' again or reinstall with ${manual}.`);
-    res = { status: 1 };
+    if (res.status !== 0) recoverStoppedRuntimeAfterFailure("update failed");
+  } finally {
+    // Expected aborts release before process.exit(); this covers every thrown or newly-added
+    // path and keeps token restoration coupled to the lease itself.
+    releaseUpdateLease();
   }
+  const postInstallPlan = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: serviceWasInstalled });
   if (res.status === 0) {
     console.log(`\nUpdated${latest ? ` to v${latest}` : ""}.`);
     repairCodexShimIfNeeded(postUpdateLauncher);
@@ -637,16 +811,15 @@ function runPackageManagerSelfUpdate(manager) {
     }
     // The stop above unloaded any managed service; refresh via the freshly-installed
     // launcher so the new files write the baked paths and the service restarts.
-    if (serviceWasInstalled) {
+    if (postInstallPlan.mayRestoreService) {
       console.log("Refreshing the background service with the updated files...");
       refreshBackgroundServiceOrStartDirect();
-    } else {
+    } else if (postInstallPlan.mayStopRuntime) {
       console.log(`Restart the proxy:  ${launcherStartHint(postUpdateLauncher, bakePort)}`);
     }
     process.exit(0);
   }
   if (trayBeforeUpdate.restoreOnFailure && postUpdateLauncherUsable) runTrayLifecycle(postUpdateLauncher, "start");
-  recoverStoppedRuntimeAfterFailure();
   const manual = manager === "pnpm"
     ? `pnpm add -g --allow-build=bun ${PKG}@${tag}`
     : `npm install -g --allow-scripts=bun ${PKG}@${tag}`;
diff --git a/desktop/README.md b/desktop/README.md
new file mode 100644
index 00000000000..9e7fcc0eda5
--- /dev/null
+++ b/desktop/README.md
@@ -0,0 +1,90 @@
+# OpenCodex desktop shell
+
+The Tauri shell attaches to the local OpenCodex proxy and keeps the dashboard
+in the proxy's loopback origin. During development:
+
+```sh
+bun run prepare-sidecar
+bun run prepare-widget
+bunx tauri dev
+```
+
+The sidecar is generated from the repository's standalone binary build and is
+not checked into git.
+
+The CI desktop-shell job performs Rust-only checks. It creates an empty
+platform-named sidecar stub and a placeholder dashboard resource directory
+solely for Tauri's external-binary and resource validation; it does not build
+or run the standalone binary.
+
+For a macOS release build, prepare the sidecar and WidgetKit extension before invoking
+Tauri:
+
+```sh
+bun run prepare-sidecar
+bun run prepare-widget
+bunx tauri build
+```
+
+## Building locally without signing keys
+
+`bunx tauri build` always produces the updater archive and then refuses to finish without
+`TAURI_SIGNING_PRIVATE_KEY`, so a local build ends on `A public key has been found, but no private
+key` **after** writing `OpenCodex.app` and the dmg. That exit code is right for a release and
+misleading on a workstation.
+
+```sh
+bun run build:local
+```
+
+This asks for the host platform's installable bundles only (app and dmg on macOS, msi and nsis
+setup exe on Windows, AppImage and deb on Linux), so no updater archive is produced and none is
+expected to be signed. Each format is attempted in its own invocation: a format this machine
+cannot bundle (for example an AppImage when a linuxdeploy dependency is missing) fails on its own
+line without destroying the formats that do build, the failing format is retried once with
+`--verbose` so the bundler's own diagnostics are visible, and the summary prints every format's
+outcome beside the artifacts that were produced. The exit code is non-zero if any format failed.
+The release path below is unchanged: a published
+updater artifact still has to be signed.
+
+## Release packaging and updates
+
+The release workflow builds a macOS DMG, Windows MSI, Linux AppImage, and Debian package.
+It collects the platform artifacts beside checksum files and creates `latest.json` for the
+Tauri updater. The public updater key and endpoint live in `src-tauri/tauri.conf.json`;
+the private key must never be committed. The manifest is generated only when the updater
+key secret is configured and then requires all four platforms to be signed.
+
+To package locally:
+
+```sh
+bun run build:gui
+cd desktop
+bun install --frozen-lockfile
+bun run prepare-sidecar
+bun run prepare-widget
+bunx tauri build --ci --bundles app,dmg
+```
+
+Release signing is supplied through environment variables:
+
+```sh
+export TAURI_SIGNING_PRIVATE_KEY="..."
+export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="..."
+export APPLE_CERTIFICATE="..."
+export APPLE_CERTIFICATE_PASSWORD="..."
+export APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"
+export APPLE_ID="..."
+export APPLE_PASSWORD="..."
+export APPLE_TEAM_ID="..."
+export MACOS_SIGN_IDENTITY="$APPLE_SIGNING_IDENTITY"
+```
+
+Generate a Tauri updater key pair with:
+
+```sh
+bunx tauri signer generate
+```
+
+Keep the private key in a local secret store. Windows SmartScreen signing is not wired
+yet; the release workflow documents that installers may show an unsigned-publisher warning.
diff --git a/desktop/package.json b/desktop/package.json
new file mode 100644
index 00000000000..5966c9235f2
--- /dev/null
+++ b/desktop/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@opencodex/desktop",
+  "private": true,
+  "scripts": {
+    "dev": "tauri dev",
+    "build": "tauri build",
+    "build:local": "bun scripts/build-local.ts",
+    "icons": "bun scripts/generate-icons.ts",
+    "icons:check": "bun scripts/generate-icons.ts --check",
+    "prepare-sidecar": "bun scripts/prepare-sidecar.ts",
+    "prepare-widget": "bash scripts/build-widget.sh"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "2.11.1"
+  }
+}
diff --git a/desktop/scripts/build-local.ts b/desktop/scripts/build-local.ts
new file mode 100644
index 00000000000..634c92ffbce
--- /dev/null
+++ b/desktop/scripts/build-local.ts
@@ -0,0 +1,161 @@
+#!/usr/bin/env bun
+/**
+ * Unsigned local bundle build.
+ *
+ * `tauri build` always produces the updater archive, because `bundle.createUpdaterArtifacts` is
+ * true and `plugins.updater.pubkey` is set. Without `TAURI_SIGNING_PRIVATE_KEY` it then refuses to
+ * finish:
+ *
+ *     Finished 2 bundles at: .../OpenCodex.app, .../OpenCodex_2.61.0_aarch64.dmg
+ *     A public key has been found, but no private key.
+ *     Error failed to build app
+ *
+ * Both bundles exist at that point. The non-zero exit is correct for a release — an unsigned
+ * updater artifact reaching users is worse than a failed build — but for someone building on their
+ * own machine it reports a failure for a signing step they were never meant to perform, and a
+ * wrapper script cannot tell it apart from a real failure.
+ *
+ * So this does not relax the check. It turns the updater artifact off for this one invocation, so
+ * there is nothing to sign and nothing is skipped unsigned. Selecting bundle targets is not enough:
+ * `createUpdaterArtifacts` is a config flag, so `--bundles app,dmg` still produces
+ * `OpenCodex.app.tar.gz (updater)` and still fails. The override has to reach the config itself.
+ *
+ * Two more local-only behaviours, learned from a real GNOME desktop (devlog plan 260921,
+ * 120_install_verification.md):
+ *
+ * - Formats build in SEPARATE invocations. A single `--bundles appimage,deb` call dies on the
+ *   first failing format, so a host that cannot bundle an AppImage (a missing linuxdeploy
+ *   dependency) also lost the deb it could have built. Each format is attempted, and the
+ *   summary at the end names every format's outcome; the exit code is non-zero if any of
+ *   them failed, and the artifacts that DID build are printed either way.
+ * - A failing format is retried once with `--verbose`. At the bundler's default log level
+ *   the error is a bare "failed to run linuxdeploy" with the tool's own diagnostics
+ *   discarded; the verbose pass is the branch where that stderr actually reaches the
+ *   terminal, so the failure says WHY instead of naming a tool nobody invoked.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const desktopDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** Bundle targets per host platform that carry no updater archive. */
+const LOCAL_BUNDLES: Record<string, readonly string[]> = {
+  darwin: ["app", "dmg"],
+  win32: ["msi", "nsis"],
+  linux: ["appimage", "deb"],
+};
+
+/**
+ * Config merged over `tauri.conf.json` for this invocation only.
+ *
+ * Turning the artifact off is what makes the signing key unnecessary, rather than leaving it
+ * required and unmet. The committed config keeps `createUpdaterArtifacts: true`, so the release
+ * build is untouched.
+ */
+const LOCAL_CONFIG = JSON.stringify({ bundle: { createUpdaterArtifacts: false } });
+
+export interface SpawnResult {
+  status: number | null;
+  error?: Error;
+}
+
+export interface ArtifactEntry {
+  path: string;
+  mtimeMs: number;
+}
+
+export interface BuildLocalDeps {
+  spawn(args: string[]): SpawnResult;
+  log(line: string): void;
+  error(line: string): void;
+  listArtifacts(): ArtifactEntry[];
+  argv: string[];
+  platform: string;
+}
+
+export interface FormatAttempt {
+  format: string;
+  status: number;
+}
+
+export function summarizeAttempts(attempts: FormatAttempt[]): { exitCode: number; lines: string[] } {
+  const lines = attempts.map(
+    attempt => `[build:local] ${attempt.format}: ${attempt.status === 0 ? "ok" : `FAILED (exit ${attempt.status})`}`,
+  );
+  return { exitCode: attempts.every(attempt => attempt.status === 0) ? 0 : 1, lines };
+}
+
+export function runBuildLocal(deps: BuildLocalDeps): number {
+  const bundles = LOCAL_BUNDLES[deps.platform];
+  if (!bundles) {
+    deps.error(`[build:local] unsupported host platform: ${deps.platform}`);
+    return 1;
+  }
+  // Snapshot before building: a bundle directory that already holds last week's AppImage
+  // must not be reported as this run's output when this run's AppImage attempt fails.
+  const baseline = new Map(deps.listArtifacts().map(entry => [entry.path, entry.mtimeMs]));
+  const attempts: FormatAttempt[] = [];
+  for (const format of bundles) {
+    // One invocation per format: a format this host cannot build must not destroy the
+    // artifacts of formats it can.
+    const args = ["tauri", "build", "--ci", "--bundles", format, "--config", LOCAL_CONFIG, ...deps.argv];
+    const first = deps.spawn(args);
+    let status = first.status ?? 1;
+    if (first.error) {
+      deps.error(`[build:local] could not start tauri: ${first.error.message}`);
+      status = 1;
+    } else if (status !== 0) {
+      // The bundler reports a bare "failed to run <tool>" at its default log level; the
+      // verbose pass is where the tool's own stderr reaches the terminal. The retry is
+      // diagnostics only — the recorded status stands either way.
+      deps.error(`[build:local] ${format} failed; rerunning with --verbose for the bundler's diagnostics`);
+      const retry = deps.spawn(["tauri", "--verbose", "build", "--ci", "--bundles", format, "--config", LOCAL_CONFIG, ...deps.argv]);
+      if (retry.error) deps.error(`[build:local] could not start tauri: ${retry.error.message}`);
+    }
+    attempts.push({ format, status });
+  }
+  // Name what THIS run produced even when something failed: an error line at the end is
+  // the least visible place for artifacts that already built.
+  const produced = deps.listArtifacts().filter(
+    entry => !baseline.has(entry.path) || baseline.get(entry.path) !== entry.mtimeMs,
+  );
+  for (const entry of produced) deps.log(`[build:local] ${entry.path}`);
+  const summary = summarizeAttempts(attempts);
+  for (const line of summary.lines) deps.log(line);
+  if (summary.exitCode === 0) {
+    deps.log("[build:local] updater artifacts skipped; release signing is unchanged.");
+  }
+  return summary.exitCode;
+}
+
+function main(): void {
+  const status = runBuildLocal({
+    spawn: args => spawnSync("bunx", args, { cwd: desktopDir, stdio: "inherit" }),
+    log: line => console.log(line),
+    error: line => console.error(line),
+    listArtifacts: () => {
+      const bundleRoot = join(desktopDir, "src-tauri", "target", "release", "bundle");
+      const artifacts: ArtifactEntry[] = [];
+      for (const dir of ["macos", "dmg", "msi", "nsis", "appimage", "deb"]) {
+        const directory = join(bundleRoot, dir);
+        if (!existsSync(directory)) continue;
+        for (const name of readdirSync(directory)) {
+          if (/\.(app|dmg|msi|exe|AppImage|deb)$/i.test(name)) {
+            const full = join(directory, name);
+            artifacts.push({ path: full, mtimeMs: statSync(full).mtimeMs });
+          }
+        }
+      }
+      return artifacts;
+    },
+    argv: process.argv.slice(2),
+    platform: process.platform,
+  });
+  process.exit(status);
+}
+
+if (import.meta.main) {
+  main();
+}
diff --git a/desktop/scripts/build-widget.sh b/desktop/scripts/build-widget.sh
new file mode 100755
index 00000000000..38e0eb9d713
--- /dev/null
+++ b/desktop/scripts/build-widget.sh
@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "prepare-widget requires macOS." >&2
+  exit 1
+fi
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+desktop_dir="$(cd "$script_dir/.." && pwd)"
+repo_root="$(cd "$desktop_dir/.." && pwd)"
+package_dir="$repo_root/app"
+output_dir="$desktop_dir/src-tauri/widget/OpenCodexWidget.appex"
+configuration="${CONFIGURATION:-release}"
+universal="${UNIVERSAL:-1}"
+
+if [[ "$universal" != "0" && "$universal" != "1" ]]; then
+  echo "UNIVERSAL must be 0 or 1." >&2
+  exit 1
+fi
+
+# A widget extension is loaded by the system, not by the app, so it is validated on its own
+# terms: notarization rejects any Mach-O inside it that lacks the hardened runtime, and macOS
+# refuses to register an extension whose signature does not chain to the containing app's team.
+# An ad-hoc signature satisfies neither, and the ad-hoc branch is the default whenever no
+# identity reaches this script. Resolve that before the build so a misconfigured release fails
+# in a second rather than after a universal Swift build.
+if [[ -n "${MACOS_SIGN_IDENTITY:-}" ]]; then
+  sign_identity="$MACOS_SIGN_IDENTITY"
+  timestamp_arg=(--timestamp)
+elif [[ "${WIDGET_SIGN_REQUIRED:-0}" == "1" ]]; then
+  # A release that signs everything else and ad-hoc signs the widget produces an app that
+  # ships either way and simply has no widget. Refuse instead.
+  echo "WIDGET_SIGN_REQUIRED=1 but MACOS_SIGN_IDENTITY is empty; refusing to ad-hoc sign a release widget." >&2
+  exit 1
+else
+  sign_identity="-"
+  timestamp_arg=(--timestamp=none)
+fi
+
+build_root="$(mktemp -d "${TMPDIR:-/tmp}/opencodex-widget.XXXXXX")"
+cleanup() { rm -rf "$build_root"; }
+trap cleanup EXIT
+
+build_widget() {
+  local arch="$1"
+  local scratch="$build_root/$arch"
+  swift build \
+    --package-path "$package_dir" \
+    --scratch-path "$scratch" \
+    -c "$configuration" \
+    --arch "$arch" \
+    --product OpenCodexWidget
+  swift build \
+    --package-path "$package_dir" \
+    --scratch-path "$scratch" \
+    -c "$configuration" \
+    --arch "$arch" \
+    --show-bin-path
+}
+
+if [[ "$universal" == "1" ]]; then
+  arm64_bin="$(build_widget arm64 | tail -n 1)/OpenCodexWidget"
+  x86_64_bin="$(build_widget x86_64 | tail -n 1)/OpenCodexWidget"
+  executable="$build_root/OpenCodexWidget"
+  lipo -create "$arm64_bin" "$x86_64_bin" -output "$executable"
+else
+  executable="$(build_widget "$(uname -m)" | tail -n 1)/OpenCodexWidget"
+fi
+
+[[ -x "$executable" ]] || { echo "Swift build did not produce $executable" >&2; exit 1; }
+
+rm -rf "$output_dir"
+mkdir -p "$output_dir/Contents/MacOS"
+cp "$executable" "$output_dir/Contents/MacOS/OpenCodexWidget"
+cp "$package_dir/Widget-Info.plist" "$output_dir/Contents/Info.plist"
+
+version="$(sed -n 's/^[[:space:]]*"version": "\([^"]*\)",/\1/p' "$desktop_dir/src-tauri/tauri.conf.json" | head -n 1)"
+version_core="${version%%-*}"
+[[ "$version_core" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
+  echo "Invalid Tauri version: $version" >&2
+  exit 1
+}
+plutil -replace CFBundleShortVersionString -string "$version_core" "$output_dir/Contents/Info.plist"
+plutil -replace CFBundleVersion -string "$version_core" "$output_dir/Contents/Info.plist"
+
+# Sign inside out over every Mach-O the bundle actually contains, chosen by magic bytes rather
+# than by name. Today that set is the single widget executable, but a name or extension filter
+# is the thing that fails silently when it stops being true: a helper tool or an embedded
+# dylib carries no suffix to match, stays unsigned, and the whole submission comes back
+# "The binary is not signed with a valid Developer ID certificate" with the bundle itself
+# looking perfectly signed.
+mach_o_members=()
+while IFS= read -r candidate; do
+  [[ "$(file -b "$candidate")" == *"Mach-O"* ]] || continue
+  mach_o_members+=("$candidate")
+done < <(find "$output_dir" -type f -not -path "*/_CodeSignature/*")
+
+[[ ${#mach_o_members[@]} -gt 0 ]] || { echo "No Mach-O binary found in $output_dir" >&2; exit 1; }
+
+for member in "${mach_o_members[@]}"; do
+  codesign --force --sign "$sign_identity" --options runtime "${timestamp_arg[@]}" "$member"
+done
+
+# The bundle seal goes on last and is the only signature that carries the entitlements.
+codesign --force --sign "$sign_identity" --entitlements "$package_dir/Widget.entitlements" \
+  --options runtime "${timestamp_arg[@]}" "$output_dir"
+
+codesign --verify --deep --strict "$output_dir"
+# `runtime` is 0x10000 in the code directory flags. Asserting it here is what turns a silently
+# unnotarizable widget into a failed build. The output is captured rather than piped into a
+# matcher: `set -o pipefail` plus a matcher that exits on its first hit makes codesign die of
+# SIGPIPE, and the check then fails on exactly the signatures it was meant to accept.
+signature_display="$(codesign --display --verbose=4 "$output_dir" 2>&1)"
+case "$signature_display" in
+  *"flags="*"runtime"*) ;;
+  *)
+    echo "Widget signature is missing the hardened runtime:" >&2
+    echo "$signature_display" >&2
+    exit 1
+    ;;
+esac
+
+echo "$output_dir"
diff --git a/desktop/scripts/collect-release-assets.ts b/desktop/scripts/collect-release-assets.ts
new file mode 100644
index 00000000000..2c97de39d44
--- /dev/null
+++ b/desktop/scripts/collect-release-assets.ts
@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+
+type BundleKind = "dmg" | "app.tar.gz" | "msi" | "appimage" | "deb";
+
+export interface BundleSpec {
+  kind: BundleKind;
+  dir: string;
+  name: string;
+}
+
+export const bundlesByTarget: Record<string, BundleSpec[]> = {
+  "universal-apple-darwin": [
+    { kind: "dmg", dir: "dmg", name: "macos.dmg" },
+    { kind: "app.tar.gz", dir: "macos", name: "macos.app.tar.gz" },
+  ],
+  "aarch64-apple-darwin": [
+    { kind: "dmg", dir: "dmg", name: "macos.dmg" },
+    { kind: "app.tar.gz", dir: "macos", name: "macos.app.tar.gz" },
+  ],
+  "x86_64-apple-darwin": [
+    { kind: "dmg", dir: "dmg", name: "macos.dmg" },
+    { kind: "app.tar.gz", dir: "macos", name: "macos.app.tar.gz" },
+  ],
+  "x86_64-pc-windows-msvc": [{ kind: "msi", dir: "msi", name: "windows-x64.msi" }],
+  "x86_64-unknown-linux-gnu": [
+    { kind: "appimage", dir: "appimage", name: "linux-x86_64.AppImage" },
+    { kind: "deb", dir: "deb", name: "linux-amd64.deb" },
+  ],
+};
+
+export interface CollectReleaseAssetsOptions {
+  version: string;
+  target: string;
+  out: string;
+  repoRoot?: string;
+}
+
+function findBundle(directory: string, kind: BundleKind): string {
+  if (!existsSync(directory)) {
+    throw new Error(`Missing ${kind} bundle directory: ${directory}`);
+  }
+  const artifact = readdirSync(directory)
+    .filter(name => name.toLowerCase().endsWith(`.${kind.toLowerCase()}`));
+  if (artifact.length === 0) throw new Error(`No ${kind} bundle found in ${directory}`);
+  if (artifact.length > 1) {
+    throw new Error(`Multiple ${kind} bundles found in ${directory}: ${artifact.join(", ")}`);
+  }
+  return join(directory, artifact[0]);
+}
+
+export function collectReleaseAssets(options: CollectReleaseAssetsOptions): string[] {
+  const repoRoot = resolve(options.repoRoot ?? join(import.meta.dir, "../.."));
+  const bundles = bundlesByTarget[options.target];
+  if (!bundles) throw new Error(`Unsupported desktop target: ${options.target}`);
+
+  const output = resolve(options.out);
+  mkdirSync(output, { recursive: true });
+  const written: string[] = [];
+  for (const bundle of bundles) {
+    const source = findBundle(
+      join(repoRoot, "desktop", "src-tauri", "target", options.target, "release", "bundle", bundle.dir),
+      bundle.kind,
+    );
+    const destinationName = `OpenCodex-${options.version}-${bundle.name}`;
+    const destination = join(output, destinationName);
+    copyFileSync(source, destination);
+    written.push(destination);
+
+    const signature = `${source}.sig`;
+    if (existsSync(signature)) {
+      copyFileSync(signature, `${destination}.sig`);
+      written.push(`${destination}.sig`);
+    }
+
+    const digest = createHash("sha256").update(readFileSync(destination)).digest("hex");
+    const checksum = `${destination}.sha256`;
+    writeFileSync(checksum, `${digest}  ${destinationName}\n`);
+    written.push(checksum);
+  }
+  return written;
+}
+
+function argument(name: string): string | undefined {
+  const index = Bun.argv.indexOf(name);
+  return index < 0 ? undefined : Bun.argv[index + 1];
+}
+
+if (import.meta.main) {
+  const version = argument("--version");
+  const target = argument("--target");
+  const out = argument("--out");
+  if (!version || !target || !out) {
+    throw new Error("Usage: collect-release-assets.ts --version <version> --target <target> --out <dir>");
+  }
+  for (const path of collectReleaseAssets({ version, target, out })) console.log(`Wrote ${path}`);
+}
diff --git a/desktop/scripts/generate-icons.ts b/desktop/scripts/generate-icons.ts
new file mode 100644
index 00000000000..3acfdc8bb92
--- /dev/null
+++ b/desktop/scripts/generate-icons.ts
@@ -0,0 +1,178 @@
+#!/usr/bin/env bun
+/**
+ * Render every app icon from `src-tauri/icons/icon.svg`.
+ *
+ * The icon set used to be eighteen independent raster files with no vector source, so each size
+ * was a separate artifact that could drift from the others and nothing could detect it. This makes
+ * the sizes derived: one curve, rendered at each dimension the platforms ask for.
+ *
+ * The SVG reproduces the raster it replaced to within antialiasing (430 of 262144 pixels at 512),
+ * measured rather than assumed — the geometry in that file was read off the original bitmap.
+ *
+ * `--check` regenerates into a temporary directory and compares, so CI can fail on a hand-edited
+ * PNG instead of letting the source and the shipped icons disagree quietly.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildIco, render as renderSvg } from "../../scripts/lib/icon-render";
+
+const desktopDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const iconsDir = join(desktopDir, "src-tauri", "icons");
+const source = join(iconsDir, "icon.svg");
+
+/** Square PNGs Tauri and the Windows store manifests reference, by output filename. */
+const PNG_SIZES: Record<string, number> = {
+  "32x32.png": 32,
+  "64x64.png": 64,
+  "128x128.png": 128,
+  "128x128@2x.png": 256,
+  "icon.png": 512,
+  "Square30x30Logo.png": 30,
+  "Square44x44Logo.png": 44,
+  "Square71x71Logo.png": 71,
+  "Square89x89Logo.png": 89,
+  "Square107x107Logo.png": 107,
+  "Square142x142Logo.png": 142,
+  "Square150x150Logo.png": 150,
+  "Square284x284Logo.png": 284,
+  "Square310x310Logo.png": 310,
+  "StoreLogo.png": 50,
+};
+
+/** Sizes an .icns carries, as iconutil names them. */
+const ICNS_ENTRIES: Array<{ name: string; size: number }> = [
+  { name: "icon_16x16.png", size: 16 },
+  { name: "icon_16x16@2x.png", size: 32 },
+  { name: "icon_32x32.png", size: 32 },
+  { name: "icon_32x32@2x.png", size: 64 },
+  { name: "icon_128x128.png", size: 128 },
+  { name: "icon_128x128@2x.png", size: 256 },
+  { name: "icon_256x256.png", size: 256 },
+  { name: "icon_256x256@2x.png", size: 512 },
+  { name: "icon_512x512.png", size: 512 },
+  { name: "icon_512x512@2x.png", size: 1024 },
+];
+
+/** Sizes packed into the .ico, which stores each one as an embedded PNG. */
+const ICO_SIZES = [16, 32, 48, 64, 128, 256];
+
+/**
+ * The menu bar image, which is the same mark with no backdrop and the prompt cut through.
+ *
+ * It needs its own source because a status item is a template image: macOS reads the alpha as
+ * coverage and paints it with the menu bar tint, so the backdrop has to be gone rather than
+ * recoloured. 44px is 22pt at @2x, which is the menu bar working height and the size this asset
+ * already shipped at.
+ */
+const TRAY_OUTPUT = "tray/icon.png";
+const TRAY_SIZE = 44;
+const traySource = join(iconsDir, "tray", "icon.svg");
+
+/** Render at `size` from `from`, defaulting to the app icon vector. */
+function render(size: number, out: string, from: string = source): void {
+  renderSvg(size, out, from);
+}
+
+/**
+ * Render the whole set into `target`, and report which artifacts were actually produced.
+ *
+ * The return value matters: `iconutil` is macOS-only, so on another platform no `.icns` exists to
+ * compare against. Reporting that is the difference between "the icns matches" and "nothing looked
+ * at the icns", and the check must not spell the second as the first.
+ */
+function generateInto(target: string): { produced: string[]; icnsSkipped: boolean } {
+  mkdirSync(target, { recursive: true });
+  const produced: string[] = [];
+  for (const [name, size] of Object.entries(PNG_SIZES)) {
+    render(size, join(target, name));
+    produced.push(name);
+  }
+
+  const iconset = join(target, "icon.iconset");
+  mkdirSync(iconset, { recursive: true });
+  for (const entry of ICNS_ENTRIES) render(entry.size, join(iconset, entry.name));
+  const icns = spawnSync("iconutil", ["-c", "icns", iconset, "-o", join(target, "icon.icns")]);
+  const icnsSkipped = icns.status !== 0;
+  if (!icnsSkipped) produced.push("icon.icns");
+  rmSync(iconset, { recursive: true, force: true });
+
+  const icoParts: Array<{ size: number; bytes: Buffer }> = [];
+  for (const size of ICO_SIZES) {
+    const scratch = join(target, `.ico-${size}.png`);
+    render(size, scratch);
+    icoParts.push({ size, bytes: readFileSync(scratch) });
+    rmSync(scratch, { force: true });
+  }
+  writeFileSync(join(target, "icon.ico"), buildIco(icoParts));
+  produced.push("icon.ico");
+
+  mkdirSync(join(target, "tray"), { recursive: true });
+  render(TRAY_SIZE, join(target, TRAY_OUTPUT), traySource);
+  produced.push(TRAY_OUTPUT);
+
+  return { produced, icnsSkipped };
+}
+
+function main(): number {
+  if (!existsSync(source)) {
+    console.error(`[icons] missing source: ${source}`);
+    return 1;
+  }
+  if (!existsSync(traySource)) {
+    console.error(`[icons] missing source: ${traySource}`);
+    return 1;
+  }
+  const check = process.argv.includes("--check");
+  if (!check) {
+    // Render into scratch first so a failure half way through cannot leave the committed set
+    // partly replaced, then move the finished artifacts over in one pass.
+    const scratch = mkdtempSync(join(tmpdir(), "ocx-icons-"));
+    try {
+      const { produced, icnsSkipped } = generateInto(scratch);
+      if (icnsSkipped) {
+        // Abort before touching the committed set. Copying the PNGs and the .ico and then
+        // reporting the missing .icns would leave the icons half regenerated: the rasters new,
+        // the .icns whatever it was, and no way to tell from the tree which is which.
+        console.error("[icons] iconutil is unavailable here, so the .icns cannot be regenerated.");
+        console.error("[icons] nothing was written; run this on a machine with iconutil.");
+        return 1;
+      }
+      for (const name of produced) writeFileSync(join(iconsDir, name), readFileSync(join(scratch, name)));
+      console.log(`[icons] regenerated ${produced.length} artifacts from ${source}`);
+      return 0;
+    } finally {
+      rmSync(scratch, { recursive: true, force: true });
+    }
+  }
+
+  const scratch = mkdtempSync(join(tmpdir(), "ocx-icons-"));
+  try {
+    const { produced, icnsSkipped } = generateInto(scratch);
+    const drifted: string[] = [];
+    for (const name of produced) {
+      const fresh = join(scratch, name);
+      const committed = join(iconsDir, name);
+      if (!existsSync(committed) || !readFileSync(fresh).equals(readFileSync(committed))) {
+        drifted.push(name);
+      }
+    }
+    if (drifted.length > 0) {
+      console.error(`[icons] these do not match their source: ${drifted.join(", ")}`);
+      console.error("[icons] regenerate with: bun run icons");
+      return 1;
+    }
+    console.log(`[icons] ${produced.length} generated icons match the source`);
+    if (icnsSkipped) {
+      console.error("[icons] iconutil is unavailable here, so icon.icns was NOT compared.");
+      return 1;
+    }
+    return 0;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+process.exit(main());
diff --git a/desktop/scripts/installed-gate-platforms.ts b/desktop/scripts/installed-gate-platforms.ts
new file mode 100644
index 00000000000..0fd10bf95d1
--- /dev/null
+++ b/desktop/scripts/installed-gate-platforms.ts
@@ -0,0 +1,407 @@
+/**
+ * Platform adapters for the installed-artifact gate (D9, part two).
+ *
+ * Adapters turn platform actions into command specs the gate engine runs and records;
+ * they never hardcode machine detail. Artifact paths, homes and ports arrive as
+ * arguments. GUI automation the OS cannot reach (the in-page consent dialog, tray
+ * clicks on some desktops) is supplied by the operator as pre-installed hook files,
+ * never as dispatch-provided command text — a persistent self-hosted runner must not
+ * become an arbitrary-execution surface.
+ *
+ * The external commands each adapter needs are declared in dependencies() so a runner
+ * can be audited for readiness before an artifact is ever installed on it.
+ */
+
+export type GatePlatform = "macos" | "windows" | "linux";
+export type GateFormat = "dmg" | "msi" | "deb" | "appimage";
+
+import { join } from "node:path";
+
+export interface CommandSpec {
+  file: string;
+  args: string[];
+}
+
+export interface ProcessEvidence {
+  ok: boolean;
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export interface InstallResult {
+  appBinary: string;
+  packageName?: string;
+  /** Path scope that identifies THIS install's processes (install dir or binary path). */
+  scope: string;
+  evidence: Record<string, unknown>;
+}
+
+export interface PlatformAdapter {
+  platform: GatePlatform;
+  /** Every external command this adapter shells out to; the engine preflights them. */
+  dependencies(): string[];
+  /** The staged npm ocx launcher inside an npm --prefix install. */
+  npmLauncher(prefix: string): string;
+  /** Registers and starts the staged npm runtime as a managed service. */
+  serviceInstall(launcher: string): CommandSpec;
+  serviceUninstall(launcher: string): CommandSpec;
+  /**
+   * Three-state registration answer: an existing registration is "present", a clean
+   * not-found is "absent", and any probe failure that cannot be told apart is
+   * "unknown" — the engine refuses to mutate on unknown.
+   */
+  registrationState(): Promise<"present" | "absent" | "unknown">;
+  /**
+   * On-disk registration files, relative to the runner account's home. A registration
+   * that is unloaded, disabled or not yet loaded leaves these behind, and the manager
+   * probes above miss exactly those states.
+   */
+  registrationFiles(): string[];
+  /**
+   * Read-only probe for a dormant installation (MSI registry entry, dpkg record) the
+   * gate must refuse to overwrite. Null where installs land inside the work dir.
+   */
+  existingInstallation(format: GateFormat, packageName?: string): CommandSpec | null;
+  /** Installs the real artifact; returns the app executable path. */
+  installArtifact(artifact: string, workDir: string, format: GateFormat): Promise<InstallResult>;
+  /** Drives the installed app's window-close gesture. */
+  closeGesture(): CommandSpec;
+  /** Drives the installed app's OS-quit gesture (Cmd+Q, Alt+F4). */
+  quitGesture(): CommandSpec;
+  /** Left-clicks the tray icon (the shell shows the dashboard window), or null. */
+  trayClick(): CommandSpec | null;
+  /** Opens the tray menu and chooses Quit (the drain-then-exit path), or null. */
+  trayQuit(): CommandSpec | null;
+  /** Chooses Check for Updates in the tray menu, or null. */
+  trayCheck(): CommandSpec | null;
+  /** Chooses the enabled Install update item in the tray menu, or null. */
+  trayInstall(): CommandSpec | null;
+  /** Exits zero only when the app currently has a visible window. */
+  windowVisible(): CommandSpec;
+  /** Installed package version probe, where the platform has one (deb), or null. */
+  installedVersion(format: GateFormat, packageName?: string): CommandSpec | null;
+  /** Dismisses exactly the authorization prompts the gate sighted, by pid, or null. */
+  cancelElevation(pids: number[]): CommandSpec | null;
+  /**
+   * Lists pids of any elevation prompt surface — pkexec, and the zenity/kdialog
+   * password dialogs the updater plugin falls back to after a pkexec cancel.
+   * Null where the platform has no package-manager elevation (macOS, Windows).
+   */
+  elevationProbe(): CommandSpec | null;
+  /** Lists pids whose executable lives under the given install scope. */
+  appProcessProbe(scope: string): CommandSpec;
+  /** Lists pids of ANY installed copy of the app — the preflight's broad probe. */
+  appNameProbe(): CommandSpec;
+  /** Lists direct child pids of the given process. */
+  childPids(pid: number): CommandSpec;
+  /** Removes what installArtifact placed on the machine. */
+  uninstall(artifact: string, workDir: string, format: GateFormat, packageName?: string): CommandSpec[];
+}
+
+export interface AdapterRuntime {
+  run(spec: CommandSpec): Promise<ProcessEvidence>;
+  mkdir(path: string): void;
+  fileExists(path: string): boolean;
+  homeDir(): string;
+}
+
+function requireOk(step: string, result: ProcessEvidence): void {
+  if (!result.ok) {
+    throw new Error(`${step} failed (exit ${result.exitCode}): ${result.stderr.trim() || result.stdout.trim()}`);
+  }
+}
+
+/** macOS: dmg install, AppleScript gestures scoped to the OpenCodex process, launchd. */
+export function macosAdapter(runtime: AdapterRuntime): PlatformAdapter {
+  const run = runtime.run.bind(runtime);
+  return {
+    platform: "macos",
+    dependencies: () => ["hdiutil", "osascript", "pgrep", "launchctl", "cp", "rm", "/usr/libexec/PlistBuddy"],
+    npmLauncher: prefix => `${prefix}/node_modules/.bin/ocx`,
+    serviceInstall: launcher => ({ file: launcher, args: ["service", "install"] }),
+    serviceUninstall: launcher => ({ file: launcher, args: ["service", "uninstall"] }),
+    registrationState: async () => {
+      if (runtime.fileExists(join(runtime.homeDir(), "Library/LaunchAgents/com.opencodex.proxy.plist"))) return "present";
+      const probe = await run({ file: "launchctl", args: ["list", "com.opencodex.proxy"] });
+      if (probe.ok) return "present";
+      // "Could not find service" is a clean absence; anything else is unknowable here.
+      return /could not find/i.test(probe.stderr) ? "absent" : "unknown";
+    },
+    registrationFiles: () => ["Library/LaunchAgents/com.opencodex.proxy.plist"],
+    // A dmg install lands inside the gate's work dir; there is no system-level record.
+    existingInstallation: () => null,
+    async installArtifact(artifact, workDir) {
+      const mount = `${workDir}/dmg-mount`;
+      const apps = `${workDir}/Applications`;
+      runtime.mkdir(mount);
+      runtime.mkdir(apps);
+      requireOk("dmg attach", await run({ file: "hdiutil", args: ["attach", artifact, "-mountpoint", mount, "-nobrowse", "-readonly"] }));
+      try {
+        requireOk("app copy", await run({ file: "cp", args: ["-R", `${mount}/OpenCodex.app`, `${apps}/`] }));
+      } finally {
+        await run({ file: "hdiutil", args: ["detach", mount] });
+      }
+      // The executable name is the bundle's own declaration, not a guess: a rename in
+      // packaging lands here without a driver change (#5351 removed this hardcode once).
+      const plist = await run({
+        file: "/usr/libexec/PlistBuddy",
+        args: ["-c", "Print :CFBundleExecutable", `${apps}/OpenCodex.app/Contents/Info.plist`],
+      });
+      requireOk("read CFBundleExecutable", plist);
+      const executable = plist.stdout.trim();
+      return {
+        appBinary: `${apps}/OpenCodex.app/Contents/MacOS/${executable}`,
+        scope: apps,
+        evidence: { mounted: mount, copiedTo: apps, executable },
+      };
+    },
+    closeGesture: () => appleScript(
+      'tell application "OpenCodex" to activate',
+      'tell application "System Events" to keystroke "w" using command down',
+    ),
+    quitGesture: () => appleScript(
+      'tell application "OpenCodex" to activate',
+      'tell application "System Events" to keystroke "q" using command down',
+    ),
+    // Menu bar items belong to their owning process; clicking by global index can hit an
+    // unrelated tray, so every tray action is scoped to the OpenCodex process.
+    trayClick: () => appleScript(
+      'tell application "System Events" to tell process "OpenCodex" to click menu bar item 1 of menu bar 2',
+    ),
+    trayQuit: () => appleScript(
+      'tell application "System Events" to tell process "OpenCodex" to click menu bar item 1 of menu bar 2',
+      'tell application "System Events" to tell process "OpenCodex" to click menu item "Quit" of menu 1 of menu bar item 1 of menu bar 2',
+    ),
+    trayCheck: () => appleScript(
+      'tell application "System Events" to tell process "OpenCodex" to click menu bar item 1 of menu bar 2',
+      'tell application "System Events" to tell process "OpenCodex" to click menu item "Check for Updates…" of menu 1 of menu bar item 1 of menu bar 2',
+    ),
+    trayInstall: () => appleScript(
+      'tell application "System Events" to tell process "OpenCodex" to click menu bar item 1 of menu bar 2',
+      'tell application "System Events" to tell process "OpenCodex" to click (first menu item of menu 1 of menu bar item 1 of menu bar 2 whose name starts with "Install update")',
+    ),
+    windowVisible: () => appleScript('tell application "System Events" to count (windows of process "OpenCodex")'),
+    installedVersion: () => null,
+    cancelElevation: () => null,
+    elevationProbe: () => null,
+    appProcessProbe: scope => ({ file: "pgrep", args: ["-f", scope] }),
+    appNameProbe: () => ({ file: "pgrep", args: ["-f", "OpenCodex.app/Contents/MacOS"] }),
+    childPids: pid => ({ file: "pgrep", args: ["-P", String(pid)] }),
+    uninstall: (_artifact, workDir) => [{ file: "rm", args: ["-rf", `${workDir}/Applications/OpenCodex.app`] }],
+  };
+}
+
+/** Windows: msi install, PowerShell gestures, Task Scheduler registration. */
+export function windowsAdapter(runtime: AdapterRuntime): PlatformAdapter {
+  const run = runtime.run.bind(runtime);
+  return {
+    platform: "windows",
+    dependencies: () => ["msiexec", "powershell", "schtasks", "sc"],
+    npmLauncher: prefix => `${prefix}\\node_modules\\.bin\\ocx.cmd`,
+    serviceInstall: launcher => ({ file: launcher, args: ["service", "install"] }),
+    serviceUninstall: launcher => ({ file: launcher, args: ["service", "uninstall"] }),
+    // Task Scheduler is the default backend; the native backend registers a WinSW
+    // service instead, and both count as an existing registration.
+    registrationState: async () => {
+      const task = await run({ file: "schtasks", args: ["/Query", "/TN", "opencodex-proxy"] });
+      if (task.ok) return "present";
+      const taskAbsent = /cannot find|does not exist/i.test(task.stderr + task.stdout);
+      const service = await run({ file: "sc.exe", args: ["query", "opencodex-proxy-native"] });
+      if (service.ok) return "present";
+      const serviceAbsent = /does not exist/i.test(service.stderr + service.stdout);
+      if (taskAbsent && serviceAbsent) return "absent";
+      return "unknown";
+    },
+    registrationFiles: () => [],
+    // A dormant MSI install shows up in the uninstall registry before any process runs.
+    existingInstallation: format =>
+      format === "msi"
+        ? {
+            file: "powershell",
+            args: [
+              "-NoProfile",
+              "-Command",
+              "$key = Get-ItemProperty 'HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*' | Where-Object { $_.DisplayName -eq 'OpenCodex' }; if ($key) { exit 0 } else { exit 1 }",
+            ],
+          }
+        : null,
+    async installArtifact(artifact, workDir) {
+      requireOk(
+        "msi install",
+        await run({ file: "msiexec", args: ["/i", artifact, "/qn", "/norestart", "/l*v", `${workDir}\\msi-install.log`] }),
+      );
+      const locate = await run({
+        file: "powershell",
+        args: [
+          "-NoProfile",
+          "-Command",
+          "$key = Get-ItemProperty 'HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*' | Where-Object { $_.DisplayName -eq 'OpenCodex' } | Select-Object -First 1; " +
+            "$dir = $key.InstallLocation; " +
+            "@(\"opencodex-desktop.exe\", \"opencodex.exe\") | ForEach-Object { $p = Join-Path $dir $_; if (Test-Path $p) { Write-Output $dir; Write-Output $p; break } }",
+        ],
+      });
+      const locateLines = locate.stdout.trim().split(/\r?\n/);
+      const installDir = locateLines[0] ?? "";
+      const appBinary = locateLines[1] ?? "";
+      if (!appBinary) {
+        // The MSI may already be installed; a discovery failure must not strand it.
+        await run({ file: "msiexec", args: ["/x", artifact, "/qn", "/norestart"] });
+        throw new Error("MSI installed but no OpenCodex executable was found under its InstallLocation");
+      }
+      return { appBinary, scope: installDir, evidence: { installLog: `${workDir}\\msi-install.log`, located: appBinary } };
+    },
+    closeGesture: () => ({
+      file: "powershell",
+      args: [
+        "-NoProfile",
+        "-Command",
+        "$p = Get-Process opencodex-desktop -ErrorAction SilentlyContinue | Where-Object { $_.MainWindowHandle -ne 0 } | Select-Object -First 1; " +
+          "if (-not $p) { exit 1 }; " +
+          "$sig = '[DllImport(\"user32.dll\")] public static extern bool PostMessage(IntPtr h, uint m, IntPtr w, IntPtr l);'; " +
+          "Add-Type -MemberDefinition $sig -Name U32 -Namespace W; [W.U32]::PostMessage($p.MainWindowHandle, 0x0010, [IntPtr]::Zero, [IntPtr]::Zero) | Out-Null",
+      ],
+    }),
+    quitGesture: () => ({
+      file: "powershell",
+      args: [
+        "-NoProfile",
+        "-Command",
+        "$p = Get-Process opencodex-desktop -ErrorAction SilentlyContinue | Where-Object { $_.MainWindowHandle -ne 0 } | Select-Object -First 1; " +
+          "if (-not $p) { exit 1 }; " +
+          "$shell = New-Object -ComObject WScript.Shell; $shell.AppActivate($p.Id) | Out-Null; $shell.SendKeys('%{F4}')",
+      ],
+    }),
+    // The Windows tray lives in the shell's notification area; a pre-installed runner
+    // hook (UIA) drives it. See --hooks-dir in installed-gate.ts.
+    trayClick: () => null,
+    trayQuit: () => null,
+    trayCheck: () => null,
+    trayInstall: () => null,
+    windowVisible: () => ({
+      file: "powershell",
+      args: [
+        "-NoProfile",
+        "-Command",
+        "$p = Get-Process opencodex-desktop -ErrorAction SilentlyContinue | Where-Object { $_.MainWindowHandle -ne 0 }; if ($p) { exit 0 } else { exit 1 }",
+      ],
+    }),
+    installedVersion: () => ({
+      file: "powershell",
+      args: [
+        "-NoProfile",
+        "-Command",
+        "(Get-ItemProperty 'HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*' | Where-Object { $_.DisplayName -eq 'OpenCodex' } | Select-Object -First 1).DisplayVersion",
+      ],
+    }),
+    cancelElevation: () => null,
+    elevationProbe: () => null,
+    appProcessProbe: scope => ({
+      file: "powershell",
+      args: [
+        "-NoProfile",
+        "-Command",
+        `(Get-CimInstance Win32_Process -Filter "ExecutablePath LIKE '${scope.replace(/%/g, "")}%'").ProcessId`,
+      ],
+    }),
+    appNameProbe: () => ({
+      file: "powershell",
+      args: ["-NoProfile", "-Command", "(Get-Process opencodex-desktop -ErrorAction SilentlyContinue).Id"],
+    }),
+    childPids: pid => ({
+      file: "powershell",
+      args: ["-NoProfile", "-Command", `(Get-CimInstance Win32_Process -Filter "ParentProcessId=${pid}").ProcessId`],
+    }),
+    uninstall: artifact => [{ file: "msiexec", args: ["/x", artifact, "/qn", "/norestart"] }],
+  };
+}
+
+/** Linux: deb and AppImage installs, xdotool gestures, systemd user registration. */
+export function linuxAdapter(runtime: AdapterRuntime): PlatformAdapter {
+  const run = runtime.run.bind(runtime);
+  return {
+    platform: "linux",
+    dependencies: () => ["dpkg", "dpkg-deb", "dpkg-query", "xdotool", "pgrep", "systemctl", "sudo", "cp", "chmod", "kill", "rm"],
+    npmLauncher: prefix => `${prefix}/node_modules/.bin/ocx`,
+    serviceInstall: launcher => ({ file: launcher, args: ["service", "install"] }),
+    serviceUninstall: launcher => ({ file: launcher, args: ["service", "uninstall"] }),
+    registrationState: async () => {
+      if (runtime.fileExists(join(runtime.homeDir(), ".config/systemd/user/opencodex-proxy.service"))) return "present";
+      // is-enabled: "enabled"/"linked" exit 0; "disabled" exits 1 but still means the
+      // unit file EXISTS. is-active: "active" exits 0; "inactive" exits 3 and also
+      // means the unit is registered. Absence prints "could not be found".
+      const enabled = await run({ file: "systemctl", args: ["--user", "is-enabled", "opencodex-proxy"] });
+      const enabledOut = (enabled.stdout + enabled.stderr).trim();
+      if (enabled.ok || /^\w*enabled$|^linked$/.test(enabled.stdout.trim()) || enabled.stdout.trim() === "disabled") return "present";
+      if (!/could not be found|no such file|not found/i.test(enabledOut)) return "unknown";
+      const active = await run({ file: "systemctl", args: ["--user", "is-active", "opencodex-proxy"] });
+      const activeOut = (active.stdout + active.stderr).trim();
+      if (active.ok || active.stdout.trim() === "inactive") return "present";
+      if (/could not be found|no such file|not found/i.test(activeOut)) return "absent";
+      return "unknown";
+    },
+    registrationFiles: () => [".config/systemd/user/opencodex-proxy.service"],
+    existingInstallation: (format, packageName) =>
+      format === "deb" && packageName
+        ? { file: "dpkg-query", args: ["-W", "-f", "${Status}", packageName] }
+        : null,
+    async installArtifact(artifact, workDir, format) {
+      if (format === "deb") {
+        const packageName = (await run({ file: "dpkg-deb", args: ["-f", artifact, "Package"] })).stdout.trim();
+        requireOk("dpkg install", await run({ file: "sudo", args: ["-n", "dpkg", "-i", artifact] }));
+        try {
+          const listing = await run({ file: "dpkg", args: ["-L", packageName] });
+          const appBinary = listing.stdout.split(/\r?\n/).find(line => line.startsWith("/usr/bin/")) ?? "";
+          if (!appBinary) throw new Error(`No /usr/bin executable found in package ${packageName}`);
+          return { appBinary, packageName, scope: appBinary, evidence: { packageName } };
+        } catch (error) {
+          // The dpkg install already landed; a discovery failure must not strand it.
+          await run({ file: "sudo", args: ["-n", "dpkg", "-r", packageName] });
+          throw error;
+        }
+      }
+      const appsDir = `${workDir}/apps`;
+      runtime.mkdir(appsDir);
+      const destination = `${appsDir}/OpenCodex.AppImage`;
+      requireOk("AppImage copy", await run({ file: "cp", args: [artifact, destination] }));
+      requireOk("AppImage chmod", await run({ file: "chmod", args: ["+x", destination] }));
+      return { appBinary: destination, scope: appsDir, evidence: { staged: destination } };
+    },
+    closeGesture: () => ({ file: "xdotool", args: ["search", "--name", "OpenCodex", "windowclose"] }),
+    quitGesture: () => ({
+      file: "xdotool",
+      args: ["search", "--name", "OpenCodex", "windowactivate", "--sync", "key", "alt+F4"],
+    }),
+    // A stock GNOME session has no tray; on a runner with a tray extension a
+    // pre-installed hook drives it. The engine records which path was taken.
+    trayClick: () => null,
+    trayQuit: () => null,
+    trayCheck: () => null,
+    trayInstall: () => null,
+    windowVisible: () => ({ file: "xdotool", args: ["search", "--name", "OpenCodex"] }),
+    installedVersion: (format, packageName) =>
+      format === "deb" && packageName
+        ? { file: "dpkg-query", args: ["-W", "-f", "${Version}", packageName] }
+        : null,
+    // Scoped to the pids the elevation monitor sighted — never a blanket pkill.
+    cancelElevation: pids =>
+      pids.length > 0 ? { file: "kill", args: pids.map(String) } : null,
+    // pkexec is the first elevation surface; the updater plugin then falls back to a
+    // zenity or kdialog password dialog, and a cancel must produce NEITHER.
+    // The updater's full elevation chain is pkexec -> zenity/kdialog -> terminal sudo.
+    // The gate never invokes sudo during the monitored update windows, so any sighting
+    // there is attributable to the updater.
+    elevationProbe: () => ({ file: "pgrep", args: ["-x", "pkexec|zenity|kdialog|sudo"] }),
+    appProcessProbe: scope => ({ file: "pgrep", args: ["-f", scope] }),
+    appNameProbe: () => ({ file: "pgrep", args: ["-f", "opencodex-desktop"] }),
+    childPids: pid => ({ file: "pgrep", args: ["-P", String(pid)] }),
+    uninstall: (_artifact, workDir, format, packageName) =>
+      format === "deb" && packageName
+        ? [{ file: "sudo", args: ["-n", "dpkg", "-r", packageName] }]
+        : [{ file: "rm", args: ["-f", `${workDir}/apps/OpenCodex.AppImage`] }],
+  };
+}
+
+function appleScript(...lines: string[]): CommandSpec {
+  return { file: "osascript", args: ["-e", lines.join(" ; ")] };
+}
diff --git a/desktop/scripts/installed-gate.ts b/desktop/scripts/installed-gate.ts
new file mode 100644
index 00000000000..4f02f443d42
--- /dev/null
+++ b/desktop/scripts/installed-gate.ts
@@ -0,0 +1,1002 @@
+/**
+ * The installed-artifact gate (D9 part two, R3).
+ *
+ * Installs the REAL desktop artifact on the host platform, launches it against a staged
+ * npm runtime, and drives the ownership contract from devlog plan 260921
+ * (080_decisions_round2.md): the staged runtime on a non-default port is drained with
+ * its registration preserved, the desktop install id becomes the owner with exactly one
+ * consent-generation increment, healthz on the preserved home and port reports the
+ * bundled sidecar as a child of the app process, close and the OS quit gesture leave
+ * both pids alive with the window reopenable, a full quit and relaunch restore
+ * ownership without re-asking consent, and tray Quit lets an in-flight request finish
+ * before both pids end. On Linux both update paths are exercised (R3): an AppImage
+ * updates in place without elevation to the exact target bytes, and a deb install asks
+ * for authorization only after Install is chosen, never retries a cancelled prompt with
+ * another elevation mechanism, preserves the old version on cancel, and installs the
+ * new version on accept.
+ *
+ * Safety shape, per the external re-audit (110_reaudit.md):
+ * - preflight-isolation runs BEFORE any mutation. A run that refuses because it found
+ *   an existing app, service registration or default-home state makes ZERO mutating
+ *   calls, cleanup included — cleanup only ever touches resources this run acquired.
+ * - GUI automation comes from operator-installed hook FILES under --hooks-dir, never
+ *   from dispatch-provided command text.
+ * - version inputs are strict semver; the npm package name is derived from this
+ *   repository's own package.json, never accepted as an argument.
+ *
+ * Every side effect goes through GateDeps so tests can prove call discipline (see the
+ * refusal test in tests/ci-workflows/installed-gate-drivers.test.ts).
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { commandInvocation } from "../../src/lib/win-exec";
+import {
+  type CommandSpec,
+  type GateFormat,
+  type GatePlatform,
+  type PlatformAdapter,
+  type ProcessEvidence,
+  linuxAdapter,
+  macosAdapter,
+  windowsAdapter,
+} from "./installed-gate-platforms";
+
+export interface GateOptions {
+  platform: GatePlatform;
+  format: GateFormat;
+  artifact: string;
+  olderArtifact?: string;
+  workDir: string;
+  toVersion: string;
+  fromVersion?: string;
+  reportPath: string;
+  hooksDir?: string;
+  consentHook?: string;
+  trayClickHook?: string;
+  trayQuitHook?: string;
+  trayCheckHook?: string;
+  trayInstallHook?: string;
+  /** Hook that answers the deb update's elevation prompt (drives the accept path). */
+  elevateAcceptHook?: string;
+  takeoverTimeoutMs: number;
+}
+
+export interface GatePhaseResult {
+  phase: string;
+  status: "pass" | "fail";
+  detail: string;
+  evidence: Record<string, unknown>;
+}
+
+export interface GateReport {
+  platform: GatePlatform;
+  format: GateFormat;
+  toVersion: string;
+  startedAt: string;
+  finishedAt?: string;
+  phases: GatePhaseResult[];
+  ok?: boolean;
+}
+
+export interface SpawnedProcess {
+  pid: number;
+  kill: () => void;
+  exited: Promise<number>;
+}
+
+/**
+ * Every side effect the engine can perform. Tests inject fakes; production gets the
+ * real implementations from defaultGateDeps().
+ */
+export interface GateDeps {
+  run(spec: CommandSpec, env?: Record<string, string | undefined>): Promise<ProcessEvidence>;
+  pidAlive(pid?: number): boolean;
+  killProcess(pid: number): void;
+  fileExists(path: string): boolean;
+  readJsonFile(path: string): unknown;
+  writeTextFile(path: string, content: string): void;
+  makeDir(path: string): void;
+  fetchJson(url: string, init?: { method?: string; headers?: Record<string, string>; body?: string; timeoutMs?: number }): Promise<{ ok: boolean; status: number; body: unknown }>;
+  spawnLogged(binary: string, logPath: string, errPath: string, env: Record<string, string | undefined>): SpawnedProcess;
+  serveMockProvider(): MockProvider;
+  digestFile(path: string): string | null;
+  homeDir(): string;
+  sleep(ms: number): Promise<void>;
+  readTextFile(path: string): string;
+}
+
+/** Hook names are file names inside --hooks-dir, nothing more. */
+const HOOK_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+
+/**
+ * Version inputs become npm dist-tags and artifact URLs. Strict semver shape is the
+ * whole grammar they are allowed to carry — anything else (an npm alias like
+ * npm:other@latest, a flag fragment) is rejected before it can reach npm or a shell.
+ */
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+/**
+ * Numeric-triple semver order. A prerelease suffix sorts before the bare release of the
+ * same triple; two suffixed versions compare lexically. The gate only needs "strictly
+ * older" answers for well-formed inputs, which parseGateArguments guarantees.
+ */
+export function compareSemver(a: string, b: string): number {
+  const parse = (v: string) => {
+    const [triple, suffix] = v.split("-", 2);
+    const parts = triple!.split(".").map(Number);
+    return { parts, suffix };
+  };
+  const left = parse(a);
+  const right = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const delta = (left.parts[i] ?? 0) - (right.parts[i] ?? 0);
+    if (delta !== 0) return delta < 0 ? -1 : 1;
+  }
+  if (left.suffix === right.suffix) return 0;
+  if (left.suffix === undefined) return 1;
+  if (right.suffix === undefined) return -1;
+  return left.suffix < right.suffix ? -1 : 1;
+}
+
+export function parseGateArguments(argv: string[]): { options?: GateOptions; error?: string } {
+  const value = (name: string): string | undefined => {
+    const index = argv.indexOf(`--${name}`);
+    return index >= 0 ? argv[index + 1] : undefined;
+  };
+  const required = ["platform", "format", "artifact", "work-dir", "to-version", "report"] as const;
+  const missing = required.filter(name => !value(name));
+  if (missing.length > 0) {
+    return { error: `missing required arguments: ${missing.map(name => `--${name}`).join(", ")}` };
+  }
+  const platform = value("platform");
+  const format = value("format");
+  if (platform !== "macos" && platform !== "windows" && platform !== "linux") {
+    return { error: "--platform must be macos, windows or linux" };
+  }
+  const expectedFormat: Record<GatePlatform, GateFormat[]> = {
+    macos: ["dmg"],
+    windows: ["msi"],
+    linux: ["deb", "appimage"],
+  };
+  if (!expectedFormat[platform].includes(format as GateFormat)) {
+    return { error: `--format ${format} is not a ${platform} artifact format` };
+  }
+  // R3: a Linux gate that cannot see one of the two promised update paths is not a gate,
+  // so the older artifact and its version are required, exactly like every other input.
+  if (platform === "linux" && !value("older-artifact")) {
+    return { error: "--older-artifact is required on linux: both update paths are in scope" };
+  }
+  const toVersion = value("to-version")!;
+  const fromVersion = value("from-version");
+  if (!SEMVER.test(toVersion)) return { error: "--to-version must be a strict semver (x.y.z[-suffix])" };
+  if (fromVersion !== undefined && !SEMVER.test(fromVersion)) {
+    return { error: "--from-version must be a strict semver (x.y.z[-suffix])" };
+  }
+  if (platform === "linux") {
+    if (!fromVersion) return { error: "--from-version is required on linux: the update phases need a proven-older release" };
+    if (fromVersion === toVersion) return { error: "--from-version must differ from --to-version" };
+    if (compareSemver(fromVersion, toVersion) >= 0) {
+      return { error: "--from-version must be strictly older than --to-version" };
+    }
+  }
+  const hooksDir = value("hooks-dir");
+  const hooks: Array<[keyof GateOptions, string | undefined]> = [
+    ["consentHook", value("consent-hook")],
+    ["trayClickHook", value("tray-click-hook")],
+    ["trayQuitHook", value("tray-quit-hook")],
+    ["trayCheckHook", value("tray-check-hook")],
+    ["trayInstallHook", value("tray-install-hook")],
+    ["elevateAcceptHook", value("elevate-accept-hook")],
+  ];
+  for (const [key, name] of hooks) {
+    if (name === undefined) continue;
+    if (!hooksDir) return { error: `--${key.replace(/[A-Z]/g, c => "-" + c.toLowerCase())} requires --hooks-dir` };
+    if (!HOOK_NAME.test(name)) {
+      return { error: `hook name \`${name}\` must be a plain file name inside the hooks directory` };
+    }
+  }
+  const takeoverTimeoutMs = Number(value("takeover-timeout") ?? 180) * 1000;
+  if (!Number.isFinite(takeoverTimeoutMs) || takeoverTimeoutMs <= 0) {
+    return { error: "--takeover-timeout must be a positive number of seconds" };
+  }
+  return {
+    options: {
+      platform,
+      format: format as GateFormat,
+      artifact: value("artifact")!,
+      olderArtifact: value("older-artifact"),
+      workDir: value("work-dir")!,
+      toVersion,
+      fromVersion,
+      reportPath: value("report")!,
+      hooksDir,
+      consentHook: value("consent-hook"),
+      trayClickHook: value("tray-click-hook"),
+      trayQuitHook: value("tray-quit-hook"),
+      trayCheckHook: value("tray-check-hook"),
+      trayInstallHook: value("tray-install-hook"),
+      elevateAcceptHook: value("elevate-accept-hook"),
+      takeoverTimeoutMs,
+    },
+  };
+}
+
+/**
+ * The staged npm runtime's package spec, derived from this repository's own
+ * package.json — the gate never takes a package spec as an argument.
+ */
+export function npmPackageSpec(packageName: string, version: string): string {
+  return `${packageName}@${version}`;
+}
+
+export function readOwnPackageName(packageJsonText: string): string | undefined {
+  try {
+    const parsed = JSON.parse(packageJsonText) as { name?: unknown };
+    return typeof parsed.name === "string" && parsed.name.length > 0 ? parsed.name : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface OwnershipObservation {
+  ownerInstallId?: string;
+  consentGeneration?: number;
+  raw: unknown;
+}
+
+/**
+ * Reads the durable ownership fields from service-state.json using lane C's schema:
+ * the record root carries an \`ownership\` object with the desktop install id and the
+ * consent generation. Any other shape is no observation, and the phase fails naming
+ * the file it read — the gate does not guess at schemas.
+ */
+export function observeOwnership(state: unknown): OwnershipObservation {
+  if (typeof state !== "object" || state === null) return { raw: state };
+  const ownership = (state as Record<string, unknown>).ownership;
+  if (typeof ownership !== "object" || ownership === null) return { raw: state };
+  const record = ownership as Record<string, unknown>;
+  return {
+    ownerInstallId: typeof record.installId === "string" ? record.installId : undefined,
+    consentGeneration: typeof record.consentGeneration === "number" ? record.consentGeneration : undefined,
+    raw: state,
+  };
+}
+
+export function evaluateOwnership(
+  before: OwnershipObservation,
+  after: OwnershipObservation,
+): { ok: boolean; detail: string } {
+  if (before.ownerInstallId !== undefined) {
+    return { ok: false, detail: "the staged npm runtime already carried an owner; the takeover precondition is an unowned runtime" };
+  }
+  if (!after.ownerInstallId) {
+    return { ok: false, detail: "the desktop install id is not recorded as owner in service-state.json" };
+  }
+  const beforeGeneration = before.consentGeneration ?? 0;
+  if (after.consentGeneration === undefined) {
+    return { ok: false, detail: "no consent generation is recorded in service-state.json" };
+  }
+  if (after.consentGeneration !== beforeGeneration + 1) {
+    return {
+      ok: false,
+      detail: `consent generation moved from ${beforeGeneration} to ${after.consentGeneration}; the contract allows exactly one increment`,
+    };
+  }
+  return { ok: true, detail: `owner ${after.ownerInstallId} recorded with consent generation ${after.consentGeneration}` };
+}
+
+/**
+ * Parses a pid listing. Empty output is no pids — never pid 0, which on POSIX means
+ * the caller's own process group and must never be signalled from here.
+ */
+export function parsePidList(stdout: string): number[] {
+  return stdout
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(line => line.length > 0)
+    .map(Number)
+    .filter(value => Number.isSafeInteger(value) && value > 0);
+}
+
+export function describeGatePhases(options: GateOptions): string[] {
+  const phases = [
+    "preflight-isolation",
+    "runner-readiness",
+    "stage-npm-runtime",
+    "install-artifact",
+    "launch-and-take-over",
+    "runtime-identity",
+    "close-gesture",
+    "quit-gesture",
+    "relaunch-consent",
+    "tray-quit-drains",
+  ];
+  if (options.platform === "linux") phases.push("update-verify");
+  phases.push("cleanup");
+  return phases;
+}
+
+export function summarizeReport(report: GateReport): string {
+  const lines = report.phases.map(
+    phase => `${phase.status === "pass" ? "PASS" : "FAIL"}  ${phase.phase}${phase.detail ? ` — ${phase.detail}` : ""}`,
+  );
+  return [`installed-artifact gate: ${report.ok ? "PASS" : "FAIL"} (${report.platform}/${report.format} v${report.toVersion})`, ...lines].join("\n");
+}
+
+interface Healthz {
+  status: string;
+  version?: string;
+  pid?: number;
+  role?: string;
+}
+
+const NON_DEFAULT_PORT = 10431;
+const ELEVATION_POLL_MS = 250;
+
+export interface MockProvider {
+  port: number;
+  /** Resolves when the first chat completion actually reached the mock. */
+  reached: Promise<void>;
+  /** Lets the held request finish. */
+  release: () => void;
+  stop: () => void;
+}
+
+/** The openai-chat compatible mock the drain phase holds an in-flight request against. */
+export function startMockProvider(): MockProvider {
+  let finish: () => void = () => {};
+  let markReached: () => void = () => {};
+  const held = new Promise<void>(resolve => { finish = resolve; });
+  const reached = new Promise<void>(resolve => { markReached = resolve; });
+  const server = Bun.serve({
+    port: 0,
+    fetch: async request => {
+      if (new URL(request.url).pathname.endsWith("/chat/completions")) {
+        markReached();
+        await held;
+        return Response.json({
+          id: "gate-drain",
+          object: "chat.completion",
+          choices: [{ index: 0, message: { role: "assistant", content: "drained" }, finish_reason: "stop" }],
+        });
+      }
+      return new Response("not found", { status: 404 });
+    },
+  });
+  return { port: server.port, reached, release: finish, stop: () => server.stop(true) };
+}
+
+export function defaultGateDeps(): GateDeps {
+  const spawnProcess = (binary: string, env: Record<string, string | undefined>, outPath?: string, errPath?: string): SpawnedProcess => {
+    const invocation = commandInvocation(binary, []);
+    const child = Bun.spawn({
+      cmd: [invocation.file, ...invocation.args],
+      env,
+      // Bun.spawn accepts a BunFile directly; a FileSink is not a valid stdio target.
+      stdout: outPath ? Bun.file(outPath) : "ignore",
+      stderr: errPath ? Bun.file(errPath) : "ignore",
+      stdin: "ignore",
+      ...invocation.options,
+    });
+    return { pid: child.pid, kill: () => child.kill(), exited: child.exited };
+  };
+  return {
+    run: async (spec, env) => {
+      const invocation = commandInvocation(spec.file, spec.args);
+      const proc = Bun.spawn({
+        cmd: [invocation.file, ...invocation.args],
+        stdout: "pipe",
+        stderr: "pipe",
+        env: env ?? { ...process.env },
+        ...invocation.options,
+      });
+      const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+      ]);
+      return { ok: exitCode === 0, exitCode, stdout, stderr };
+    },
+    pidAlive: pid => {
+      if (typeof pid !== "number") return false;
+      try {
+        process.kill(pid, 0);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    killProcess: pid => process.kill(pid),
+    fileExists: path => existsSync(path),
+    readJsonFile: path => {
+      try {
+        return JSON.parse(readFileSync(path, "utf8"));
+      } catch {
+        return undefined;
+      }
+    },
+    writeTextFile: (path, content) => writeFileSync(path, content),
+    makeDir: path => mkdirSync(path, { recursive: true }),
+    fetchJson: async (url, init) => {
+      const response = await fetch(url, {
+        method: init?.method,
+        headers: init?.headers,
+        body: init?.body,
+        signal: AbortSignal.timeout(init?.timeoutMs ?? 4000),
+      });
+      let body: unknown = undefined;
+      try {
+        body = await response.json();
+      } catch {
+        body = undefined;
+      }
+      return { ok: response.ok, status: response.status, body };
+    },
+    spawnLogged: (binary, logPath, errPath, env) => spawnProcess(binary, env, logPath, errPath),
+    serveMockProvider: () => startMockProvider(),
+    digestFile: path => (existsSync(path) ? createHash("sha256").update(readFileSync(path)).digest("hex") : null),
+    homeDir: () => homedir(),
+    sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+    readTextFile: path => readFileSync(path, "utf8"),
+  };
+}
+
+export async function runGate(options: GateOptions, deps: GateDeps = defaultGateDeps()): Promise<GateReport> {
+  const report: GateReport = {
+    platform: options.platform,
+    format: options.format,
+    toVersion: options.toVersion,
+    startedAt: new Date().toISOString(),
+    phases: [],
+  };
+  const workDir = options.workDir;
+  const home = join(workDir, "preserved-home");
+  const codexHome = join(workDir, "codex-home");
+  const npmPrefix = join(workDir, "npm-prefix");
+  const port = NON_DEFAULT_PORT;
+  const isolatedEnv = (): Record<string, string | undefined> => ({
+    ...process.env,
+    OPENCODEX_HOME: home,
+    CODEX_HOME: codexHome,
+  });
+  // Every command the gate drives runs under the staged homes — a probe or a service
+  // invocation must never read the runner account's real opencodex or codex home.
+  const run = (spec: CommandSpec): Promise<ProcessEvidence> => deps.run(spec, isolatedEnv());
+  const adapter: PlatformAdapter = (options.platform === "macos" ? macosAdapter : options.platform === "windows" ? windowsAdapter : linuxAdapter)(
+    { run, mkdir: path => deps.makeDir(path), fileExists: path => deps.fileExists(path), homeDir: () => deps.homeDir() },
+  );
+  const launcher = adapter.npmLauncher(npmPrefix);
+  const spawned: SpawnedProcess[] = [];
+  let npmPid: number | undefined;
+  let appPid: number | undefined;
+  let appBinary: string | undefined;
+  let packageName: string | undefined;
+  let takeoverOwnerId: string | undefined;
+  let takeoverGeneration: number | undefined;
+  let takeoverRuntimePid: number | undefined;
+  let installScope: string | undefined;
+  let mock: MockProvider | undefined;
+  let stopVerification = false;
+
+  const record = (phase: string, ok: boolean, detail: string, evidence: Record<string, unknown> = {}) => {
+    report.phases.push({ phase, status: ok ? "pass" : "fail", detail, evidence });
+    if (!ok) stopVerification = true;
+  };
+
+  const listPids = async (spec: CommandSpec): Promise<number[]> => {
+    const result = await run(spec);
+    if (!result.ok) return [];
+    return parsePidList(result.stdout);
+  };
+
+  const healthz = async (): Promise<Healthz | null> => {
+    try {
+      const response = await deps.fetchJson(`http://127.0.0.1:${port}/healthz`, { timeoutMs: 4000 });
+      if (!response.ok) return null;
+      const body = response.body as Record<string, unknown>;
+      if (body?.status !== "ok") return null;
+      return {
+        status: "ok",
+        version: typeof body.version === "string" ? body.version : undefined,
+        pid: typeof body.pid === "number" ? body.pid : undefined,
+        role: typeof body.role === "string" ? body.role : undefined,
+      };
+    } catch {
+      return null;
+    }
+  };
+
+  const waitFor = async (predicate: () => Promise<boolean>, timeoutMs: number, everyMs = 500): Promise<boolean> => {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (await predicate()) return true;
+      await deps.sleep(everyMs);
+    }
+    return await predicate();
+  };
+
+  /**
+   * A registration is present when any manager probe exits zero OR any on-disk
+   * registration file exists — unloaded launchd jobs, disabled systemd units and the
+   * WinSW native service all leave traces a single manager query would miss.
+   */
+  /** Resources THIS invocation placed on the machine; cleanup touches nothing else. */
+  const acquired = { service: false, artifact: false };
+
+  const resolveHook = (name?: string): string | undefined =>
+    name && options.hooksDir ? join(options.hooksDir, name) : undefined;
+
+  /** A pre-installed hook file runs directly, never through a shell. */
+  const runHook = async (name: string | undefined, fallback: () => CommandSpec | null): Promise<{ ok: boolean; via: string }> => {
+    const hook = resolveHook(name);
+    if (hook) {
+      if (!deps.fileExists(hook)) return { ok: false, via: `missing hook ${hook}` };
+      return { ok: (await run({ file: hook, args: [] })).ok, via: hook };
+    }
+    const spec = fallback();
+    if (!spec) return { ok: false, via: "no hook and no platform default" };
+    return { ok: (await run(spec)).ok, via: spec.file };
+  };
+
+  const windowVisible = async (): Promise<boolean> => {
+    const probe = await run(adapter.windowVisible());
+    // macOS prints a window count, Linux prints one window id per line, Windows
+    // prints nothing and answers through the exit code.
+    const firstLine = probe.stdout.trim().split(/\r?\n/)[0] ?? "";
+    return probe.ok && (firstLine === "" || Number(firstLine) > 0);
+  };
+
+  try {
+    // ---- preflight-isolation: refuse to touch a machine with real opencodex state.
+    // This phase completes BEFORE anything mutating; a refusal skips every later phase,
+    // and the cleanup below touches only resources recorded in `acquired`/`spawned`.
+    // Registration absence must be PROVEN: an unreadable manager probe is "unknown",
+    // and unknown refuses the run exactly like present does.
+    const registration = await adapter.registrationState();
+    const defaultState = join(deps.homeDir(), ".opencodex", "service-state.json");
+    const defaultStatePresent = deps.fileExists(defaultState);
+    const runningApp = await listPids(adapter.appNameProbe());
+    // A dormant install counts too: the gate would overwrite it, and cleanup could
+    // then remove something this run never installed. For deb the package name is read
+    // from the artifact (read-only) before probing dpkg.
+    let dormantInstall = false;
+    if (options.format === "deb") {
+      const nameProbe = await run({ file: "dpkg-deb", args: ["-f", options.artifact, "Package"] });
+      if (nameProbe.ok && nameProbe.stdout.trim()) {
+        const installed = adapter.existingInstallation("deb", nameProbe.stdout.trim());
+        dormantInstall = installed !== null && (await run(installed)).ok;
+      }
+    } else {
+      const installed = adapter.existingInstallation(options.format);
+      dormantInstall = installed !== null && (await run(installed)).ok;
+    }
+    const isolated = registration === "absent" && !defaultStatePresent && runningApp.length === 0 && !dormantInstall;
+    record(
+      "preflight-isolation",
+      isolated,
+      isolated
+        ? "no existing registration, default-home state or running app"
+        : "this runner already carries opencodex state; the gate would overwrite or remove it — refusing to run",
+      { registration, defaultStatePresent, runningApp, dormantInstall },
+    );
+
+    if (!stopVerification) {
+      deps.makeDir(home);
+      deps.makeDir(codexHome);
+      // ---- runner-readiness: every external command the adapter needs must resolve
+      // before an artifact is installed.
+      const dependencies = [...adapter.dependencies(), "npm"];
+      const missing: string[] = [];
+      for (const dependency of dependencies) {
+        const probe = process.platform === "win32"
+          ? await run({ file: "where.exe", args: [dependency] })
+          : await run({ file: "sh", args: ["-c", `command -v ${dependency}`] });
+        if (!probe.ok) missing.push(dependency);
+      }
+      record("runner-readiness", missing.length === 0,
+        missing.length === 0 ? `${dependencies.length} external commands resolve` : `missing: ${missing.join(", ")}`,
+        { missing });
+    }
+
+    if (!stopVerification) {
+      // ---- stage-npm-runtime: register FIRST so the recorded pid is the managed one.
+      // The package name comes from this repository's own package.json; only the
+      // semver-validated version is operator input.
+      const staging: Record<string, unknown> = {};
+      const packageName_ = readOwnPackageName(deps.readTextFile(join(import.meta.dir, "..", "..", "package.json")));
+      if (!packageName_) {
+        record("stage-npm-runtime", false, "could not read this repository's npm package name", staging);
+      } else {
+        const spec = npmPackageSpec(packageName_, options.fromVersion ?? options.toVersion);
+        staging.npmPackage = spec;
+        const install = await run({ file: "npm", args: ["install", "--prefix", npmPrefix, spec] });
+        staging.npmInstallExit = install.exitCode;
+        mock = deps.serveMockProvider();
+        deps.writeTextFile(
+          join(home, "config.json"),
+          JSON.stringify(
+            {
+              port,
+              defaultProvider: "gate-mock",
+              providers: {
+                "gate-mock": {
+                  adapter: "openai-chat",
+                  baseUrl: `http://127.0.0.1:${mock.port}/v1`,
+                  apiKey: "gate-mock-key",
+                },
+              },
+            },
+            null,
+            2,
+          ) + "\n",
+        );
+        let ok = install.ok;
+        if (ok) {
+          const registered = await run(adapter.serviceInstall(launcher));
+          staging.serviceInstallExit = registered.exitCode;
+          ok = registered.ok;
+          // A nonzero exit can still leave a registration behind; if anything is
+          // registered now, this run owns removing it.
+          acquired.service = (await adapter.registrationState()) === "present";
+        }
+        if (ok) ok = await waitFor(() => healthz().then(Boolean), 60_000);
+        const before = await healthz();
+        npmPid = before?.pid;
+        const present = (await adapter.registrationState()) === "present";
+        staging.npmRuntime = before;
+        staging.registrationPresent = present;
+        ok = ok && present && typeof npmPid === "number";
+        record(
+          "stage-npm-runtime",
+          ok,
+          ok ? `managed npm runtime pid ${npmPid} on port ${port}; registration present` : "staging failed; see evidence",
+          staging,
+        );
+      }
+    }
+
+    const ownershipBefore = observeOwnership(deps.readJsonFile(join(home, "service-state.json")));
+
+    if (!stopVerification) {
+      // ---- install-artifact: the real artifact, installed like a user would.
+      try {
+        const installResult = await adapter.installArtifact(options.artifact, workDir, options.format);
+        appBinary = installResult.appBinary;
+        packageName = installResult.packageName;
+        installScope = installResult.scope;
+        acquired.artifact = true;
+        record("install-artifact", Boolean(appBinary), `installed ${basename(options.artifact)} -> ${appBinary}`, installResult.evidence);
+      } catch (error) {
+        // A partial install is still an acquisition: mark it so cleanup rolls it back.
+        acquired.artifact = true;
+        record("install-artifact", false, String(error));
+      }
+    }
+
+    if (!stopVerification && appBinary) {
+      // ---- launch-and-take-over: consent once, drain the npm runtime, keep the registration.
+      const launched = deps.spawnLogged(appBinary, join(workDir, "app.log"), join(workDir, "app.err.log"), isolatedEnv());
+      spawned.push(launched);
+      appPid = launched.pid;
+      if (options.consentHook) await runHook(options.consentHook, () => null);
+      const taken = await waitFor(async () => {
+        const now = await healthz();
+        return now !== null && typeof now.pid === "number" && now.pid !== npmPid;
+      }, options.takeoverTimeoutMs);
+      const after = await healthz();
+      const npmDrained = !deps.pidAlive(npmPid);
+      const registration = (await adapter.registrationState()) === "present";
+      const ownershipAfter = observeOwnership(deps.readJsonFile(join(home, "service-state.json")));
+      const ownership = evaluateOwnership(ownershipBefore, ownershipAfter);
+      if (ownership.ok) {
+        takeoverOwnerId = ownershipAfter.ownerInstallId;
+        takeoverGeneration = ownershipAfter.consentGeneration;
+        takeoverRuntimePid = after?.pid;
+      }
+      const ok = taken && npmDrained && registration && ownership.ok;
+      record("launch-and-take-over", ok, [ownership.detail, `npm pid drained: ${npmDrained}`, `registration present: ${registration}`].join("; "), {
+        before: ownershipBefore.raw,
+        after: ownershipAfter.raw,
+        healthzAfter: after,
+      });
+    }
+
+    if (!stopVerification) {
+      // ---- runtime-identity: healthz on the preserved home+port is the bundled sidecar,
+      // a child of THIS launched app, reporting THIS release's version.
+      const now = await healthz();
+      const children = appPid !== undefined ? await listPids(adapter.childPids(appPid)) : [];
+      const portRecord = deps.readJsonFile(join(home, "runtime-port.json")) as { port?: number; pid?: number } | undefined;
+      const ok =
+        now?.pid !== undefined &&
+        children.includes(now.pid) &&
+        portRecord?.port === port &&
+        portRecord?.pid === now.pid &&
+        now.version === options.toVersion;
+      record("runtime-identity", ok, ok
+        ? `healthz pid ${now?.pid} v${now?.version} is a child of app pid ${appPid} on preserved port ${port}`
+        : "the answering runtime is not the bundled sidecar of the launched app on the preserved home",
+        { healthz: now, appPid, sidecarCandidates: children, runtimePortRecord: portRecord });
+    }
+
+    const gesture = async (phase: string, spec: CommandSpec) => {
+      if (stopVerification) return;
+      const before = await healthz();
+      const gestureResult = await run(spec);
+      // The gesture must actually hide the window; a no-op command exit is not the
+      // contract.
+      const windowHidden = await waitFor(async () => !(await windowVisible()), 10_000);
+      const after = await healthz();
+      const runtimeAlive = before?.pid !== undefined && before.pid === after?.pid;
+      const appAlive = deps.pidAlive(appPid);
+      const reopen = await runHook(options.trayClickHook, () => adapter.trayClick());
+      const visible = await waitFor(windowVisible, 15_000);
+      const ok = gestureResult.ok && windowHidden && runtimeAlive && appAlive && reopen.ok && visible;
+      record(phase, ok,
+        `gesture exit ${gestureResult.exitCode}; window hidden: ${windowHidden}; runtime pid ${after?.pid} alive: ${runtimeAlive}; app pid ${appPid} alive: ${appAlive}; window reopened via ${reopen.via}: ${visible}`,
+        { before, after });
+    };
+
+    await gesture("close-gesture", adapter.closeGesture());
+    await gesture("quit-gesture", adapter.quitGesture());
+
+    if (!stopVerification && appBinary) {
+      // ---- relaunch-consent: a FULL quit (tray Quit drains and ends both pids), then a
+      // cold relaunch must restore ownership WITHOUT asking again — the same install id,
+      // the same consent generation. Watching a single-instance duplicate exit is not
+      // this contract.
+      const quit = await runHook(options.trayQuitHook, () => adapter.trayQuit());
+      // Both pids — the app AND the runtime it owned at takeover — must actually end
+      // before the relaunch means anything.
+      const previousAppPid = appPid;
+      const ended = await waitFor(async () =>
+        !deps.pidAlive(previousAppPid)
+        && !deps.pidAlive(takeoverRuntimePid)
+        && (installScope === undefined || (await listPids(adapter.appProcessProbe(installScope))).length === 0),
+      30_000);
+      let ownershipRestored = false;
+      let relaunchHealth: Healthz | null = null;
+      if (ended) {
+        const relaunched = deps.spawnLogged(appBinary, join(workDir, "relaunch.log"), join(workDir, "relaunch.err.log"), isolatedEnv());
+        spawned.push(relaunched);
+        appPid = relaunched.pid;
+        const up = await waitFor(() => healthz().then(Boolean), 60_000);
+        relaunchHealth = await healthz();
+        const ownership = observeOwnership(deps.readJsonFile(join(home, "service-state.json")));
+        ownershipRestored = up
+          && ownership.ownerInstallId !== undefined
+          && ownership.ownerInstallId === takeoverOwnerId;
+        // A re-asked consent would move the generation; identical generation is the
+        // proof that nothing was asked.
+        ownershipRestored &&= ownership.consentGeneration !== undefined && ownership.consentGeneration === takeoverGeneration;
+      }
+      const ok = quit.ok && ended && ownershipRestored;
+      record("relaunch-consent", ok, ok
+        ? `full quit and cold relaunch restored owner ${takeoverOwnerId} without re-asking consent`
+        : "ownership was not restored after a cold relaunch, or consent was asked again",
+        { quitVia: quit.via, ended, ownerAfterRelaunch: relaunchHealth, takeoverOwnerId });
+    }
+
+    if (!stopVerification) {
+      // ---- tray-quit-drains: the request must be verifiably in flight when Quit fires.
+      const before = await healthz();
+      const request = deps.fetchJson(`http://127.0.0.1:${port}/v1/chat/completions`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: "Bearer gate-mock-key" },
+        body: JSON.stringify({ model: "gate-mock/gate-model", messages: [{ role: "user", content: "hold" }] }),
+        timeoutMs: 90_000,
+      }).then(response => response.status);
+      const inFlight = await Promise.race([
+        mock!.reached.then(() => true),
+        deps.sleep(15_000).then(() => false),
+      ]);
+      const quit = await runHook(options.trayQuitHook, () => adapter.trayQuit());
+      await deps.sleep(2000);
+      mock?.release();
+      let requestStatus: number | null = null;
+      try {
+        requestStatus = await request;
+      } catch {
+        requestStatus = null;
+      }
+      const drained = requestStatus === 200;
+      const bothEnded = await waitFor(async () => !deps.pidAlive(before?.pid) && (installScope === undefined || (await listPids(adapter.appProcessProbe(installScope))).length === 0), 30_000);
+      const ok = inFlight && quit.ok && drained && bothEnded;
+      record("tray-quit-drains", ok,
+        `request in flight at Quit: ${inFlight}; tray Quit driven via ${quit.via}; request finished with ${requestStatus}; both pids ended: ${bothEnded}`,
+        { runtimePid: before?.pid, requestStatus });
+    }
+
+    if (!stopVerification && options.platform === "linux" && options.olderArtifact && options.fromVersion) {
+      // ---- update-verify (R3): both Linux formats update through their own path, on
+      // both authorization outcomes. A failed prerequisite stops the phase BEFORE the
+      // next mutation, never after it.
+      for (const spec of adapter.uninstall(options.artifact, workDir, options.format, packageName)) {
+        await run(spec);
+      }
+      const older = await adapter.installArtifact(options.olderArtifact, workDir, options.format);
+      packageName = older.packageName;
+      installScope = older.scope;
+      const oldApp = deps.spawnLogged(older.appBinary, join(workDir, "older-app.log"), join(workDir, "older-app.err.log"), isolatedEnv());
+      spawned.push(oldApp);
+      appPid = oldApp.pid;
+      const oldHealthy = await waitFor(() => healthz().then(Boolean), 60_000);
+      const preVersion = adapter.installedVersion(options.format, packageName);
+      const preVersionOutput = preVersion ? await run(preVersion) : null;
+      const preVersionText = preVersionOutput?.ok ? preVersionOutput.stdout.trim() : "";
+      const preDigest = options.format === "appimage" ? deps.digestFile(older.appBinary) : null;
+      const targetDigest = options.format === "appimage" ? deps.digestFile(options.artifact) : null;
+
+      // One continuous monitor across the whole update operation: a fixed window can
+      // close before download and signature verification reach the elevation step.
+      // Sightings are attributed by the timestamp of each driver action.
+      const sightings: Array<{ pid: number; at: number }> = [];
+      const elevationProbe = adapter.elevationProbe();
+      let monitoring = true;
+      const monitorTask = (async () => {
+        while (monitoring && elevationProbe) {
+          for (const pid of await listPids(elevationProbe)) sightings.push({ pid, at: Date.now() });
+          await deps.sleep(ELEVATION_POLL_MS);
+        }
+      })();
+      const stopMonitor = async () => { monitoring = false; await monitorTask; };
+      const sightingsAfter = (timestamp: number): number[] =>
+        [...new Set(sightings.filter(sighting => sighting.at >= timestamp).map(sighting => sighting.pid))];
+
+      try {
+        let check = { ok: false, via: "skipped: old app never became healthy" };
+        let install = { ok: false, via: "skipped: old app never became healthy" };
+        let installStart = Number.POSITIVE_INFINITY;
+        if (oldHealthy) {
+          check = await runHook(options.trayCheckHook, () => adapter.trayCheck());
+          installStart = Date.now();
+          install = await runHook(options.trayInstallHook, () => adapter.trayInstall());
+        }
+        const elevationDuringCheck = [...new Set(
+          sightings.filter(sighting => sighting.at < installStart).map(sighting => sighting.pid),
+        )];
+
+        if (options.format === "appimage") {
+          // The installed file must become byte-identical to the target artifact — a
+          // changed digest alone would pass for an update to the wrong version, and a
+          // missing pre/target digest would make the transition vacuous.
+          await waitFor(async () => deps.digestFile(older.appBinary) === targetDigest, 120_000);
+          const postDigest = deps.digestFile(older.appBinary);
+          const anyElevation = sightingsAfter(0);
+          const ok = oldHealthy && check.ok && install.ok
+            && elevationDuringCheck.length === 0 && anyElevation.length === 0
+            && preDigest !== null && targetDigest !== null && preDigest !== targetDigest
+            && postDigest !== null && postDigest === targetDigest;
+          record("update-verify", ok,
+            `AppImage updated in place to the exact target artifact (digest match: ${postDigest === targetDigest}); no elevation anywhere (${anyElevation.length} sighted); path kept`,
+            { preDigest, postDigest, targetDigest, elevation: anyElevation });
+        } else {
+          // Cancel path: wait for the prompt, dismiss exactly the sighted pids, prove
+          // they exited, then prove NO elevation mechanism retries (the pinned plugin
+          // otherwise falls back pkexec -> zenity/kdialog -> sudo), and the version
+          // never moved.
+          const prompted = await waitFor(async () => sightingsAfter(installStart).length > 0, 90_000);
+          const elevation = sightingsAfter(installStart);
+          const cancel = adapter.cancelElevation(elevation);
+          let cancelOk = elevation.length === 0;
+          if (cancel && elevation.length > 0) {
+            cancelOk = (await run(cancel)).ok;
+            cancelOk &&= await waitFor(async () => elevation.every(pid => !deps.pidAlive(pid)), 10_000);
+          }
+          const cancelDoneAt = Date.now();
+          await deps.sleep(10_000);
+          const retriedElevation = sightingsAfter(cancelDoneAt);
+          const settledVersion = adapter.installedVersion(options.format, packageName);
+          const settledVersionOutput = settledVersion ? await run(settledVersion) : null;
+          const settledVersionText = settledVersionOutput?.ok ? settledVersionOutput.stdout.trim() : "";
+          const cancelPreserved = preVersionText !== "" && preVersionText === options.fromVersion && settledVersionText === preVersionText;
+          const cancelOkAll = oldHealthy && check.ok && install.ok
+            && elevationDuringCheck.length === 0 && prompted
+            && cancelOk && retriedElevation.length === 0 && cancelPreserved;
+
+          // Accept path: only after the cancel path held. Drive Install again, answer
+          // through the operator hook, and require the package to reach the target.
+          let acceptOk = false;
+          let acceptEvidence: Record<string, unknown> = { skipped: "no --elevate-accept-hook" };
+          if (options.elevateAcceptHook && cancelOkAll) {
+            const acceptStart = Date.now();
+            const installAgain = await runHook(options.trayInstallHook, () => adapter.trayInstall());
+            const promptedAgain = await waitFor(async () => sightingsAfter(acceptStart).length > 0, 90_000);
+            let hookOk = false;
+            if (promptedAgain) {
+              hookOk = (await runHook(options.elevateAcceptHook, () => null)).ok;
+            }
+            const accepted = await waitFor(async () => {
+              const probe = adapter.installedVersion(options.format, packageName);
+              if (!probe) return false;
+              const result = await run(probe);
+              return result.ok && result.stdout.trim() === options.toVersion;
+            }, 120_000);
+            acceptOk = installAgain.ok && promptedAgain && hookOk && accepted;
+            acceptEvidence = { installAgain: installAgain.ok, promptedAgain, hookOk, accepted };
+          } else if (options.elevateAcceptHook) {
+            acceptEvidence = { skipped: "cancel path failed; accept not attempted" };
+          }
+          const ok = cancelOkAll && acceptOk;
+          record("update-verify", ok,
+            `deb cancel path preserved ${settledVersionText} with no elevation retry (${retriedElevation.length}); accept path reached ${options.toVersion}: ${acceptOk}`,
+            { preVersion: preVersionText, postCancelVersion: settledVersionText, cancelOk, prompted, retriedElevation, accept: acceptEvidence });
+        }
+      } finally {
+        await stopMonitor();
+      }
+    }
+  } catch (error) {
+    // A thrown exception is a fatal phase of its own: without this, a crash between
+    // phases could leave a report whose recorded phases all pass.
+    record("fatal-error", false, String(error));
+  } finally {
+    // ---- cleanup: rolls back ONLY what this invocation acquired. A preflight refusal
+    // means nothing here runs against machine state: the gate must never destroy an
+    // existing installation it detected. Every rollback step runs; a failure fails the
+    // phase but never stops the remaining steps.
+    const cleanupEvidence: Record<string, unknown> = {};
+    let cleanupOk = true;
+    const fail = (key: string, error: unknown) => {
+      cleanupOk = false;
+      cleanupEvidence[key] = String(error);
+    };
+    for (const child of spawned) {
+      try { child.kill(); } catch (error) { fail(`spawned-${child.pid}`, error); }
+    }
+    // Processes the gate no longer owns: an AppImage update restarts detached from the
+    // original spawn handle. Only swept when this run launched an app at all.
+    if (appPid !== undefined && installScope !== undefined) {
+      for (const pid of await listPids(adapter.appProcessProbe(installScope))) {
+        try { deps.killProcess(pid); } catch (error) { fail(`app-${pid}`, error); }
+      }
+    }
+    if (deps.pidAlive(npmPid)) {
+      try { deps.killProcess(npmPid!); } catch (error) { fail("npm-runtime", error); }
+    }
+    if (acquired.service) {
+      try {
+        const result = await run(adapter.serviceUninstall(launcher));
+        if (!result.ok) fail("service-uninstall", result.stderr.trim() || `exit ${result.exitCode}`);
+      } catch (error) { fail("service-uninstall", error); }
+    }
+    if (acquired.artifact) {
+      for (const spec of adapter.uninstall(options.artifact, workDir, options.format, packageName)) {
+        try {
+          const result = await run(spec);
+          if (!result.ok) fail(`uninstall:${spec.args[1] ?? spec.file}`, result.stderr.trim() || `exit ${result.exitCode}`);
+        } catch (error) { fail("uninstall", error); }
+      }
+    }
+    mock?.stop();
+    record("cleanup", cleanupOk, cleanupOk ? "everything the gate installed was rolled back" : "a rollback step failed; see evidence", cleanupEvidence);
+    report.finishedAt = new Date().toISOString();
+    // Green means every phase ran AND passed — a report missing phases (a crash, an
+    // early refusal) is not green even if everything recorded passed.
+    const expectedPhases = describeGatePhases(options);
+    const covered = expectedPhases.every(name => report.phases.some(phase => phase.phase === name));
+    report.ok = report.phases.every(phase => phase.status === "pass") && covered;
+    deps.writeTextFile(options.reportPath, `${JSON.stringify(report, null, 2)}\n`);
+  }
+  return report;
+}
+
+if (import.meta.main) {
+  const parsed = parseGateArguments(Bun.argv.slice(2));
+  if (!parsed.options || parsed.error) {
+    console.error(parsed.error ?? "invalid arguments");
+    console.error(
+      "usage: installed-gate.ts --platform <macos|windows|linux> --format <dmg|msi|deb|appimage> --artifact <path>" +
+        " --older-artifact <path> --work-dir <dir> --to-version <version> --from-version <version> --report <path>" +
+        " [--hooks-dir <dir>] [--consent-hook <name>] [--tray-click-hook <name>] [--tray-quit-hook <name>]" +
+        " [--tray-check-hook <name>] [--tray-install-hook <name>] [--elevate-accept-hook <name>] [--takeover-timeout <seconds>]",
+    );
+    process.exit(2);
+  }
+  const report = await runGate(parsed.options);
+  console.log(summarizeReport(report));
+  process.exit(report.ok ? 0 : 1);
+}
diff --git a/desktop/scripts/prepare-sidecar.ts b/desktop/scripts/prepare-sidecar.ts
new file mode 100644
index 00000000000..502127870dc
--- /dev/null
+++ b/desktop/scripts/prepare-sidecar.ts
@@ -0,0 +1,59 @@
+import { copyFileSync, cpSync, existsSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const targetByTriple: Record<string, string> = {
+  "aarch64-apple-darwin": "bun-darwin-arm64",
+  "x86_64-apple-darwin": "bun-darwin-x64",
+  "x86_64-pc-windows-msvc": "bun-windows-x64",
+  "x86_64-unknown-linux-gnu": "bun-linux-x64",
+  "aarch64-unknown-linux-gnu": "bun-linux-arm64",
+};
+
+function argument(name: string): string | undefined {
+  const index = Bun.argv.indexOf(name);
+  return index < 0 ? undefined : Bun.argv[index + 1];
+}
+
+function hostTriple(): string | undefined {
+  const result = Bun.spawnSync(["rustc", "-vV"], { stdout: "pipe", stderr: "ignore" });
+  if (result.exitCode !== 0) return undefined;
+  const host = result.stdout.toString().match(/^host:\s*(\S+)$/m)?.[1];
+  return host;
+}
+
+const repoRoot = resolve(import.meta.dir, "../..");
+const triple =
+  argument("--target") ??
+  process.env.TARGET ??
+  process.env.RUST_TARGET ??
+  Bun.env.RUST_TARGET ??
+  hostTriple();
+if (!triple || !targetByTriple[triple]) {
+  throw new Error(
+    `Unsupported Rust target ${triple ?? "(host unavailable)"}; pass --target ${Object.keys(targetByTriple).join("|")}`,
+  );
+}
+
+const target = targetByTriple[triple];
+const source = join(repoRoot, "dist", "standalone", target);
+const executable = join(source, target.startsWith("bun-windows-") ? "ocx.exe" : "ocx");
+if (!existsSync(executable)) {
+  const result = Bun.spawnSync([
+    process.execPath,
+    "run",
+    "build:standalone",
+    "--target",
+    target,
+  ], { cwd: repoRoot, stdout: "inherit", stderr: "inherit" });
+  if (result.exitCode !== 0) process.exit(result.exitCode);
+}
+
+const desktopRoot = resolve(import.meta.dir, "..");
+const binaries = join(desktopRoot, "src-tauri", "binaries");
+const resources = join(desktopRoot, "src-tauri", "resources", "gui", "dist");
+mkdirSync(binaries, { recursive: true });
+mkdirSync(resources, { recursive: true });
+const destination = join(binaries, `ocx-${triple}${target.startsWith("bun-windows-") ? ".exe" : ""}`);
+copyFileSync(executable, destination);
+cpSync(join(repoRoot, "gui", "dist"), resources, { recursive: true });
+console.log(`Prepared ${destination}`);
diff --git a/desktop/scripts/updater-manifest.ts b/desktop/scripts/updater-manifest.ts
new file mode 100644
index 00000000000..e3fae9a372c
--- /dev/null
+++ b/desktop/scripts/updater-manifest.ts
@@ -0,0 +1,104 @@
+import {
+  existsSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+
+export interface UpdaterManifestOptions {
+  version: string;
+  dir: string;
+  repo: string;
+  out: string;
+  warn?: (message: string) => void;
+  requireAll?: boolean;
+}
+
+interface PlatformUpdate {
+  signature: string;
+  url: string;
+}
+
+export interface UpdaterManifest {
+  version: string;
+  notes: string;
+  pub_date: string;
+  platforms: Record<string, PlatformUpdate>;
+}
+
+export const platformFiles: Record<string, string> = {
+  "darwin-aarch64": "macos.app.tar.gz",
+  "darwin-x86_64": "macos.app.tar.gz",
+  "windows-x86_64": "windows-x64.msi",
+  // The AppImage is the plugin's default Linux target: it keeps the plain os-arch key so
+  // AppImage installs from releases before the deb target existed keep resolving updates.
+  "linux-x86_64": "linux-x86_64.AppImage",
+  // A deb install cannot apply an AppImage payload (the updater validates the downloaded
+  // bytes as a real .deb before installing), so it must resolve a distinct key. The shell
+  // selects this key from the bundle type embedded at packaging time; see updater.rs.
+  "linux-x86_64-deb": "linux-amd64.deb",
+};
+
+export function buildUpdaterManifest(options: UpdaterManifestOptions): UpdaterManifest {
+  const dir = resolve(options.dir);
+  const warn = options.warn ?? console.warn;
+  const platforms: Record<string, PlatformUpdate> = {};
+  const missing: string[] = [];
+  for (const [platform, suffix] of Object.entries(platformFiles)) {
+    const base = `OpenCodex-${options.version}-${suffix}`;
+    const signaturePath = join(dir, `${base}.sig`);
+    if (!existsSync(signaturePath)) {
+      missing.push(platform);
+      if (!options.requireAll) {
+        warn(`Skipping ${platform}: missing ${signaturePath}`);
+      }
+      continue;
+    }
+    platforms[platform] = {
+      signature: readFileSync(signaturePath, "utf8").trim(),
+      url: `https://github.com/${options.repo}/releases/download/v${options.version}/${base}`,
+    };
+  }
+  if (options.requireAll && missing.length > 0) {
+    throw new Error(`Missing signed updater platforms: ${missing.join(", ")}`);
+  }
+  if (Object.keys(platforms).length === 0) {
+    throw new Error("No signed updater platforms remain");
+  }
+  return {
+    version: options.version,
+    notes: `https://github.com/${options.repo}/releases/tag/v${options.version}`,
+    pub_date: new Date().toISOString(),
+    platforms,
+  };
+}
+
+export function writeUpdaterManifest(options: UpdaterManifestOptions): UpdaterManifest {
+  const manifest = buildUpdaterManifest(options);
+  const output = resolve(options.out);
+  const temporary = `${output}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(manifest, null, 2)}\n`);
+  renameSync(temporary, output);
+  return manifest;
+}
+
+function argument(name: string): string | undefined {
+  const index = Bun.argv.indexOf(name);
+  return index < 0 ? undefined : Bun.argv[index + 1];
+}
+
+if (import.meta.main) {
+  const version = argument("--version");
+  const dir = argument("--dir");
+  const repo = argument("--repo");
+  const out = argument("--out");
+  const requireAll = Bun.argv.includes("--require-all");
+  if (!version || !dir || !repo || !out) {
+    throw new Error(
+      "Usage: updater-manifest.ts --version <version> --dir <dir> --repo <owner/name> --out <file> [--require-all]",
+    );
+  }
+  writeUpdaterManifest({ version, dir, repo, out, requireAll });
+  console.log(`Wrote ${out}`);
+}
diff --git a/desktop/scripts/verify-release-assets.ts b/desktop/scripts/verify-release-assets.ts
new file mode 100644
index 00000000000..7292be7a684
--- /dev/null
+++ b/desktop/scripts/verify-release-assets.ts
@@ -0,0 +1,343 @@
+/**
+ * Pre-publication release asset verification.
+ *
+ * Everything a release will publish is checked here, in the verify-release job,
+ * before any publication step may run: the expected platform file set derived from
+ * the workflow's own packaging matrices and the producer scripts' tables, every
+ * recorded checksum against the bytes on disk, every updater signature
+ * cryptographically against the pinned minisign public key, and the updater
+ * manifest parsed back against the files it names. The result is a
+ * machine-readable receipt; attach-release requires the receipt to name the same
+ * version and commit before it uploads anything, so publication can only ever
+ * consume the verified bundle.
+ */
+import { createHash, createPublicKey, verify as ed25519Verify, type KeyObject } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  standaloneArchiveName,
+  standaloneTargets as sharedStandaloneTargets,
+} from "../../scripts/standalone-targets";
+import { bundlesByTarget } from "./collect-release-assets";
+import { platformFiles, writeUpdaterManifest, type UpdaterManifest } from "./updater-manifest";
+
+export interface VerifyReleaseAssetsOptions {
+  version: string;
+  dir: string;
+  repo: string;
+  sha: string;
+  repoRoot?: string;
+  manifestOut?: string;
+  receiptOut?: string;
+  requireSignatures?: boolean;
+}
+
+export interface ReleaseVerificationReceipt {
+  version: string;
+  repo: string;
+  sha: string;
+  expectedFiles: number;
+  checksumsVerified: number;
+  signaturesVerified: number;
+  manifestPlatforms: string[];
+}
+
+/**
+ * The expected file set, derived from the producer tables rather than restated.
+ * Signatures are required only for the assets the updater actually signs — the
+ * unique suffixes in platformFiles — because the DMG and the deb are not updater
+ * targets and are never signed.
+ */
+export function expectedReleaseAssets(options: {
+  version: string;
+  desktopTargets: string[];
+  requireSignatures?: boolean;
+}): string[] {
+  const expected: string[] = [];
+  for (const target of sharedStandaloneTargets) {
+    const archive = standaloneArchiveName(options.version, target);
+    expected.push(archive, `${archive}.sha256`);
+  }
+  const updaterSuffixes = new Set(Object.values(platformFiles));
+  for (const target of options.desktopTargets) {
+    const bundles = bundlesByTarget[target];
+    if (!bundles) throw new Error(`Unsupported desktop target in release matrix: ${target}`);
+    for (const bundle of bundles) {
+      const asset = `OpenCodex-${options.version}-${bundle.name}`;
+      expected.push(asset, `${asset}.sha256`);
+      if (options.requireSignatures && updaterSuffixes.has(bundle.name)) {
+        expected.push(`${asset}.sig`);
+      }
+    }
+  }
+  return expected;
+}
+
+/** The packaging matrices of the release workflow itself — the source of truth for the set. */
+export function releaseMatrixTargets(workflowText: string): {
+  standaloneTargets: string[];
+  desktopTargets: string[];
+} {
+  const workflow = Bun.YAML.parse(workflowText) as {
+    jobs?: Record<string, { strategy?: { matrix?: { include?: Array<{ target?: string }> } } }>;
+  };
+  const read = (job: string): string[] =>
+    (workflow.jobs?.[job]?.strategy?.matrix?.include ?? [])
+      .map(entry => entry.target)
+      .filter((target): target is string => typeof target === "string");
+  const standaloneTargets = read("package-standalone");
+  const desktopTargets = read("package-desktop");
+  if (standaloneTargets.length === 0 || desktopTargets.length === 0) {
+    throw new Error("release.yml packaging matrices are empty or unreadable");
+  }
+  return { standaloneTargets, desktopTargets };
+}
+
+/**
+ * Every recorded checksum against the bytes on disk, in exactly the producers'
+ * format (64 hex, two spaces, bare name, one trailing newline). The recorded name
+ * must equal the checksum file's own name minus the suffix: a foo.sha256 naming
+ * bar would leave foo's bytes unchecked while bar's are checked twice.
+ */
+export function verifyChecksums(dir: string): number {
+  const checksumFiles = readdirSync(dir).filter(name => name.endsWith(".sha256")).sort();
+  if (checksumFiles.length === 0) throw new Error(`No .sha256 files found in ${dir}`);
+  for (const checksumFile of checksumFiles) {
+    const content = readFileSync(join(dir, checksumFile), "utf8");
+    const match = /^([0-9a-f]{64})  (\S+)\n$/.exec(content);
+    if (!match) throw new Error(`Malformed checksum record in ${checksumFile}: ${JSON.stringify(content)}`);
+    const digest = match[1]!;
+    const recorded = match[2]!;
+    const own = checksumFile.slice(0, -".sha256".length);
+    if (recorded !== own) {
+      throw new Error(`Checksum ${checksumFile} records ${recorded}; it must record its own payload ${own}`);
+    }
+    const payload = join(dir, recorded);
+    if (!existsSync(payload)) throw new Error(`Checksum ${checksumFile} names ${recorded}, which is missing`);
+    const actual = createHash("sha256").update(readFileSync(payload)).digest("hex");
+    if (actual !== digest) {
+      throw new Error(`Checksum mismatch for ${recorded}: recorded ${digest}, computed ${actual}`);
+    }
+  }
+  return checksumFiles.length;
+}
+
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+export interface MinisignPublicKey {
+  keyId: string;
+  publicKey: KeyObject;
+}
+
+function minisignPayload(text: string, expectedBytes: number, what: string): Buffer {
+  const encoded = text
+    .split("\n")
+    .filter(line => line.trim().length > 0 && !line.trimStart().startsWith("untrusted comment:"))
+    .join("")
+    .trim();
+  const payload = Buffer.from(encoded, "base64");
+  if (payload.length !== expectedBytes) {
+    throw new Error(`Malformed ${what}: expected ${expectedBytes} decoded bytes, got ${payload.length}`);
+  }
+  return payload;
+}
+
+/** minisign public key: base64 of algorithm ("Ed") || key id (8) || raw key (32). */
+export function parseMinisignPublicKey(text: string): MinisignPublicKey {
+  const payload = minisignPayload(text, 42, "minisign public key");
+  const algorithm = payload.subarray(0, 2).toString("utf8");
+  if (algorithm !== "Ed") {
+    throw new Error(`Unsupported minisign public key algorithm: ${JSON.stringify(algorithm)}`);
+  }
+  return {
+    keyId: payload.subarray(2, 10).toString("hex"),
+    publicKey: createPublicKey({
+      key: Buffer.concat([ED25519_SPKI_PREFIX, payload.subarray(10, 42)]),
+      format: "der",
+      type: "spki",
+    }),
+  };
+}
+
+/** The updater public key pinned in the Tauri configuration. */
+export function loadUpdaterPublicKey(tauriConfPath: string): MinisignPublicKey {
+  const conf = JSON.parse(readFileSync(tauriConfPath, "utf8")) as {
+    plugins?: { updater?: { pubkey?: string } };
+  };
+  const pubkey = conf.plugins?.updater?.pubkey;
+  if (!pubkey) throw new Error(`No plugins.updater.pubkey in ${tauriConfPath}`);
+  return parseMinisignPublicKey(Buffer.from(pubkey, "base64").toString("utf8"));
+}
+
+/**
+ * minisign signature: base64 of algorithm || key id (8) || signature (64).
+ * "Ed" is a pure Ed25519 signature over the raw file bytes — the form the Tauri
+ * bundler emits. "ED" (BLAKE2b-prehashed) or anything else fails loudly rather
+ * than being silently mis-verified.
+ */
+export function verifyUpdaterSignature(filePath: string, key: MinisignPublicKey): void {
+  const signaturePath = `${filePath}.sig`;
+  if (!existsSync(signaturePath)) throw new Error(`Missing signature: ${signaturePath}`);
+  const payload = minisignPayload(readFileSync(signaturePath, "utf8"), 74, `signature ${signaturePath}`);
+  const algorithm = payload.subarray(0, 2).toString("utf8");
+  if (algorithm !== "Ed") {
+    throw new Error(`Unsupported signature algorithm in ${signaturePath}: ${JSON.stringify(algorithm)}`);
+  }
+  const keyId = payload.subarray(2, 10).toString("hex");
+  if (keyId !== key.keyId) {
+    throw new Error(`Signature ${signaturePath} was made by key ${keyId}, not the pinned updater key ${key.keyId}`);
+  }
+  if (!ed25519Verify(null, readFileSync(filePath), key.publicKey, payload.subarray(10, 74))) {
+    throw new Error(`Signature verification failed for ${filePath}`);
+  }
+}
+
+function parseBackManifest(manifestPath: string, options: VerifyReleaseAssetsOptions): string[] {
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as UpdaterManifest;
+  if (manifest.version !== options.version) {
+    throw new Error(`Manifest version ${manifest.version} != ${options.version}`);
+  }
+  const platforms = Object.keys(manifest.platforms).sort();
+  const expectedPlatforms = Object.keys(platformFiles).sort();
+  if (JSON.stringify(platforms) !== JSON.stringify(expectedPlatforms)) {
+    throw new Error(
+      `Manifest platforms (${platforms.join(", ")}) do not match the updater platform set (${expectedPlatforms.join(", ")})`,
+    );
+  }
+  for (const [platform, entry] of Object.entries(manifest.platforms)) {
+    const base = `OpenCodex-${options.version}-${platformFiles[platform]}`;
+    const expectedUrl = `https://github.com/${options.repo}/releases/download/v${options.version}/${base}`;
+    if (entry.url !== expectedUrl) {
+      throw new Error(`Manifest entry ${platform} points at ${entry.url}, expected ${expectedUrl}`);
+    }
+    if (!existsSync(join(options.dir, base))) {
+      throw new Error(`Manifest entry ${platform} names ${base}, which is missing`);
+    }
+    // The manifest must carry exactly the signature that was just verified,
+    // not merely a nonempty string.
+    const sidecar = readFileSync(join(options.dir, `${base}.sig`), "utf8").trim();
+    if (entry.signature !== sidecar) {
+      throw new Error(`Manifest entry ${platform} signature does not match ${base}.sig`);
+    }
+  }
+  return platforms;
+}
+
+function atomicWrite(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, content);
+  renameSync(temporary, path);
+}
+
+export function verifyReleaseAssets(options: VerifyReleaseAssetsOptions): ReleaseVerificationReceipt {
+  const repoRoot = resolve(options.repoRoot ?? join(import.meta.dir, "../.."));
+  const dir = resolve(options.dir);
+  const { standaloneTargets, desktopTargets } = releaseMatrixTargets(
+    readFileSync(join(repoRoot, ".github", "workflows", "release.yml"), "utf8"),
+  );
+  // The workflow matrix must describe exactly the shared target set the builder
+  // uses; a target added to one and not the other fails here, not at release time.
+  const workflowStandalone = [...standaloneTargets].sort();
+  const sharedStandalone = [...sharedStandaloneTargets].sort();
+  if (JSON.stringify(workflowStandalone) !== JSON.stringify(sharedStandalone)) {
+    throw new Error(
+      `release.yml package-standalone matrix (${workflowStandalone.join(", ")})`
+        + ` does not match scripts/standalone-targets.ts (${sharedStandalone.join(", ")})`,
+    );
+  }
+  const expected = expectedReleaseAssets({
+    version: options.version,
+    desktopTargets,
+    requireSignatures: options.requireSignatures,
+  });
+  const missing = expected.filter(name => !existsSync(join(dir, name)));
+  if (missing.length > 0) {
+    throw new Error(`Missing expected release assets:\n${missing.join("\n")}`);
+  }
+
+  const checksumsVerified = verifyChecksums(dir);
+
+  const updaterKey = loadUpdaterPublicKey(
+    join(repoRoot, "desktop", "src-tauri", "tauri.conf.json"),
+  );
+  // Every signature present is verified, required or not: a tampered signature in
+  // an unsigned dry-run bundle must fail, not be skipped.
+  let signaturesVerified = 0;
+  for (const name of readdirSync(dir).filter(candidate => candidate.endsWith(".sig")).sort()) {
+    const payload = join(dir, name.slice(0, -".sig".length));
+    if (!existsSync(payload)) throw new Error(`Signature ${name} has no payload beside it`);
+    verifyUpdaterSignature(payload, updaterKey);
+    signaturesVerified += 1;
+  }
+
+  let manifestPlatforms: string[] = [];
+  if (options.manifestOut) {
+    writeUpdaterManifest({
+      version: options.version,
+      dir,
+      repo: options.repo,
+      out: options.manifestOut,
+      requireAll: options.requireSignatures,
+    });
+    manifestPlatforms = parseBackManifest(options.manifestOut, options);
+  }
+
+  // attach-release uploads dist/release/* verbatim, so anything unexpected here
+  // would be published unchecked. The bundle is exactly the expected set plus
+  // the manifest this run just generated.
+  const allowed = new Set(expected);
+  if (options.manifestOut) allowed.add(options.manifestOut.split(/[\\/]/).pop()!);
+  const extras = readdirSync(dir).filter(name => !allowed.has(name));
+  if (extras.length > 0) {
+    throw new Error(`Unexpected files in the release bundle (refusing to publish them):\n${extras.join("\n")}`);
+  }
+
+  const receipt: ReleaseVerificationReceipt = {
+    version: options.version,
+    repo: options.repo,
+    sha: options.sha,
+    expectedFiles: expected.length,
+    checksumsVerified,
+    signaturesVerified,
+    manifestPlatforms,
+  };
+  if (options.receiptOut) {
+    atomicWrite(options.receiptOut, `${JSON.stringify(receipt, null, 2)}\n`);
+  }
+  return receipt;
+}
+
+function argument(name: string): string | undefined {
+  const index = Bun.argv.indexOf(name);
+  return index < 0 ? undefined : Bun.argv[index + 1];
+}
+
+if (import.meta.main) {
+  const version = argument("--version");
+  const dir = argument("--dir");
+  const repo = argument("--repo");
+  const sha = argument("--sha");
+  if (!version || !dir || !repo || !sha) {
+    throw new Error(
+      "Usage: verify-release-assets.ts --version <version> --dir <dir> --repo <owner/name> --sha <commit>"
+        + " [--manifest-out <file>] [--require-signatures] [--receipt-out <file>]",
+    );
+  }
+  const receipt = verifyReleaseAssets({
+    version,
+    dir,
+    repo,
+    sha,
+    manifestOut: argument("--manifest-out"),
+    receiptOut: argument("--receipt-out"),
+    requireSignatures: Bun.argv.includes("--require-signatures"),
+  });
+  console.log(
+    `Verified ${receipt.expectedFiles} expected files, ${receipt.checksumsVerified} checksums,`
+      + ` ${receipt.signaturesVerified} signatures`
+      + (receipt.manifestPlatforms.length > 0
+        ? `, manifest platforms: ${receipt.manifestPlatforms.join(", ")}`
+        : ""),
+  );
+}
diff --git a/desktop/src-tauri/Cargo.lock b/desktop/src-tauri/Cargo.lock
new file mode 100644
index 00000000000..db1cf16767c
--- /dev/null
+++ b/desktop/src-tauri/Cargo.lock
@@ -0,0 +1,5656 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "addr2line"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b5d307320b3181d6d7954e663bd7c774a838b8220fe0593c86d9fb09f498b4b"
+dependencies = [
+ "gimli",
+]
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "alloc-no-stdlib"
+version = "2.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc7bb162ec39d46ab1ca8c77bf72e890535becd1751bb45f64c597edb4c8c6b3"
+
+[[package]]
+name = "alloc-stdlib"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e76a019e91224d279006ff972f1e984179a6e9feb050adba6ce8274aef23195"
+dependencies = [
+ "alloc-no-stdlib",
+]
+
+[[package]]
+name = "android-tzdata"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e999941b234f3131b00bc13c22d06e8c5ff726d1b6318ac7eb276997bbb4fef0"
+
+[[package]]
+name = "android_system_properties"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "anyhow"
+version = "1.0.104"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
+
+[[package]]
+name = "arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"
+dependencies = [
+ "derive_arbitrary",
+]
+
+[[package]]
+name = "async-broadcast"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "435a87a52755b8f27fcf321ac4f04b2802e337c8c4872923137471ec39c37532"
+dependencies = [
+ "event-listener",
+ "event-listener-strategy",
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-channel"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "924ed96dd52d1b75e9c1a3e6275715fd320f5f9439fb5a4a11fa51f4221158d2"
+dependencies = [
+ "concurrent-queue",
+ "event-listener-strategy",
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-executor"
+version = "1.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c96bf972d85afc50bf5ab8fe2d54d1586b4e0b46c97c50a0c9e71e2f7bcd812a"
+dependencies = [
+ "async-task",
+ "concurrent-queue",
+ "fastrand",
+ "futures-lite",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "async-io"
+version = "2.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "456b8a8feb6f42d237746d4b3e9a178494627745c3c56c6ea55d92ba50d026fc"
+dependencies = [
+ "autocfg",
+ "cfg-if",
+ "concurrent-queue",
+ "futures-io",
+ "futures-lite",
+ "parking",
+ "polling",
+ "rustix",
+ "slab",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "async-lock"
+version = "3.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "290f7f2596bd5b78a9fec8088ccd89180d7f9f55b94b0576823bbbdc72ee8311"
+dependencies = [
+ "event-listener",
+ "event-listener-strategy",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-process"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc50921ec0055cdd8a16de48773bfeec5c972598674347252c0399676be7da75"
+dependencies = [
+ "async-channel",
+ "async-io",
+ "async-lock",
+ "async-signal",
+ "async-task",
+ "blocking",
+ "cfg-if",
+ "event-listener",
+ "futures-lite",
+ "rustix",
+]
+
+[[package]]
+name = "async-recursion"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b43422f69d8ff38f95f1b2bb76517c91589a924d1559a0e935d7c8ce0274c11"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "async-signal"
+version = "0.2.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52b5aaafa020cf5053a01f2a60e8ff5dccf550f0f77ec54a4e47285ac2bab485"
+dependencies = [
+ "async-io",
+ "async-lock",
+ "atomic-waker",
+ "cfg-if",
+ "futures-core",
+ "futures-io",
+ "rustix",
+ "signal-hook-registry",
+ "slab",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "async-task"
+version = "4.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b75356056920673b02621b35afd0f7dda9306d03c79a30f5c56c44cf256e3de"
+
+[[package]]
+name = "async-trait"
+version = "0.1.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "atk"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "241b621213072e993be4f6f3a9e4b45f65b7e6faad43001be957184b7bb1824b"
+dependencies = [
+ "atk-sys",
+ "glib",
+ "libc",
+]
+
+[[package]]
+name = "atk-sys"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c5e48b684b0ca77d2bbadeef17424c2ea3c897d44d566a1617e7e8f30614d086"
+dependencies = [
+ "glib-sys",
+ "gobject-sys",
+ "libc",
+ "system-deps",
+]
+
+[[package]]
+name = "atomic-waker"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
+
+[[package]]
+name = "auto-launch"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f012b8cc0c850f34117ec8252a44418f2e34a2cf501de89e29b241ae5f79471"
+dependencies = [
+ "dirs 4.0.0",
+ "thiserror 1.0.69",
+ "winreg 0.10.1",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "backtrace"
+version = "0.3.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb531853791a215d7c62a30daf0dde835f381ab5de4589cfe7c649d2cbe92bd6"
+dependencies = [
+ "addr2line",
+ "cfg-if",
+ "libc",
+ "miniz_oxide 0.8.9",
+ "object",
+ "rustc-demangle",
+ "windows-link 0.2.1",
+]
+
+[[package]]
+name = "base64"
+version = "0.21.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d297deb1925b89f2ccc13d7635fa0714f12c87adce1c75356b39ca9b7178567"
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "base64"
+version = "0.23.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
+
+[[package]]
+name = "bit-set"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"
+dependencies = [
+ "bit-vec",
+]
+
+[[package]]
+name = "bit-vec"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
+
+[[package]]
+name = "bitflags"
+version = "1.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
+
+[[package]]
+name = "bitflags"
+version = "2.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2261d10cca569e4643e526d8dc2e62e433cc8aba21ab764233731f8d369bf394"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "block2"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdeb9d870516001442e364c5220d3574d2da8dc765554b4a617230d33fa58ef5"
+dependencies = [
+ "objc2",
+]
+
+[[package]]
+name = "blocking"
+version = "1.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a70e4329df6cb94385eed412ec92375c3cdd8a6e502493d1229b6414e4036dfa"
+dependencies = [
+ "async-channel",
+ "async-task",
+ "futures-io",
+ "futures-lite",
+ "piper",
+]
+
+[[package]]
+name = "brotli"
+version = "8.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5cc91aac060a7a1e25823bdccbfb6af1875b88f17c6daac97894eed8207166b3"
+dependencies = [
+ "alloc-no-stdlib",
+ "alloc-stdlib",
+ "brotli-decompressor",
+]
+
+[[package]]
+name = "brotli-decompressor"
+version = "5.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a32acac15fe1967bc3986b2a6347dffc965602354ea6f450ad07e8bfd253583"
+dependencies = [
+ "alloc-no-stdlib",
+ "alloc-stdlib",
+]
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "bytemuck"
+version = "1.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
+
+[[package]]
+name = "byteorder"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
+
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "cairo-rs"
+version = "0.18.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ca26ef0159422fb77631dc9d17b102f253b876fe1586b03b803e63a309b4ee2"
+dependencies = [
+ "bitflags 2.9.4",
+ "cairo-sys-rs",
+ "glib",
+ "libc",
+ "once_cell",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "cairo-sys-rs"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "685c9fa8e590b8b3d678873528d83411db17242a73fccaed827770ea0fedda51"
+dependencies = [
+ "glib-sys",
+ "libc",
+ "system-deps",
+]
+
+[[package]]
+name = "camino"
+version = "1.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd0b03af37dad7a14518b7691d81acb0f8222604ad3d1b02f6b4bed5188c0cd5"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "cargo-platform"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e35af189006b9c0f00a064685c727031e3ed2d8020f7ba284d78cc2671bd36ea"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "cargo_metadata"
+version = "0.19.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd5eb614ed4c27c5d706420e4320fbe3216ab31fa1c33cd8246ac36dae4479ba"
+dependencies = [
+ "camino",
+ "cargo-platform",
+ "semver",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.20",
+]
+
+[[package]]
+name = "cargo_toml"
+version = "0.22.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "374b7c592d9c00c1f4972ea58390ac6b18cbb6ab79011f3bdc90a0b82ca06b77"
+dependencies = [
+ "serde",
+ "toml 0.9.5",
+]
+
+[[package]]
+name = "cc"
+version = "1.4.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "54413ede23c2daf518f35156dfde027feb2374004d63bd497f983c8db9c0e313"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cesu8"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d43a04d8753f35258c91f8ec639f792891f748a1edbd759cf1dcea3382ad83c"
+
+[[package]]
+name = "cfb"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d38f2da7a0a2c4ccf0065be06397cc26a81f4e528be095826eee9d4adbb8c60f"
+dependencies = [
+ "byteorder",
+ "fnv",
+ "uuid",
+]
+
+[[package]]
+name = "cfg-expr"
+version = "0.15.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d067ad48b8650848b989a59a86c6c36a995d02d2bf778d45c3c5d57bc2718f02"
+dependencies = [
+ "smallvec",
+ "target-lexicon",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "cfg_aliases"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
+
+[[package]]
+name = "chacha20"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.1",
+ "rand_core",
+]
+
+[[package]]
+name = "chrono"
+version = "0.4.41"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c469d952047f47f91b68d1cba3f10d63c11d73e4636f24f08daf0278abf01c4d"
+dependencies = [
+ "android-tzdata",
+ "iana-time-zone",
+ "num-traits",
+ "serde",
+ "windows-link 0.1.3",
+]
+
+[[package]]
+name = "combine"
+version = "4.6.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfc320937d09e6de266b31b9afb480f197d7a861be86be7cb2ea7e5d1bfffc5e"
+dependencies = [
+ "bytes",
+ "memchr",
+]
+
+[[package]]
+name = "concurrent-queue"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "cookie"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a373e3602691c3cdea496d2f0ee5935151e6168fe87739483c463db1b2f2f87"
+dependencies = [
+ "time",
+ "version_check",
+]
+
+[[package]]
+name = "core-foundation"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "core-graphics"
+version = "0.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "064badf302c3194842cf2c5d61f56cc88e54a759313879cdf03abdd27d0c3b97"
+dependencies = [
+ "bitflags 2.9.4",
+ "core-foundation",
+ "core-graphics-types",
+ "foreign-types",
+ "libc",
+]
+
+[[package]]
+name = "core-graphics-types"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d44a101f213f6c4cdc1853d4b78aef6db6bdfa3468798cc1d9912f4735013eb"
+dependencies = [
+ "bitflags 2.9.4",
+ "core-foundation",
+ "libc",
+]
+
+[[package]]
+name = "core_detect"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f8f80099a98041a3d1622845c271458a2d73e688351bf3cb999266764b81d48"
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "cpufeatures"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crc32fast"
+version = "1.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "01a7799fd6b852db0e61728dde9a204c423b44d689dbd432522543614b490e78"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "crossbeam-channel"
+version = "0.5.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "98b0cc327b5bc766e7fda9c9260cc0fa81b43a8e240440422dff70788e3f9ef1"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "cssparser"
+version = "0.36.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dae61cf9c0abb83bd659dab65b7e4e38d8236824c85f0f804f173567bda257d2"
+dependencies = [
+ "cssparser-macros",
+ "dtoa-short",
+ "itoa",
+ "phf",
+ "smallvec",
+]
+
+[[package]]
+name = "cssparser-macros"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13b588ba4ac1a99f7f2964d24b3d896ddc6bf847ee3855dbd4366f058cfcd331"
+dependencies = [
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "ctor"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "352d39c2f7bef1d6ad73db6f5160efcaed66d94ef8c6c573a8410c00bf909a98"
+dependencies = [
+ "ctor-proc-macro",
+ "dtor",
+]
+
+[[package]]
+name = "ctor-proc-macro"
+version = "0.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52560adf09603e58c9a7ee1fe1dcb95a16927b17c127f0ac02d6e768a0e25bc1"
+
+[[package]]
+name = "darling"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc7f46116c46ff9ab3eb1597a45688b6715c6e628b5c133e288e709a29bcb4ee"
+dependencies = [
+ "darling_core",
+ "darling_macro",
+]
+
+[[package]]
+name = "darling_core"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d00b9596d185e565c2207a0b01f8bd1a135483d02d9b7b0a54b11da8d53412e"
+dependencies = [
+ "fnv",
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "darling_macro"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc34b93ccb385b40dc71c6fceac4b2ad23662c7eeb248cf10d529b7e055b6ead"
+dependencies = [
+ "darling_core",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "dbus"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ab69f03cc8c4340c9c8e315114e1658e6775a9b16a04357973aa21cec22b32e"
+dependencies = [
+ "libc",
+ "libdbus-sys",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "deranged"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d630bccd429a5bb5a64b5e94f693bfc48c9f8566418fda4c494cc94f911f87cc"
+dependencies = [
+ "powerfmt",
+ "serde",
+]
+
+[[package]]
+name = "derive_arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "derive_more"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d751e9e49156b02b44f9c1815bcb94b984cdcc4396ecc32521c739452808b134"
+dependencies = [
+ "derive_more-impl",
+]
+
+[[package]]
+name = "derive_more-impl"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "799a97264921d8623a957f6c3b9011f3b5492f557bbb7a5a19b7fa6d06ba8dcb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "rustc_version",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
+[[package]]
+name = "dirs"
+version = "4.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca3aa72a6f96ea37bbc5aa912f6788242832f75369bdfdadcb0e38423f100059"
+dependencies = [
+ "dirs-sys 0.3.7",
+]
+
+[[package]]
+name = "dirs"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3e8aa94d75141228480295a7d0e7feb620b1a5ad9f12bc40be62411e38cce4e"
+dependencies = [
+ "dirs-sys 0.5.0",
+]
+
+[[package]]
+name = "dirs-sys"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b1d1d91c932ef41c0f2663aa8b0ca0342d444d842c06914aa0a7e352d0bada6"
+dependencies = [
+ "libc",
+ "redox_users 0.4.6",
+ "winapi",
+]
+
+[[package]]
+name = "dirs-sys"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e01a3366d27ee9890022452ee61b2b63a67e6f13f58900b651ff5665f0bb1fab"
+dependencies = [
+ "libc",
+ "option-ext",
+ "redox_users 0.5.3",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "dispatch2"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38"
+dependencies = [
+ "bitflags 2.9.4",
+ "block2",
+ "libc",
+ "objc2",
+]
+
+[[package]]
+name = "displaydoc"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "dlopen2"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e2c5bd4158e66d1e215c49b837e11d62f3267b30c92f1d171c4d3105e3dc4d4"
+dependencies = [
+ "dlopen2_derive",
+ "libc",
+ "once_cell",
+ "winapi",
+]
+
+[[package]]
+name = "dlopen2_derive"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fbbb781877580993a8707ec48672673ec7b81eeba04cfd2310bd28c08e47c8f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "dom_query"
+version = "0.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "521e380c0c8afb8d9a1e83a1822ee03556fc3e3e7dbc1fd30be14e37f9cb3f89"
+dependencies = [
+ "bit-set",
+ "cssparser",
+ "foldhash",
+ "html5ever",
+ "precomputed-hash",
+ "selectors",
+ "tendril",
+]
+
+[[package]]
+name = "dpi"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8b14ccef22fc6f5a8f4d7d768562a182c04ce9a3b3157b91390b52ddfdf1a76"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "dtoa"
+version = "1.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c3cf4824e2d5f025c7b531afcb2325364084a16806f6d47fbc1f5fbd9960590"
+
+[[package]]
+name = "dtoa-short"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd1511a7b6a56299bd043a9c167a6d2bfb37bf84a6dfceaba651168adfb43c87"
+dependencies = [
+ "dtoa",
+]
+
+[[package]]
+name = "dtor"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1057d6c64987086ff8ed0fd3fbf377a6b7d205cc7715868cd401705f715cbe4"
+dependencies = [
+ "dtor-proc-macro",
+]
+
+[[package]]
+name = "dtor-proc-macro"
+version = "0.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f678cf4a922c215c63e0de95eb1ff08a958a81d47e485cf9da1e27bf6305cfa5"
+
+[[package]]
+name = "dunce"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813"
+
+[[package]]
+name = "dyn-clone"
+version = "1.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
+
+[[package]]
+name = "embed-resource"
+version = "3.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63a1d0de4f2249aa0ff5884d7080814f446bb241a559af6c170a41e878ed2d45"
+dependencies = [
+ "cc",
+ "memchr",
+ "rustc_version",
+ "toml 0.9.5",
+ "vswhom",
+ "winreg 0.55.0",
+]
+
+[[package]]
+name = "embed_plist"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ef6b89e5b37196644d8796de5268852ff179b44e96276cf4290264843743bb7"
+
+[[package]]
+name = "encoding_rs"
+version = "0.8.41"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b5ef0006ac9ab233c38522f5ae99cae3625151de8f706cacee1cba4b8e2832a"
+dependencies = [
+ "cfg-if",
+ "core_detect",
+ "multiversion",
+ "multiversion_no_op",
+ "rustversion",
+ "scopeguard",
+ "simdutf8",
+]
+
+[[package]]
+name = "endi"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66b7e2430c6dff6a955451e2cfc438f09cea1965a9d6f87f7e3b90decc014099"
+
+[[package]]
+name = "enumflags2"
+version = "0.7.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1027f7680c853e056ebcec683615fb6fbbc07dbaa13b4d5d9442b146ded4ecef"
+dependencies = [
+ "enumflags2_derive",
+ "serde",
+]
+
+[[package]]
+name = "enumflags2_derive"
+version = "0.7.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67c78a4d8fdf9953a5c9d458f9efe940fd97a0cab0941c075a813ac594733827"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "erased-serde"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e004d887f51fcb9fef17317a2f3525c887d8aa3f4f50fed920816a688284a5b7"
+dependencies = [
+ "serde",
+ "typeid",
+]
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "event-listener"
+version = "5.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a23add41df1562121a9393cb065eab5146a1242410f23a644851e90cfd669d2"
+dependencies = [
+ "parking",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "event-listener-strategy"
+version = "0.5.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8be9f3dfaaffdae2972880079a491a1a8bb7cbed0b8dd7a347f668b4150a3b93"
+dependencies = [
+ "event-listener",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
+[[package]]
+name = "field-offset"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38e2275cc4e4fc009b0669731a1e5ab7ebf11f469eaede2bab9309a5b4d6057f"
+dependencies = [
+ "memoffset",
+ "rustc_version",
+]
+
+[[package]]
+name = "filetime"
+version = "0.2.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c287a33c7f0a620c38e641e7f60827713987b3c0f26e8ddc9462cc69cf75759"
+dependencies = [
+ "cfg-if",
+ "libc",
+]
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef25905e51abafe4dcea6c15fec58c57b601cdbd0ee53d22ea1d3016c587d39b"
+
+[[package]]
+name = "flate2"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide 0.9.1",
+ "zlib-rs",
+]
+
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
+[[package]]
+name = "foldhash"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
+
+[[package]]
+name = "foreign-types"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d737d9aa519fb7b749cbc3b962edcf310a8dd1f4b67c91c4f83975dbdd17d965"
+dependencies = [
+ "foreign-types-macros",
+ "foreign-types-shared",
+]
+
+[[package]]
+name = "foreign-types-macros"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea5190182e6915eb873ddbc16e23b711b6eb1f9c00a0d0a3a91b5f6228475225"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "foreign-types-shared"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa9a19cbb55df58761df49b23516a86d432839add4af60fc256da840f66ed35b"
+
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
+
+[[package]]
+name = "futures-executor"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-io"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"
+
+[[package]]
+name = "futures-lite"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f78e10609fe0e0b3f4157ffab1876319b5b0db102a2c60dc4626306dc46b44ad"
+dependencies = [
+ "fastrand",
+ "futures-core",
+ "futures-io",
+ "parking",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "futures-macro"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "futures-sink"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"
+
+[[package]]
+name = "futures-task"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"
+
+[[package]]
+name = "futures-util"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
+dependencies = [
+ "futures-core",
+ "futures-io",
+ "futures-macro",
+ "futures-sink",
+ "futures-task",
+ "memchr",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "gdk"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9f245958c627ac99d8e529166f9823fb3b838d1d41fd2b297af3075093c2691"
+dependencies = [
+ "cairo-rs",
+ "gdk-pixbuf",
+ "gdk-sys",
+ "gio",
+ "glib",
+ "libc",
+ "pango",
+]
+
+[[package]]
+name = "gdk-pixbuf"
+version = "0.18.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "50e1f5f1b0bfb830d6ccc8066d18db35c487b1b2b1e8589b5dfe9f07e8defaec"
+dependencies = [
+ "gdk-pixbuf-sys",
+ "gio",
+ "glib",
+ "libc",
+ "once_cell",
+]
+
+[[package]]
+name = "gdk-pixbuf-sys"
+version = "0.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9839ea644ed9c97a34d129ad56d38a25e6756f99f3a88e15cd39c20629caf7"
+dependencies = [
+ "gio-sys",
+ "glib-sys",
+ "gobject-sys",
+ "libc",
+ "system-deps",
+]
+
+[[package]]
+name = "gdk-sys"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c2d13f38594ac1e66619e188c6d5a1adb98d11b2fcf7894fc416ad76aa2f3f7"
+dependencies = [
+ "cairo-sys-rs",
+ "gdk-pixbuf-sys",
+ "gio-sys",
+ "glib-sys",
+ "gobject-sys",
+ "libc",
+ "pango-sys",
+ "pkg-config",
+ "system-deps",
+]
+
+[[package]]
+name = "gdkwayland-sys"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "140071d506d223f7572b9f09b5e155afbd77428cd5cc7af8f2694c41d98dfe69"
+dependencies = [
+ "gdk-sys",
+ "glib-sys",
+ "gobject-sys",
+ "libc",
+ "pkg-config",
+ "system-deps",
+]
+
+[[package]]
+name = "gdkx11"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3caa00e14351bebbc8183b3c36690327eb77c49abc2268dd4bd36b856db3fbfe"
+dependencies = [
+ "gdk",
+ "gdkx11-sys",
+ "gio",
+ "glib",
+ "libc",
+ "x11",
+]
+
+[[package]]
+name = "gdkx11-sys"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e2e7445fe01ac26f11601db260dd8608fe172514eb63b3b5e261ea6b0f4428d"
+dependencies = [
+ "gdk-sys",
+ "glib-sys",
+ "libc",
+ "system-deps",
+ "x11",
+]
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "wasi",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 5.3.0",
+ "wasip2",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "r-efi 6.0.0",
+ "rand_core",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "gimli"
+version = "0.32.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e629b9b98ef3dd8afe6ca2bd0f89306cec16d43d907889945bc5d6687f2f13c7"
+
+[[package]]
+name = "gio"
+version = "0.18.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4fc8f532f87b79cbc51a79748f16a6828fb784be93145a322fa14d06d354c73"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-util",
+ "gio-sys",
+ "glib",
+ "libc",
+ "once_cell",
+ "pin-project-lite",
+ "smallvec",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "gio-sys"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37566df850baf5e4cb0dfb78af2e4b9898d817ed9263d1090a2df958c64737d2"
+dependencies = [
+ "glib-sys",
+ "gobject-sys",
+ "libc",
+ "system-deps",
+ "winapi",
+]
+
+[[package]]
+name = "glib"
+version = "0.18.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "233daaf6e83ae6a12a52055f568f9d7cf4671dabb78ff9560ab6da230ce00ee5"
+dependencies = [
+ "bitflags 2.9.4",
+ "futures-channel",
+ "futures-core",
+ "futures-executor",
+ "futures-task",
+ "futures-util",
+ "gio-sys",
+ "glib-macros",
+ "glib-sys",
+ "gobject-sys",
+ "libc",
+ "memchr",
+ "once_cell",
+ "smallvec",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "glib-macros"
+version = "0.18.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bb0228f477c0900c880fd78c8759b95c7636dbd7842707f49e132378aa2acdc"
+dependencies = [
+ "heck 0.4.1",
+ "proc-macro-crate 2.0.2",
+ "proc-macro-error",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "glib-sys"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "063ce2eb6a8d0ea93d2bf8ba1957e78dbab6be1c2220dd3daca57d5a9d869898"
+dependencies = [
+ "libc",
+ "system-deps",
+]
+
+[[package]]
+name = "glob"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
+
+[[package]]
+name = "gobject-sys"
+version = "0.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0850127b514d1c4a4654ead6dedadb18198999985908e6ffe4436f53c785ce44"
+dependencies = [
+ "glib-sys",
+ "libc",
+ "system-deps",
+]
+
+[[package]]
+name = "gtk"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd56fb197bfc42bd5d2751f4f017d44ff59fbb58140c6b49f9b3b2bdab08506a"
+dependencies = [
+ "atk",
+ "cairo-rs",
+ "field-offset",
+ "futures-channel",
+ "gdk",
+ "gdk-pixbuf",
+ "gio",
+ "glib",
+ "gtk-sys",
+ "gtk3-macros",
+ "libc",
+ "pango",
+ "pkg-config",
+]
+
+[[package]]
+name = "gtk-sys"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f29a1c21c59553eb7dd40e918be54dccd60c52b049b75119d5d96ce6b624414"
+dependencies = [
+ "atk-sys",
+ "cairo-sys-rs",
+ "gdk-pixbuf-sys",
+ "gdk-sys",
+ "gio-sys",
+ "glib-sys",
+ "gobject-sys",
+ "libc",
+ "pango-sys",
+ "system-deps",
+]
+
+[[package]]
+name = "gtk3-macros"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ff3c5b21f14f0736fed6dcfc0bfb4225ebf5725f3c0209edeec181e4d73e9d"
+dependencies = [
+ "proc-macro-crate 1.3.1",
+ "proc-macro-error",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "heck"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "hermit-abi"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e17592d60ebacc7d5e169f4663c5f84f9161cc90328abcfe8456f41e4dfcb284"
+
+[[package]]
+name = "hex"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
+
+[[package]]
+name = "html5ever"
+version = "0.38.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1054432bae2f14e0061e33d23402fbaa67a921d319d56adc6bcf887ddad1cbc2"
+dependencies = [
+ "log",
+ "markup5ever",
+]
+
+[[package]]
+name = "http"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "http-body"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
+dependencies = [
+ "bytes",
+ "http",
+]
+
+[[package]]
+name = "http-body-util"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "hyper"
+version = "1.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27b501faa50e7a26c3d3560ca625132f4078a17771f4810baf70475ae48cbe43"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "http",
+ "http-body",
+ "httparse",
+ "itoa",
+ "pin-project-lite",
+ "smallvec",
+ "tokio",
+ "want",
+]
+
+[[package]]
+name = "hyper-rustls"
+version = "0.27.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
+dependencies = [
+ "http",
+ "hyper",
+ "hyper-util",
+ "rustls",
+ "tokio",
+ "tokio-rustls",
+ "tower-service",
+ "webpki-roots",
+]
+
+[[package]]
+name = "hyper-util"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
+dependencies = [
+ "base64 0.22.1",
+ "bytes",
+ "futures-channel",
+ "futures-util",
+ "http",
+ "http-body",
+ "hyper",
+ "ipnet",
+ "libc",
+ "percent-encoding",
+ "pin-project-lite",
+ "socket2 0.6.5",
+ "tokio",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core 0.62.2",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "ico"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e795dff5605e0f04bff85ca41b51a96b83e80b281e96231bcaaf1ac35103371"
+dependencies = [
+ "byteorder",
+ "png 0.17.16",
+]
+
+[[package]]
+name = "icu_collections"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa68d21081c4a05d5a901a1c62add574c77048b6a1c67be3b50ce0b60d4ca513"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d56e28588da92eee5c3201a6eff33fabdd49b62269c8938d4ff050ce4d900deb"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "12f9cf5f235641ed274641dd81c3f28d870e276763d0797aeeab72317b1c646f"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1563da1ed3e0b3bf3d74c9b85917ac9c56464d2f57242270c09c9e752f8021a0"
+
+[[package]]
+name = "icu_properties"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e7ca276ad3145661a65914e6daf131ca5120cd3dcee8f8f3214b8875184a148"
+dependencies = [
+ "displaydoc",
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e590f038c1464a96894fd6d10127e90a8be4509f56ff7ecef851b15cee0b7caa"
+
+[[package]]
+name = "icu_provider"
+version = "2.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d27bbb9d3abbefac45d55f647c9de1d44aafcd1186eb91879afef17c396c3e73"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "ident_case"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "moxcms",
+ "num-traits",
+ "png 0.18.1",
+]
+
+[[package]]
+name = "indexmap"
+version = "1.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bd070e393353796e801d209ad339e89596eb4c8d430d18ede6a1cced8fafbd99"
+dependencies = [
+ "autocfg",
+ "hashbrown 0.12.3",
+ "serde",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
+dependencies = [
+ "equivalent",
+ "hashbrown 0.17.1",
+]
+
+[[package]]
+name = "infer"
+version = "0.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a588916bfdfd92e71cacef98a63d9b1f0d74d6599980d11894290e7ddefffcf7"
+dependencies = [
+ "cfb",
+]
+
+[[package]]
+name = "ipnet"
+version = "2.12.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0"
+
+[[package]]
+name = "is-docker"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "928bae27f42bc99b60d9ac7334e3a21d10ad8f1835a4e12ec3ec0464765ed1b3"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "is-wsl"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "173609498df190136aa7dea1a91db051746d339e18476eed5ca40521f02d7aa5"
+dependencies = [
+ "is-docker",
+ "once_cell",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "javascriptcore-rs"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca5671e9ffce8ffba57afc24070e906da7fc4b1ba66f2cabebf61bf2ea257fcc"
+dependencies = [
+ "bitflags 1.3.2",
+ "glib",
+ "javascriptcore-rs-sys",
+]
+
+[[package]]
+name = "javascriptcore-rs-sys"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af1be78d14ffa4b75b66df31840478fef72b51f8c2465d4ca7c194da9f7a5124"
+dependencies = [
+ "glib-sys",
+ "gobject-sys",
+ "libc",
+ "system-deps",
+]
+
+[[package]]
+name = "jni"
+version = "0.21.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a87aa2bb7d2af34197c04845522473242e1aa17c12f4935d5856491a7fb8c97"
+dependencies = [
+ "cesu8",
+ "cfg-if",
+ "combine",
+ "jni-sys 0.3.1",
+ "log",
+ "thiserror 1.0.69",
+ "walkdir",
+ "windows-sys 0.45.0",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41a652e1f9b6e0275df1f15b32661cf0d4b78d4d87ddec5e0c3c20f097433258"
+dependencies = [
+ "jni-sys 0.4.1",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2"
+dependencies = [
+ "jni-sys-macros",
+]
+
+[[package]]
+name = "jni-sys-macros"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264"
+dependencies = [
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "js-sys"
+version = "0.3.105"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce57d20d1ea864ce2ac172ab472d409214f4fd359f0b2a2775abdf522e2af99e"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "json-patch"
+version = "3.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "863726d7afb6bc2590eeff7135d923545e5e964f004c2ccf8716c25e70a86f08"
+dependencies = [
+ "jsonptr",
+ "serde",
+ "serde_json",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "jsonptr"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5dea2b27dd239b2556ed7a25ba842fe47fd602e7fc7433c2a8d6106d4d9edd70"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "keyboard-types"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b750dcadc39a09dbadd74e118f6dd6598df77fa01df0cfcdc52c28dece74528a"
+dependencies = [
+ "bitflags 2.9.4",
+ "serde",
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "libappindicator"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "03589b9607c868cc7ae54c0b2a22c8dc03dd41692d48f2d7df73615c6a95dc0a"
+dependencies = [
+ "glib",
+ "gtk",
+ "gtk-sys",
+ "libappindicator-sys",
+ "log",
+]
+
+[[package]]
+name = "libappindicator-sys"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e9ec52138abedcc58dc17a7c6c0c00a2bdb4f3427c7f63fa97fd0d859155caf"
+dependencies = [
+ "gtk-sys",
+ "libloading",
+ "once_cell",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "libdbus-sys"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "328c4789d42200f1eeec05bd86c9c13c7f091d2ba9a6ea35acdf51f31bc0f043"
+dependencies = [
+ "pkg-config",
+]
+
+[[package]]
+name = "libloading"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67380fd3b2fbe7527a606e18729d21c6f3951633d0500574c4dc22d2d638b9f"
+dependencies = [
+ "cfg-if",
+ "winapi",
+]
+
+[[package]]
+name = "libredox"
+version = "0.1.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6480ccc157a1389bb2e4891b24751b0f798ba640d22386f23143fbcc89da195a"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "litemap"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae"
+
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
+[[package]]
+name = "log"
+version = "0.4.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
+
+[[package]]
+name = "lru-slab"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f"
+
+[[package]]
+name = "markup5ever"
+version = "0.38.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8983d30f2915feeaaab2d6babdd6bc7e9ed1a00b66b5e6d74df19aa9c0e91862"
+dependencies = [
+ "log",
+ "tendril",
+ "web_atoms",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "mime"
+version = "0.3.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
+
+[[package]]
+name = "minisign-verify"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22f9645cb765ea72b8111f36c522475d2daa0d22c957a9826437e97534bc4e9e"
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "miniz_oxide"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "mio"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b18443e9c262bfe8fa82f51666e2642c53393f7e5c27b3e1aeab922cff5b9d8"
+dependencies = [
+ "libc",
+ "wasi",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
+[[package]]
+name = "muda"
+version = "0.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1dd04e60bc0b07438a6771710ee1698f98f6ebbc7f89b61264af1563b8aeb878"
+dependencies = [
+ "crossbeam-channel",
+ "dpi",
+ "gtk",
+ "keyboard-types",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-core-foundation",
+ "objc2-foundation",
+ "once_cell",
+ "png 0.18.1",
+ "serde",
+ "thiserror 2.0.20",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "multiversion"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ca4bea16ffc3f443cf7d866912118196bfef4c6a1556ca00f9f9b00bb43f7c"
+dependencies = [
+ "multiversion-macros",
+]
+
+[[package]]
+name = "multiversion-macros"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d416831a7317ef4b08bee00b69cbbb9c8763da7959a7026244d6266869f9c83"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "rustversion",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "multiversion_no_op"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "743fb55ba31b18fb1ecef6bdc9aa2743314978ac084044301a7eee33fb99a20d"
+
+[[package]]
+name = "ndk"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3f42e7bbe13d351b6bead8286a43aac9534b82bd3cc43e47037f012ebfd62d4"
+dependencies = [
+ "bitflags 2.9.4",
+ "jni-sys 0.3.1",
+ "log",
+ "ndk-sys",
+ "num_enum",
+ "raw-window-handle",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "ndk-sys"
+version = "0.6.0+11769913"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee6cda3051665f1fb8d9e08fc35c96d5a244fb1be711a03b71118828afc9a873"
+dependencies = [
+ "jni-sys 0.3.1",
+]
+
+[[package]]
+name = "new_debug_unreachable"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
+
+[[package]]
+name = "num-conv"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "51d515d32fb182ee37cda2ccdcb92950d6a3c2893aa280e540671c2cd0f3b1d9"
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "num_enum"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d0bca838442ec211fa11de3a8b0e0e8f3a4522575b5c4c06ed722e005036f26"
+dependencies = [
+ "num_enum_derive",
+ "rustversion",
+]
+
+[[package]]
+name = "num_enum_derive"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8"
+dependencies = [
+ "proc-macro-crate 3.4.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "objc2"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a12a8ed07aefc768292f076dc3ac8c48f3781c8f2d5851dd3d98950e8c5a89f"
+dependencies = [
+ "objc2-encode",
+ "objc2-exception-helper",
+]
+
+[[package]]
+name = "objc2-app-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c"
+dependencies = [
+ "bitflags 2.9.4",
+ "block2",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-cloud-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73ad74d880bb43877038da939b7427bba67e9dd42004a18b809ba7d87cee241c"
+dependencies = [
+ "bitflags 2.9.4",
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-data"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b402a653efbb5e82ce4df10683b6b28027616a2715e90009947d50b8dd298fa"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
+dependencies = [
+ "bitflags 2.9.4",
+ "dispatch2",
+ "objc2",
+]
+
+[[package]]
+name = "objc2-core-graphics"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807"
+dependencies = [
+ "bitflags 2.9.4",
+ "dispatch2",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-io-surface",
+]
+
+[[package]]
+name = "objc2-core-image"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5d563b38d2b97209f8e861173de434bd0214cf020e3423a52624cd1d989f006"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-location"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca347214e24bc973fc025fd0d36ebb179ff30536ed1f80252706db19ee452009"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-text"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cde0dfb48d25d2b4862161a4d5fcc0e3c24367869ad306b0c9ec0073bfed92d"
+dependencies = [
+ "bitflags 2.9.4",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+]
+
+[[package]]
+name = "objc2-encode"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33"
+
+[[package]]
+name = "objc2-exception-helper"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7a1c5fbb72d7735b076bb47b578523aedc40f3c439bea6dfd595c089d79d98a"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "objc2-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
+dependencies = [
+ "bitflags 2.9.4",
+ "block2",
+ "libc",
+ "objc2",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-io-surface"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d"
+dependencies = [
+ "bitflags 2.9.4",
+ "objc2",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-osa-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f112d1746737b0da274ef79a23aac283376f335f4095a083a267a082f21db0c0"
+dependencies = [
+ "bitflags 2.9.4",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-quartz-core"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96c1358452b371bf9f104e21ec536d37a650eb10f7ee379fff67d2e08d537f1f"
+dependencies = [
+ "bitflags 2.9.4",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-ui-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d87d638e33c06f577498cbcc50491496a3ed4246998a7fbba7ccb98b1e7eab22"
+dependencies = [
+ "bitflags 2.9.4",
+ "block2",
+ "objc2",
+ "objc2-cloud-kit",
+ "objc2-core-data",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-core-image",
+ "objc2-core-location",
+ "objc2-core-text",
+ "objc2-foundation",
+ "objc2-quartz-core",
+ "objc2-user-notifications",
+]
+
+[[package]]
+name = "objc2-user-notifications"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9df9128cbbfef73cda168416ccf7f837b62737d748333bfe9ab71c245d76613e"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-web-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2e5aaab980c433cf470df9d7af96a7b46a9d892d521a2cbbb2f8a4c16751e7f"
+dependencies = [
+ "bitflags 2.9.4",
+ "block2",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-core-foundation",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "object"
+version = "0.37.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff76201f031d8863c38aa7f905eca4f53abbfa15f609db4277d44cd8938f33fe"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "open"
+version = "5.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa576c76302b7b808eecc68061e67336c47833ef9d22caa74dda10fa9675eebc"
+dependencies = [
+ "dunce",
+ "is-wsl",
+ "libc",
+]
+
+[[package]]
+name = "opencodex-desktop"
+version = "2.61.0"
+dependencies = [
+ "dbus",
+ "reqwest 0.12.24",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-build",
+ "tauri-plugin-autostart",
+ "tauri-plugin-opener",
+ "tauri-plugin-process",
+ "tauri-plugin-shell",
+ "tauri-plugin-single-instance",
+ "tauri-plugin-updater",
+ "tauri-utils",
+ "tokio",
+ "uuid",
+]
+
+[[package]]
+name = "option-ext"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
+
+[[package]]
+name = "ordered-stream"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9aa2b01e1d916879f73a53d01d1d6cee68adbb31d6d9177a8cfce093cced1d50"
+dependencies = [
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "os_pipe"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d8fae84b431384b68627d0f9b3b1245fcf9f46f6c0e3dc902e9dce64edd1967"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "osakit"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "732c71caeaa72c065bb69d7ea08717bd3f4863a4f451402fc9513e29dbd5261b"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+ "objc2-osa-kit",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.20",
+]
+
+[[package]]
+name = "pango"
+version = "0.18.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ca27ec1eb0457ab26f3036ea52229edbdb74dee1edd29063f5b9b010e7ebee4"
+dependencies = [
+ "gio",
+ "glib",
+ "libc",
+ "once_cell",
+ "pango-sys",
+]
+
+[[package]]
+name = "pango-sys"
+version = "0.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "436737e391a843e5933d6d9aa102cb126d501e815b83601365a948a518555dc5"
+dependencies = [
+ "glib-sys",
+ "gobject-sys",
+ "libc",
+ "system-deps",
+]
+
+[[package]]
+name = "parking"
+version = "2.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f38d5652c16fde515bb1ecef450ab0f6a219d619a7274976324d5e377f7dceba"
+
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link 0.2.1",
+]
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "phf"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c1562dc717473dbaa4c1f85a36410e03c047b2e7df7f45ee938fbef64ae7fadf"
+dependencies = [
+ "phf_macros",
+ "phf_shared",
+ "serde",
+]
+
+[[package]]
+name = "phf_codegen"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "49aa7f9d80421bca176ca8dbfebe668cc7a2684708594ec9f3c0db0805d5d6e1"
+dependencies = [
+ "phf_generator",
+ "phf_shared",
+]
+
+[[package]]
+name = "phf_generator"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "135ace3a761e564ec88c03a77317a7c6b80bb7f7135ef2544dbe054243b89737"
+dependencies = [
+ "fastrand",
+ "phf_shared",
+]
+
+[[package]]
+name = "phf_macros"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "812f032b54b1e759ccd5f8b6677695d5268c588701effba24601f6932f8269ef"
+dependencies = [
+ "phf_generator",
+ "phf_shared",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "phf_shared"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e57fef6bc5981e38c2ce2d63bfa546861309f875b8a75f092d1d54ae2d64f266"
+dependencies = [
+ "siphasher",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "piper"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c835479a4443ded371d6c535cbfd8d31ad92c5d23ae9770a61bc155e4992a3c1"
+dependencies = [
+ "atomic-waker",
+ "fastrand",
+ "futures-io",
+]
+
+[[package]]
+name = "pkg-config"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"
+
+[[package]]
+name = "plist"
+version = "1.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "740ebea15c5d1428f910cd1a5f52cebf8d25006245ed8ade92702f4943d91e07"
+dependencies = [
+ "base64 0.22.1",
+ "indexmap 2.14.2",
+ "quick-xml",
+ "serde",
+ "time",
+]
+
+[[package]]
+name = "png"
+version = "0.17.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526"
+dependencies = [
+ "bitflags 1.3.2",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide 0.8.9",
+]
+
+[[package]]
+name = "png"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
+dependencies = [
+ "bitflags 2.9.4",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide 0.8.9",
+]
+
+[[package]]
+name = "polling"
+version = "3.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d0e4f59085d47d8241c88ead0f274e8a0cb551f3625263c05eb8dd897c34218"
+dependencies = [
+ "cfg-if",
+ "concurrent-queue",
+ "hermit-abi",
+ "pin-project-lite",
+ "rustix",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "potential_utf"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661"
+dependencies = [
+ "zerovec",
+]
+
+[[package]]
+name = "powerfmt"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
+
+[[package]]
+name = "precomputed-hash"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "925383efa346730478fb4838dbe9137d2a47675ad789c546d150a6e1dd4ab31c"
+
+[[package]]
+name = "proc-macro-crate"
+version = "1.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f4c021e1093a56626774e81216a4ce732a735e5bad4868a03f3ed65ca0c3919"
+dependencies = [
+ "once_cell",
+ "toml_edit 0.19.15",
+]
+
+[[package]]
+name = "proc-macro-crate"
+version = "2.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b00f26d3400549137f92511a46ac1cd8ce37cb5598a96d382381458b992a5d24"
+dependencies = [
+ "toml_datetime 0.6.3",
+ "toml_edit 0.20.2",
+]
+
+[[package]]
+name = "proc-macro-crate"
+version = "3.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "219cb19e96be00ab2e37d6e299658a0cfa83e52429179969b0f0121b4ac46983"
+dependencies = [
+ "toml_edit 0.23.4",
+]
+
+[[package]]
+name = "proc-macro-error"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da25490ff9892aab3fcf7c36f08cfb902dd3e71ca0f9f9517bea02a73a5ce38c"
+dependencies = [
+ "proc-macro-error-attr",
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+ "version_check",
+]
+
+[[package]]
+name = "proc-macro-error-attr"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1be40180e52ecc98ad80b184934baf3d0d29f979574e439af5a55274b35f869"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "version_check",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pxfm"
+version = "0.1.30"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
+
+[[package]]
+name = "quick-xml"
+version = "0.38.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b66c2058c55a409d601666cffe35f04333cf1013010882cec174a7467cd4e21c"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "quinn"
+version = "0.11.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4051e23e9185c255a7e33ef59cdbca87a22d359052eecd22fc6b901fb37d9d11"
+dependencies = [
+ "bytes",
+ "cfg_aliases",
+ "pin-project-lite",
+ "quinn-proto",
+ "quinn-udp",
+ "rustc-hash",
+ "rustls",
+ "socket2 0.6.5",
+ "thiserror 2.0.20",
+ "tokio",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-proto"
+version = "0.11.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9746dbde176634f4f2f1faf2404e30a31b2bc1e9cafb5329c95d8177a18c9fc"
+dependencies = [
+ "bytes",
+ "getrandom 0.4.3",
+ "lru-slab",
+ "rand",
+ "rand_pcg",
+ "ring",
+ "rustc-hash",
+ "rustls",
+ "rustls-pki-types",
+ "slab",
+ "thiserror 2.0.20",
+ "tinyvec",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-udp"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694"
+dependencies = [
+ "cfg_aliases",
+ "libc",
+ "once_cell",
+ "socket2 0.6.5",
+ "tracing",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "rand"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7f5fa3a058cd35567ef9bfa5e75732bee0f9e4c55fa90477bef2dfcdbc4be80"
+dependencies = [
+ "chacha20",
+ "getrandom 0.4.3",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+
+[[package]]
+name = "rand_pcg"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a"
+dependencies = [
+ "rand_core",
+]
+
+[[package]]
+name = "raw-window-handle"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20675572f6f24e9e76ef639bc5552774ed45f1c30e2951e1e99c59888861c539"
+
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags 2.9.4",
+]
+
+[[package]]
+name = "redox_users"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba009ff324d1fc1b900bd1fdb31564febe58a8ccc8a6fdbb93b543d33b13ca43"
+dependencies = [
+ "getrandom 0.2.17",
+ "libredox",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "redox_users"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60dc65c0ff1a7ae1294b0c67b9f14baf70b644404010370171787bfac1038fc0"
+dependencies = [
+ "libredox",
+ "thiserror 2.0.20",
+]
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "reqwest"
+version = "0.12.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d0946410b9f7b082a427e4ef5c8ff541a88b357bc6c637c40db3a68ac70a36f"
+dependencies = [
+ "base64 0.22.1",
+ "bytes",
+ "futures-core",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-util",
+ "js-sys",
+ "log",
+ "percent-encoding",
+ "pin-project-lite",
+ "quinn",
+ "rustls",
+ "rustls-pki-types",
+ "serde",
+ "serde_json",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tokio-rustls",
+ "tokio-util",
+ "tower",
+ "tower-http",
+ "tower-service",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-streams 0.4.2",
+ "web-sys",
+ "webpki-roots",
+]
+
+[[package]]
+name = "reqwest"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16a1cfa75cc186dd73d5818e510e042e40927bccc9c236b061cea97e1eb08029"
+dependencies = [
+ "base64 0.23.1",
+ "bytes",
+ "futures-core",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "js-sys",
+ "log",
+ "percent-encoding",
+ "pin-project-lite",
+ "serde",
+ "serde_json",
+ "sync_wrapper",
+ "tokio",
+ "tokio-util",
+ "tower",
+ "tower-http",
+ "tower-service",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-streams 0.5.0",
+ "web-sys",
+]
+
+[[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom 0.2.17",
+ "libc",
+ "untrusted",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "rustc-demangle"
+version = "0.1.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b74b56ffa8bb2830709a538c2cbcae9aa062db0d2a42563bfb09bdaae44020eb"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "rustc_version"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
+dependencies = [
+ "semver",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "891efababe418670775f199f0d233d84843c227a0949a883ce15b37c78d6629d"
+dependencies = [
+ "bitflags 2.9.4",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls"
+version = "0.23.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
+dependencies = [
+ "once_cell",
+ "ring",
+ "rustls-pki-types",
+ "rustls-webpki",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-pki-types"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
+dependencies = [
+ "web-time",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-webpki"
+version = "0.103.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3c3cf1d8b1e7d4927e2d154c3fcb02979afb9939629c62cd9048d4f07b60ac2"
+dependencies = [
+ "ring",
+ "rustls-pki-types",
+ "untrusted",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "schemars"
+version = "0.8.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3fbf2ae1b8bc8e02df939598064d22402220cd5bbcca1c76f7d6a310974d5615"
+dependencies = [
+ "dyn-clone",
+ "indexmap 1.9.3",
+ "schemars_derive",
+ "serde",
+ "serde_json",
+ "url",
+ "uuid",
+]
+
+[[package]]
+name = "schemars_derive"
+version = "0.8.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32e265784ad618884abaea0600a9adf15393368d840e0222d101a072f3f7534d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde_derive_internals",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "selectors"
+version = "0.36.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c5d9c0c92a92d33f08817311cf3f2c29a3538a8240e94a6a3c622ce652d7e00c"
+dependencies = [
+ "bitflags 2.9.4",
+ "cssparser",
+ "derive_more",
+ "log",
+ "new_debug_unreachable",
+ "phf",
+ "phf_codegen",
+ "precomputed-hash",
+ "rustc-hash",
+ "servo_arc",
+ "smallvec",
+]
+
+[[package]]
+name = "semver"
+version = "1.0.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56e6fa9c48d24d85fb3de5ad847117517440f6beceb7798af16b4a87d616b8d0"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.219"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f0e2c6ed6606019b4e29e69dbaba95b11854410e5347d525002456dbbb786b6"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde-untagged"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34836a629bcbc6f1afdf0907a744870039b1e14c0561cb26094fa683b158eff3"
+dependencies = [
+ "erased-serde",
+ "serde",
+ "typeid",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.219"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b0276cf7f2c73365f7157c8123c21cd9a50fbbd844757af28ca1f5925fc2a00"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "serde_derive_internals"
+version = "0.29.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "18d26a20a969b9e3fdf2fc2d9f21eda6c40e2de84c9408bb5d3b05d499aae711"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.140"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20068b6e96dc6c9bd23e01df8827e6c7e1f2fddd43c21810382803c136b99373"
+dependencies = [
+ "itoa",
+ "memchr",
+ "ryu",
+ "serde",
+]
+
+[[package]]
+name = "serde_repr"
+version = "0.1.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8d3b1629de253c70a0508c3899572da79ca359fdab27c7920ff00406df418906"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "serde_spanned"
+version = "0.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "serde_spanned"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40734c41988f7306bb04f0ecf60ec0f3f1caa34290e4e8ea471dcd3346483b83"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "serde_urlencoded"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd"
+dependencies = [
+ "form_urlencoded",
+ "itoa",
+ "ryu",
+ "serde",
+]
+
+[[package]]
+name = "serde_with"
+version = "3.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21e47d95bc83ed33b2ecf84f4187ad1ab9685d18ff28db000c99deac8ce180e3"
+dependencies = [
+ "base64 0.21.7",
+ "chrono",
+ "hex",
+ "indexmap 1.9.3",
+ "serde",
+ "serde_json",
+ "serde_with_macros",
+ "time",
+]
+
+[[package]]
+name = "serde_with_macros"
+version = "3.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea3cee93715c2e266b9338b7544da68a9f24e227722ba482bd1c024367c77c65"
+dependencies = [
+ "darling",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "serialize-to-javascript"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "04f3666a07a197cdb77cdf306c32be9b7f598d7060d50cfd4d5aa04bfd92f6c5"
+dependencies = [
+ "serde",
+ "serde_json",
+ "serialize-to-javascript-impl",
+]
+
+[[package]]
+name = "serialize-to-javascript-impl"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "772ee033c0916d670af7860b6e1ef7d658a4629a6d0b4c8c3e67f09b3765b75d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "servo_arc"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "170fb83ab34de17dc69aa7c67482b22218ddb85da56546f9bd6b929e32a05930"
+dependencies = [
+ "stable_deref_trait",
+]
+
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest",
+]
+
+[[package]]
+name = "shared_child"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "607549934f6cc26b89cfecfdc46fa90f1e5d1536a68349b0c3a4f9d1c0d37959"
+dependencies = [
+ "libc",
+ "sigchld",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "sigchld"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24f2b37f04360cd465089b87a9c3869c08220a2f3458463f0adf8badf5e77f2c"
+dependencies = [
+ "libc",
+ "os_pipe",
+ "signal-hook",
+]
+
+[[package]]
+name = "signal-hook"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a0c28ca5908dbdbcd52e6fdaa00358ab88637f8ab33e1f188dd510eb44b53d"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
+[[package]]
+name = "simdutf8"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
+
+[[package]]
+name = "siphasher"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ee5873ec9cce0195efcb7a4e9507a04cd49aec9c83d0389df45b1ef7ba2e649"
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "smallvec"
+version = "1.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba467056f1b547ed52077911161fc86985becbc60e8e1857c8a144dab0def891"
+
+[[package]]
+name = "socket2"
+version = "0.5.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e22376abed350d73dd1cd119b57ffccad95b4e585a7cda43e286245ce23c0678"
+dependencies = [
+ "libc",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "socket2"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "softbuffer"
+version = "0.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aac18da81ebbf05109ab275b157c22a653bb3c12cf884450179942f81bcbf6c3"
+dependencies = [
+ "bytemuck",
+ "js-sys",
+ "ndk",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-foundation",
+ "objc2-quartz-core",
+ "raw-window-handle",
+ "redox_syscall",
+ "tracing",
+ "wasm-bindgen",
+ "web-sys",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "soup3"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "471f924a40f31251afc77450e781cb26d55c0b650842efafc9c6cbd2f7cc4f9f"
+dependencies = [
+ "futures-channel",
+ "gio",
+ "glib",
+ "libc",
+ "soup3-sys",
+]
+
+[[package]]
+name = "soup3-sys"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ebe8950a680a12f24f15ebe1bf70db7af98ad242d9db43596ad3108aab86c27"
+dependencies = [
+ "gio-sys",
+ "glib-sys",
+ "gobject-sys",
+ "libc",
+ "system-deps",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "string_cache"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a18596f8c785a729f2819c0f6a7eae6ebeebdfffbfe4214ae6b087f690e31901"
+dependencies = [
+ "new_debug_unreachable",
+ "parking_lot",
+ "phf_shared",
+ "precomputed-hash",
+]
+
+[[package]]
+name = "string_cache_codegen"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "585635e46db231059f76c5849798146164652513eb9e8ab2685939dd90f29b69"
+dependencies = [
+ "phf_generator",
+ "phf_shared",
+ "proc-macro2",
+ "quote",
+]
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
+[[package]]
+name = "swift-rs"
+version = "1.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e45c444e496845d3f2a351146bff59aae4975b2280238df1dfaa0c7d1846f38e"
+dependencies = [
+ "base64 0.21.7",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "syn"
+version = "1.0.109"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237"
+dependencies = [
+ "proc-macro2",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "sync_wrapper"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "system-deps"
+version = "6.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3e535eb8dded36d55ec13eddacd30dec501792ff23a0b1682c38601b8cf2349"
+dependencies = [
+ "cfg-expr",
+ "heck 0.5.0",
+ "pkg-config",
+ "toml 0.8.2",
+ "version-compare",
+]
+
+[[package]]
+name = "tao"
+version = "0.35.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1c93047acf68669466a34690ac58cca7010bd1b201e1ec86f1fd0a75d3dd4a9"
+dependencies = [
+ "bitflags 2.9.4",
+ "block2",
+ "core-foundation",
+ "core-graphics",
+ "crossbeam-channel",
+ "dbus",
+ "dispatch2",
+ "dlopen2",
+ "dpi",
+ "gdkwayland-sys",
+ "gdkx11-sys",
+ "gtk",
+ "jni",
+ "libc",
+ "log",
+ "ndk",
+ "ndk-sys",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-foundation",
+ "objc2-ui-kit",
+ "once_cell",
+ "parking_lot",
+ "percent-encoding",
+ "raw-window-handle",
+ "tao-macros",
+ "unicode-segmentation",
+ "url",
+ "windows",
+ "windows-core 0.61.2",
+ "windows-version",
+ "x11-dl",
+]
+
+[[package]]
+name = "tao-macros"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f7eeb6d99155545da6150a1795945f16ac9c178deb2a5f2e74d776107bd5849"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tar"
+version = "0.4.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f6221d9a6003c78398e3b239969f352578258df48c8eb051caadae0015bc840"
+dependencies = [
+ "filetime",
+ "libc",
+ "xattr",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "tauri"
+version = "2.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fa5bacdb9bbad5954af3d1bd6cf6ae9192cab1b2e270f4a07f904610b9e85f4"
+dependencies = [
+ "anyhow",
+ "bytes",
+ "cookie",
+ "dirs 6.0.0",
+ "dunce",
+ "embed_plist",
+ "getrandom 0.3.4",
+ "glob",
+ "gtk",
+ "heck 0.5.0",
+ "http",
+ "image",
+ "jni",
+ "libc",
+ "log",
+ "mime",
+ "muda",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-foundation",
+ "objc2-ui-kit",
+ "objc2-web-kit",
+ "percent-encoding",
+ "plist",
+ "raw-window-handle",
+ "reqwest 0.13.5",
+ "serde",
+ "serde_json",
+ "serde_repr",
+ "serialize-to-javascript",
+ "swift-rs",
+ "tauri-build",
+ "tauri-macros",
+ "tauri-runtime",
+ "tauri-runtime-wry",
+ "tauri-utils",
+ "thiserror 2.0.20",
+ "tokio",
+ "tray-icon",
+ "url",
+ "webkit2gtk",
+ "webview2-com",
+ "window-vibrancy",
+ "windows",
+]
+
+[[package]]
+name = "tauri-build"
+version = "2.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc9ce40b16101cb6ea63d3e221567affd1c3a9205f95d7bc574941a10636b632"
+dependencies = [
+ "anyhow",
+ "cargo_toml",
+ "dirs 6.0.0",
+ "glob",
+ "heck 0.5.0",
+ "json-patch",
+ "schemars",
+ "semver",
+ "serde",
+ "serde_json",
+ "tauri-utils",
+ "tauri-winres",
+ "walkdir",
+]
+
+[[package]]
+name = "tauri-codegen"
+version = "2.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08279169ff42f8fc45a1dbc9dcae888893ba95288142e5880c59b93a26d2cfc5"
+dependencies = [
+ "base64 0.22.1",
+ "brotli",
+ "ico",
+ "json-patch",
+ "plist",
+ "png 0.17.16",
+ "proc-macro2",
+ "quote",
+ "semver",
+ "serde",
+ "serde_json",
+ "sha2",
+ "syn 2.0.119",
+ "tauri-utils",
+ "thiserror 2.0.20",
+ "time",
+ "url",
+ "uuid",
+ "walkdir",
+]
+
+[[package]]
+name = "tauri-macros"
+version = "2.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8b394794f399a421811d06966343e7933fcae92d59f5180b9388d1174497a45"
+dependencies = [
+ "heck 0.5.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "tauri-codegen",
+ "tauri-utils",
+]
+
+[[package]]
+name = "tauri-plugin"
+version = "2.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74be5dd4bed9afbd145e5716b5fa2ec28cbc29c34ffa61c258c9273d896c8020"
+dependencies = [
+ "anyhow",
+ "glob",
+ "plist",
+ "schemars",
+ "serde",
+ "serde_json",
+ "tauri-utils",
+ "walkdir",
+]
+
+[[package]]
+name = "tauri-plugin-autostart"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "062cdcd483d5e3148c9a64dabf8c574e239e2aa1193cf208d95cf89a676f87a5"
+dependencies = [
+ "auto-launch",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-plugin",
+ "thiserror 2.0.20",
+]
+
+[[package]]
+name = "tauri-plugin-opener"
+version = "2.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc624469b06f59f5a29f874bbc61a2ed737c0f9c23ef09855a292c389c42e83f"
+dependencies = [
+ "dunce",
+ "glob",
+ "objc2-app-kit",
+ "objc2-foundation",
+ "open",
+ "schemars",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-plugin",
+ "thiserror 2.0.20",
+ "url",
+ "windows",
+ "zbus",
+]
+
+[[package]]
+name = "tauri-plugin-process"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7461c622a5ea00eb9cd9f7a08dbd3bf79484499fd5c21aa2964677f64ca651ab"
+dependencies = [
+ "tauri",
+ "tauri-plugin",
+]
+
+[[package]]
+name = "tauri-plugin-shell"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb2c50a63e60fb8925956cc5b7569f4b750ac197a4d39f13b8dd46ea8e2bad79"
+dependencies = [
+ "encoding_rs",
+ "log",
+ "open",
+ "os_pipe",
+ "regex",
+ "schemars",
+ "serde",
+ "serde_json",
+ "shared_child",
+ "tauri",
+ "tauri-plugin",
+ "thiserror 2.0.20",
+ "tokio",
+]
+
+[[package]]
+name = "tauri-plugin-single-instance"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc61e4822b8f74d68278e09161d3e3fdd1b14b9eb781e24edccaabf10c420e8c"
+dependencies = [
+ "serde",
+ "serde_json",
+ "tauri",
+ "thiserror 2.0.20",
+ "tracing",
+ "windows-sys 0.60.2",
+ "zbus",
+]
+
+[[package]]
+name = "tauri-plugin-updater"
+version = "2.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27cbc31740f4d507712550694749572ec0e43bdd66992db7599b89fbfd6b167b"
+dependencies = [
+ "base64 0.22.1",
+ "dirs 6.0.0",
+ "flate2",
+ "futures-util",
+ "http",
+ "infer",
+ "log",
+ "minisign-verify",
+ "osakit",
+ "percent-encoding",
+ "reqwest 0.12.24",
+ "semver",
+ "serde",
+ "serde_json",
+ "tar",
+ "tauri",
+ "tauri-plugin",
+ "tempfile",
+ "thiserror 2.0.20",
+ "time",
+ "tokio",
+ "url",
+ "windows-sys 0.60.2",
+ "zip",
+]
+
+[[package]]
+name = "tauri-runtime"
+version = "2.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b0b4bc95aed361b0019067d189a1174a603d460d0f6c72606512d59fc9c12ec8"
+dependencies = [
+ "cookie",
+ "dpi",
+ "gtk",
+ "http",
+ "jni",
+ "objc2",
+ "objc2-ui-kit",
+ "objc2-web-kit",
+ "raw-window-handle",
+ "serde",
+ "serde_json",
+ "tauri-utils",
+ "thiserror 2.0.20",
+ "url",
+ "webkit2gtk",
+ "webview2-com",
+ "windows",
+]
+
+[[package]]
+name = "tauri-runtime-wry"
+version = "2.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e6fac707727b7a2f48e4ded90976324267371073edbb415ffb73bb0458d203f"
+dependencies = [
+ "gtk",
+ "http",
+ "jni",
+ "log",
+ "objc2",
+ "objc2-app-kit",
+ "once_cell",
+ "percent-encoding",
+ "raw-window-handle",
+ "softbuffer",
+ "tao",
+ "tauri-runtime",
+ "tauri-utils",
+ "url",
+ "webkit2gtk",
+ "webview2-com",
+ "windows",
+ "wry",
+]
+
+[[package]]
+name = "tauri-utils"
+version = "2.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e176a18e67764923c4f1ce66f25ae4abe5f688384d5eb1a0fa6c77f3d90f887"
+dependencies = [
+ "anyhow",
+ "brotli",
+ "cargo_metadata",
+ "ctor",
+ "dom_query",
+ "dunce",
+ "glob",
+ "http",
+ "infer",
+ "json-patch",
+ "log",
+ "memchr",
+ "phf",
+ "plist",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "schemars",
+ "semver",
+ "serde",
+ "serde-untagged",
+ "serde_json",
+ "serde_with",
+ "swift-rs",
+ "thiserror 2.0.20",
+ "toml 0.9.5",
+ "url",
+ "urlpattern",
+ "uuid",
+ "walkdir",
+]
+
+[[package]]
+name = "tauri-winres"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1087b111fe2b005e42dbdc1990fc18593234238d47453b0c99b7de1c9ab2c1e0"
+dependencies = [
+ "dunce",
+ "embed-resource",
+ "toml 0.9.5",
+]
+
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "tendril"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5fed54709c5b3a53d09bb1c113ea4f5ceafd1e772ddcb0030a82e1d56c087b08"
+dependencies = [
+ "new_debug_unreachable",
+]
+
+[[package]]
+name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl 1.0.69",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
+dependencies = [
+ "thiserror-impl 2.0.20",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "time"
+version = "0.3.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e7d9e3bb61134e77bde20dd4825b97c010155709965fedf0f49bb138e52a9d"
+dependencies = [
+ "deranged",
+ "itoa",
+ "num-conv",
+ "powerfmt",
+ "serde",
+ "time-core",
+ "time-macros",
+]
+
+[[package]]
+name = "time-core"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40868e7c1d2f0b8d73e4a8c7f0ff63af4f6d19be117e90bd73eb1d62cf831c6b"
+
+[[package]]
+name = "time-macros"
+version = "0.2.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30cfb0125f12d9c277f35663a0a33f8c30190f4e4574868a330595412d34ebf3"
+dependencies = [
+ "num-conv",
+ "time-core",
+]
+
+[[package]]
+name = "tinystr"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1e27c91459209c2986af3dcf603a5a74a4368754ce37414f59acc971167f643"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
+[[package]]
+name = "tinyvec"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee"
+
+[[package]]
+name = "tokio"
+version = "1.45.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75ef51a33ef1da925cea3e4eb122833cb377c61439ca401b770f54902b806779"
+dependencies = [
+ "backtrace",
+ "bytes",
+ "libc",
+ "mio",
+ "pin-project-lite",
+ "socket2 0.5.10",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "tokio-rustls"
+version = "0.26.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b0c85f2c3ef0b1cd58b36682f4b17aaa995f0e5db534d85692b4903abce21f67"
+dependencies = [
+ "rustls",
+ "tokio",
+]
+
+[[package]]
+name = "tokio-util"
+version = "0.7.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ae9cec805b01e8fc3fd2fe289f89149a9b66dd16786abd8b19cfa7b48cb0098"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-sink",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "toml"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "185d8ab0dfbb35cf1399a6344d8484209c088f75f8f68230da55d48d95d43e3d"
+dependencies = [
+ "serde",
+ "serde_spanned 0.6.9",
+ "toml_datetime 0.6.3",
+ "toml_edit 0.20.2",
+]
+
+[[package]]
+name = "toml"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75129e1dc5000bfbaa9fee9d1b21f974f9fbad9daec557a521ee6e080825f6e8"
+dependencies = [
+ "indexmap 2.14.2",
+ "serde",
+ "serde_spanned 1.0.0",
+ "toml_datetime 0.7.0",
+ "toml_parser",
+ "toml_writer",
+ "winnow 0.7.15",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7cda73e2f1397b1262d6dfdcef8aafae14d1de7748d66822d3bfeeb6d03e5e4b"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bade1c3e902f58d73d3f294cd7f20391c1cb2fbcb643b73566bc773971df91e3"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.19.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b5bb770da30e5cbfde35a2d7b9b8a2c4b8ef89548a7a6aeab5c9a576e3e7421"
+dependencies = [
+ "indexmap 2.14.2",
+ "toml_datetime 0.6.3",
+ "winnow 0.5.40",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "396e4d48bbb2b7554c944bde63101b5ae446cff6ec4a24227428f15eb72ef338"
+dependencies = [
+ "indexmap 2.14.2",
+ "serde",
+ "serde_spanned 0.6.9",
+ "toml_datetime 0.6.3",
+ "winnow 0.5.40",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.23.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7211ff1b8f0d3adae1663b7da9ffe396eabe1ca25f0b0bee42b0da29a9ddce93"
+dependencies = [
+ "indexmap 2.14.2",
+ "toml_datetime 0.7.0",
+ "toml_parser",
+ "winnow 0.7.15",
+]
+
+[[package]]
+name = "toml_parser"
+version = "1.1.3+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d38ac1cf9b95face32296c0a3ede1fdc270627c9d9c02a7274dd6d960dc4d56"
+dependencies = [
+ "winnow 1.0.4",
+]
+
+[[package]]
+name = "toml_writer"
+version = "1.1.2+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d56353a2a665ad0f41a421187180aab746c8c325620617ad883a99a1cbe66d2"
+
+[[package]]
+name = "tower"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
+dependencies = [
+ "futures-core",
+ "futures-util",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tokio",
+ "tower-layer",
+ "tower-service",
+]
+
+[[package]]
+name = "tower-http"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
+dependencies = [
+ "bitflags 2.9.4",
+ "bytes",
+ "futures-util",
+ "http",
+ "http-body",
+ "pin-project-lite",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "url",
+]
+
+[[package]]
+name = "tower-layer"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
+
+[[package]]
+name = "tower-service"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-attributes",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-attributes"
+version = "0.1.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "tray-icon"
+version = "0.24.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "045979e3f037cd18ad1cb2a419dfda133c5c29c9f3453370079f2255d46c257e"
+dependencies = [
+ "crossbeam-channel",
+ "dirs 6.0.0",
+ "libappindicator",
+ "muda",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-foundation",
+ "once_cell",
+ "png 0.18.1",
+ "serde",
+ "thiserror 2.0.20",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "try-lock"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
+
+[[package]]
+name = "typeid"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc7d623258602320d5c55d1bc22793b57daff0ec7efc270ea7d55ce1d5f5471c"
+
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
+[[package]]
+name = "uds_windows"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f6fb2847f6742cd76af783a2a2c49e9375d0a111c7bef6f71cd9e738c72d6e"
+dependencies = [
+ "memoffset",
+ "tempfile",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "unic-char-property"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a8c57a407d9b6fa02b4795eb81c5b6652060a15a7903ea981f3d723e6c0be221"
+dependencies = [
+ "unic-char-range",
+]
+
+[[package]]
+name = "unic-char-range"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0398022d5f700414f6b899e10b8348231abf9173fa93144cbc1a43b9793c1fbc"
+
+[[package]]
+name = "unic-common"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80d7ff825a6a654ee85a63e80f92f054f904f21e7d12da4e22f9834a4aaa35bc"
+
+[[package]]
+name = "unic-ucd-ident"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e230a37c0381caa9219d67cf063aa3a375ffed5bf541a452db16e744bdab6987"
+dependencies = [
+ "unic-char-property",
+ "unic-char-range",
+ "unic-ucd-version",
+]
+
+[[package]]
+name = "unic-ucd-version"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96bd2f2237fe450fcd0a1d2f5f4e91711124f7857ba2e964247776ebeeb7b0c4"
+dependencies = [
+ "unic-common",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+ "serde_derive",
+]
+
+[[package]]
+name = "urlpattern"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70acd30e3aa1450bc2eece896ce2ad0d178e9c079493819301573dae3c37ba6d"
+dependencies = [
+ "regex",
+ "serde",
+ "unic-ucd-ident",
+ "url",
+]
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
+[[package]]
+name = "uuid"
+version = "1.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f87b8aa10b915a06587d0dec516c282ff295b475d94abf425d62b57710070a2"
+dependencies = [
+ "getrandom 0.3.4",
+ "js-sys",
+ "serde",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "version-compare"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "03c2856837ef78f57382f06b2b8563a2f512f7185d732608fd9176cb3b8edf0e"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "vswhom"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be979b7f07507105799e854203b470ff7c78a1639e330a58f183b5fea574608b"
+dependencies = [
+ "libc",
+ "vswhom-sys",
+]
+
+[[package]]
+name = "vswhom-sys"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb067e4cbd1ff067d1df46c9194b5de0e98efd2810bbc95c5d5e5f25a3231150"
+dependencies = [
+ "cc",
+ "libc",
+]
+
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
+[[package]]
+name = "want"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+dependencies = [
+ "try-lock",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.128"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aecb87a33d3b0c5e3b7aa46336eaf486cffafbd281b195e4c8b80d50df2351bf"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-futures"
+version = "0.4.78"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ef4c5d3d2cdf5c54f4231181768f5510842e350db025faf1f7163b1030ed928"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.128"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a690d511e3c1a8b3a55e33511e3c2c00c78415cd23650f32b808627f5696b9ed"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.128"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "411e4887f0071ef2d2164a9d5fdf2d20efbef78fccd3a78b0c10a1dc5295e48a"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.128"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "81941cd78d0c92026c33e5e01312845a4cb1e9af3407f9134b100dd03144103e"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "wasm-streams"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
+dependencies = [
+ "futures-util",
+ "js-sys",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
+[[package]]
+name = "wasm-streams"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d1ec4f6517c9e11ae630e200b2b65d193279042e28edd4a2cda233e46670bbb"
+dependencies = [
+ "futures-util",
+ "js-sys",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
+[[package]]
+name = "web-sys"
+version = "0.3.105"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9fbddc4a036f00ec4f18c83445bd3115cb306a91da554919a099d9222fe4a7f8"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "web-time"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "web_atoms"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba8b815c1b593dc0baf78dd0f4fc8fdb2de53198fb1163738093e9a311c33fb3"
+dependencies = [
+ "phf",
+ "phf_codegen",
+ "string_cache",
+ "string_cache_codegen",
+]
+
+[[package]]
+name = "webkit2gtk"
+version = "2.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1027150013530fb2eaf806408df88461ae4815a45c541c8975e61d6f2fc4793"
+dependencies = [
+ "bitflags 1.3.2",
+ "cairo-rs",
+ "gdk",
+ "gdk-sys",
+ "gio",
+ "gio-sys",
+ "glib",
+ "glib-sys",
+ "gobject-sys",
+ "gtk",
+ "gtk-sys",
+ "javascriptcore-rs",
+ "libc",
+ "once_cell",
+ "soup3",
+ "webkit2gtk-sys",
+]
+
+[[package]]
+name = "webkit2gtk-sys"
+version = "2.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "916a5f65c2ef0dfe12fff695960a2ec3d4565359fdbb2e9943c974e06c734ea5"
+dependencies = [
+ "bitflags 1.3.2",
+ "cairo-sys-rs",
+ "gdk-sys",
+ "gio-sys",
+ "glib-sys",
+ "gobject-sys",
+ "gtk-sys",
+ "javascriptcore-rs-sys",
+ "libc",
+ "pkg-config",
+ "soup3-sys",
+ "system-deps",
+]
+
+[[package]]
+name = "webpki-roots"
+version = "1.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "webview2-com"
+version = "0.38.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7130243a7a5b33c54a444e54842e6a9e133de08b5ad7b5861cd8ed9a6a5bc96a"
+dependencies = [
+ "webview2-com-macros",
+ "webview2-com-sys",
+ "windows",
+ "windows-core 0.61.2",
+ "windows-implement",
+ "windows-interface",
+]
+
+[[package]]
+name = "webview2-com-macros"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67a921c1b6914c367b2b823cd4cde6f96beec77d30a939c8199bb377cf9b9b54"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "webview2-com-sys"
+version = "0.38.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "381336cfffd772377d291702245447a5251a2ffa5bad679c99e61bc48bacbf9c"
+dependencies = [
+ "thiserror 2.0.20",
+ "windows",
+ "windows-core 0.61.2",
+]
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "window-vibrancy"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9bec5a31f3f9362f2258fd0e9c9dd61a9ca432e7306cc78c444258f0dce9a9c"
+dependencies = [
+ "objc2",
+ "objc2-app-kit",
+ "objc2-core-foundation",
+ "objc2-foundation",
+ "raw-window-handle",
+ "windows-sys 0.59.0",
+ "windows-version",
+]
+
+[[package]]
+name = "windows"
+version = "0.61.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9babd3a767a4c1aef6900409f85f5d53ce2544ccdfaa86dad48c91782c6d6893"
+dependencies = [
+ "windows-collections",
+ "windows-core 0.61.2",
+ "windows-future",
+ "windows-link 0.1.3",
+ "windows-numerics",
+]
+
+[[package]]
+name = "windows-collections"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3beeceb5e5cfd9eb1d76b381630e82c4241ccd0d27f1a39ed41b2760b255c5e8"
+dependencies = [
+ "windows-core 0.61.2",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0fdd3ddb90610c7638aa2b3a3ab2904fb9e5cdbecc643ddb3647212781c4ae3"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link 0.1.3",
+ "windows-result 0.3.4",
+ "windows-strings 0.4.2",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link 0.2.1",
+ "windows-result 0.4.1",
+ "windows-strings 0.5.1",
+]
+
+[[package]]
+name = "windows-future"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc6a41e98427b19fe4b73c550f060b59fa592d7d686537eebf9385621bfbad8e"
+dependencies = [
+ "windows-core 0.61.2",
+ "windows-link 0.1.3",
+ "windows-threading",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e6ad25900d524eaabdbbb96d20b4311e1e7ae1699af4fb28c17ae66c80d798a"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-numerics"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9150af68066c4c5c07ddc0ce30421554771e528bde427614c61038bc2c92c2b1"
+dependencies = [
+ "windows-core 0.61.2",
+ "windows-link 0.1.3",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56f42bd332cc6c8eac5af113fc0c1fd6a8fd2aa08a0119358686e5160d0586c6"
+dependencies = [
+ "windows-link 0.1.3",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link 0.2.1",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56e6c93f3a0c3b36176cb1327a4958a0353d5d166c2a35cb268ace15e91d3b57"
+dependencies = [
+ "windows-link 0.1.3",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link 0.2.1",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75283be5efb2831d37ea142365f009c02ec203cd29a3ebecbc093d52315b66d0"
+dependencies = [
+ "windows-targets 0.42.2",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
+dependencies = [
+ "windows-targets 0.53.5",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link 0.2.1",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e5180c00cd44c9b1c88adb3693291f1cd93605ded80c250a75d472756b4d071"
+dependencies = [
+ "windows_aarch64_gnullvm 0.42.2",
+ "windows_aarch64_msvc 0.42.2",
+ "windows_i686_gnu 0.42.2",
+ "windows_i686_msvc 0.42.2",
+ "windows_x86_64_gnu 0.42.2",
+ "windows_x86_64_gnullvm 0.42.2",
+ "windows_x86_64_msvc 0.42.2",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm 0.52.6",
+ "windows_aarch64_msvc 0.52.6",
+ "windows_i686_gnu 0.52.6",
+ "windows_i686_gnullvm 0.52.6",
+ "windows_i686_msvc 0.52.6",
+ "windows_x86_64_gnu 0.52.6",
+ "windows_x86_64_gnullvm 0.52.6",
+ "windows_x86_64_msvc 0.52.6",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.53.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
+dependencies = [
+ "windows-link 0.2.1",
+ "windows_aarch64_gnullvm 0.53.1",
+ "windows_aarch64_msvc 0.53.1",
+ "windows_i686_gnu 0.53.1",
+ "windows_i686_gnullvm 0.53.1",
+ "windows_i686_msvc 0.53.1",
+ "windows_x86_64_gnu 0.53.1",
+ "windows_x86_64_gnullvm 0.53.1",
+ "windows_x86_64_msvc 0.53.1",
+]
+
+[[package]]
+name = "windows-threading"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b66463ad2e0ea3bbf808b7f1d371311c80e115c0b71d60efc142cafbcfb057a6"
+dependencies = [
+ "windows-link 0.1.3",
+]
+
+[[package]]
+name = "windows-version"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4060a1da109b9d0326b7262c8e12c84df67cc0dbc9e33cf49e01ccc2eb63631"
+dependencies = [
+ "windows-link 0.2.1",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "597a5118570b68bc08d8d59125332c54f1ba9d9adeedeef5b99b02ba2b0698f8"
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e08e8864a60f06ef0d0ff4ba04124db8b0fb3be5776a5cd47641e942e58c4d43"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c61d927d8da41da96a81f029489353e68739737d3beca43145c8afec9a31a84f"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "44d840b6ec649f480a41c8d80f9c65108b92d89345dd94027bfe06ac444d1060"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8de912b8b8feb55c064867cf047dda097f92d51efad5b491dfb98f6bbb70cb36"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "26d41b46a36d453748aedef1486d5c7a85db22e56aff34643984ea85514e94a3"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9aec5da331524158c6d1a4ac0ab1541149c0b9505fde06423b02f5ef0106b9f0"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
+
+[[package]]
+name = "winnow"
+version = "0.5.40"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f593a95398737aeed53e489c785df13f3618e41dbcd6718c6addbf1395aa6876"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "winnow"
+version = "0.7.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "winnow"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "winreg"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80d0f4e272c85def139476380b12f9ac60926689dd2e01d4923222f40580869d"
+dependencies = [
+ "winapi",
+]
+
+[[package]]
+name = "winreg"
+version = "0.55.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb5a765337c50e9ec252c2069be9bf91c7df47afb103b642ba3a53bf8101be97"
+dependencies = [
+ "cfg-if",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "writeable"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
+
+[[package]]
+name = "wry"
+version = "0.55.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "186f9871daa55fd9c016578b810d149de58367113db7fb72b462d2323ce19514"
+dependencies = [
+ "base64 0.22.1",
+ "block2",
+ "cookie",
+ "crossbeam-channel",
+ "dirs 6.0.0",
+ "dom_query",
+ "dpi",
+ "dunce",
+ "gdkx11",
+ "gtk",
+ "http",
+ "javascriptcore-rs",
+ "jni",
+ "libc",
+ "ndk",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-core-foundation",
+ "objc2-foundation",
+ "objc2-ui-kit",
+ "objc2-web-kit",
+ "once_cell",
+ "percent-encoding",
+ "raw-window-handle",
+ "sha2",
+ "soup3",
+ "tao-macros",
+ "thiserror 2.0.20",
+ "url",
+ "webkit2gtk",
+ "webkit2gtk-sys",
+ "webview2-com",
+ "windows",
+ "windows-core 0.61.2",
+ "windows-version",
+ "x11-dl",
+]
+
+[[package]]
+name = "x11"
+version = "2.21.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "502da5464ccd04011667b11c435cb992822c2c0dbde1770c988480d312a0db2e"
+dependencies = [
+ "libc",
+ "pkg-config",
+]
+
+[[package]]
+name = "x11-dl"
+version = "2.21.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38735924fedd5314a6e548792904ed8c6de6636285cb9fec04d5b1db85c1516f"
+dependencies = [
+ "libc",
+ "once_cell",
+ "pkg-config",
+]
+
+[[package]]
+name = "xattr"
+version = "1.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32e45ad4206f6d2479085147f02bc2ef834ac85886624a23575ae137c8aa8156"
+dependencies = [
+ "libc",
+ "rustix",
+]
+
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33811428bee40dbceb6d545e95754741d17a6aef9a4849f0fd62e2ba4f412a78"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+ "synstructure",
+]
+
+[[package]]
+name = "zbus"
+version = "5.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5db4be7c075cb421e4b7ee645541604239bd243ba7c357511f4ff3a74b555907"
+dependencies = [
+ "async-broadcast",
+ "async-executor",
+ "async-io",
+ "async-lock",
+ "async-process",
+ "async-recursion",
+ "async-task",
+ "async-trait",
+ "blocking",
+ "enumflags2",
+ "event-listener",
+ "futures-core",
+ "futures-lite",
+ "hex",
+ "libc",
+ "ordered-stream",
+ "rustix",
+ "serde",
+ "serde_repr",
+ "tracing",
+ "uds_windows",
+ "uuid",
+ "windows-sys 0.61.2",
+ "winnow 1.0.4",
+ "zbus_macros",
+ "zbus_names",
+ "zvariant",
+]
+
+[[package]]
+name = "zbus_macros"
+version = "5.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2990635d09ade6df1868f72f8cac69a876a90981e8bd3c40b1be413f8dc88f40"
+dependencies = [
+ "proc-macro-crate 3.4.0",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+ "zbus_names",
+ "zvariant",
+ "zvariant_utils",
+]
+
+[[package]]
+name = "zbus_names"
+version = "4.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8bf88b4a3ff53e883001e0e0115b297a9d53c31b9c1edd2bfdd853e3428624e"
+dependencies = [
+ "serde",
+ "winnow 1.0.4",
+ "zvariant",
+]
+
+[[package]]
+name = "zcheapstr"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1afec51604565183aeb5c54c20aeab286120d4e4460f7f76e3e8bb8c0d99473"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+ "synstructure",
+]
+
+[[package]]
+name = "zeroize"
+version = "1.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+
+[[package]]
+name = "zerotrie"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb0464e17806c1d976d5cba29399c7f08e516e279e2ba493f63123b5fca67dd8"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34df6fc39dbd26ddc9c10e6a2984476e13acce22e64e4487636ef494369225da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "zip"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "caa8cd6af31c3b31c6631b8f483848b91589021b28fffe50adada48d4f4d2ed1"
+dependencies = [
+ "arbitrary",
+ "crc32fast",
+ "indexmap 2.14.2",
+ "memchr",
+]
+
+[[package]]
+name = "zlib-rs"
+version = "0.6.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112"
+
+[[package]]
+name = "zvariant"
+version = "5.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c1d34c27cc6cdd1f458427519dd6b8612f7b7e3f7b9a0b2355d041dda9869147"
+dependencies = [
+ "endi",
+ "enumflags2",
+ "serde",
+ "winnow 1.0.4",
+ "zcheapstr",
+ "zvariant_derive",
+ "zvariant_utils",
+]
+
+[[package]]
+name = "zvariant_derive"
+version = "5.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "864155e69b4352db0c7f374917bf45d1e0c8d17659c8b3dbf9795f3673f8c497"
+dependencies = [
+ "proc-macro-crate 3.4.0",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+ "zvariant_utils",
+]
+
+[[package]]
+name = "zvariant_utils"
+version = "4.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bad0294361a320b694a328460dc73add56c306150f5cb6bfafc44446120008a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde",
+ "syn 3.0.6",
+ "winnow 1.0.4",
+]
diff --git a/desktop/src-tauri/Cargo.toml b/desktop/src-tauri/Cargo.toml
new file mode 100644
index 00000000000..2b323a3cb3e
--- /dev/null
+++ b/desktop/src-tauri/Cargo.toml
@@ -0,0 +1,52 @@
+[package]
+name = "opencodex-desktop"
+version = "2.61.0"
+description = "OpenCodex desktop shell"
+authors = ["OpenCodex contributors"]
+license = "MIT"
+edition = "2021"
+rust-version = "1.77"
+
+[lib]
+name = "opencodex_desktop_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "=2.6.3", features = [] }
+
+[dependencies]
+reqwest = { version = "=0.12.24", default-features = false, features = ["json", "rustls-tls"] }
+serde = { version = "=1.0.219", features = ["derive"] }
+serde_json = "=1.0.140"
+uuid = { version = "=1.18.1", features = ["v4"] }
+tauri = { version = "=2.11.6", features = ["tray-icon", "image-png"] }
+tauri-utils = "=2.9.3"
+tauri-plugin-autostart = "=2.5.0"
+tauri-plugin-opener = "=2.5.3"
+tauri-plugin-process = "=2.3.0"
+tauri-plugin-shell = "=2.2.0"
+tauri-plugin-single-instance = "=2.4.0"
+tauri-plugin-updater = "=2.9.0"
+tokio = { version = "=1.45.1", features = ["sync", "time"] }
+
+# Linux only, and already in this graph: `tao` enables its own `dbus` feature by default, so
+# `libdbus-sys` is compiled for every Linux build of this shell today. Naming it here adds a
+# session-bus probe for the StatusNotifier watcher without adding a package or a system library.
+[target.'cfg(target_os = "linux")'.dependencies]
+dbus = "=0.9.12"
+
+[profile.release]
+codegen-units = 1
+lto = "thin"
+opt-level = "s"
+strip = "symbols"
+
+# Build scripts and proc macros are compiled for the host and loaded by rustc, so
+# they must keep the symbols it resolves them through. `strip = "symbols"` above
+# applies to them as well without this override, and a stripped proc-macro dylib
+# fails to load with a bare `can't find crate`, naming the macro rather than the
+# profile that removed it. `ctor-proc-macro`, pulled in by `tauri-utils`, is the
+# one this repository hits: the release build stops at `pub use ctor_proc_macro::ctor`
+# while the dev profile compiles the same graph.
+[profile.release.build-override]
+strip = false
diff --git a/desktop/src-tauri/build.rs b/desktop/src-tauri/build.rs
new file mode 100644
index 00000000000..d860e1e6a7c
--- /dev/null
+++ b/desktop/src-tauri/build.rs
@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}
diff --git a/desktop/src-tauri/capabilities/default.json b/desktop/src-tauri/capabilities/default.json
new file mode 100644
index 00000000000..622143b1fa4
--- /dev/null
+++ b/desktop/src-tauri/capabilities/default.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "Bootstrap-only shell permissions",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "core:window:allow-show",
+    "core:window:allow-hide",
+    "core:window:allow-set-title",
+    "opener:default",
+    "autostart:default"
+  ]
+}
diff --git a/desktop/src-tauri/icons/128x128.png b/desktop/src-tauri/icons/128x128.png
new file mode 100644
index 00000000000..8827b1fdc27
Binary files /dev/null and b/desktop/src-tauri/icons/128x128.png differ
diff --git a/desktop/src-tauri/icons/128x128@2x.png b/desktop/src-tauri/icons/128x128@2x.png
new file mode 100644
index 00000000000..21c507c776c
Binary files /dev/null and b/desktop/src-tauri/icons/128x128@2x.png differ
diff --git a/desktop/src-tauri/icons/32x32.png b/desktop/src-tauri/icons/32x32.png
new file mode 100644
index 00000000000..47a19b8131c
Binary files /dev/null and b/desktop/src-tauri/icons/32x32.png differ
diff --git a/desktop/src-tauri/icons/64x64.png b/desktop/src-tauri/icons/64x64.png
new file mode 100644
index 00000000000..5f7a0713c82
Binary files /dev/null and b/desktop/src-tauri/icons/64x64.png differ
diff --git a/desktop/src-tauri/icons/Square107x107Logo.png b/desktop/src-tauri/icons/Square107x107Logo.png
new file mode 100644
index 00000000000..9436cf61e1c
Binary files /dev/null and b/desktop/src-tauri/icons/Square107x107Logo.png differ
diff --git a/desktop/src-tauri/icons/Square142x142Logo.png b/desktop/src-tauri/icons/Square142x142Logo.png
new file mode 100644
index 00000000000..80d163ad59a
Binary files /dev/null and b/desktop/src-tauri/icons/Square142x142Logo.png differ
diff --git a/desktop/src-tauri/icons/Square150x150Logo.png b/desktop/src-tauri/icons/Square150x150Logo.png
new file mode 100644
index 00000000000..5148c874dcc
Binary files /dev/null and b/desktop/src-tauri/icons/Square150x150Logo.png differ
diff --git a/desktop/src-tauri/icons/Square284x284Logo.png b/desktop/src-tauri/icons/Square284x284Logo.png
new file mode 100644
index 00000000000..d4ccde8b23f
Binary files /dev/null and b/desktop/src-tauri/icons/Square284x284Logo.png differ
diff --git a/desktop/src-tauri/icons/Square30x30Logo.png b/desktop/src-tauri/icons/Square30x30Logo.png
new file mode 100644
index 00000000000..acbbb84ceb3
Binary files /dev/null and b/desktop/src-tauri/icons/Square30x30Logo.png differ
diff --git a/desktop/src-tauri/icons/Square310x310Logo.png b/desktop/src-tauri/icons/Square310x310Logo.png
new file mode 100644
index 00000000000..1b9c14d45a4
Binary files /dev/null and b/desktop/src-tauri/icons/Square310x310Logo.png differ
diff --git a/desktop/src-tauri/icons/Square44x44Logo.png b/desktop/src-tauri/icons/Square44x44Logo.png
new file mode 100644
index 00000000000..5ce2668bf23
Binary files /dev/null and b/desktop/src-tauri/icons/Square44x44Logo.png differ
diff --git a/desktop/src-tauri/icons/Square71x71Logo.png b/desktop/src-tauri/icons/Square71x71Logo.png
new file mode 100644
index 00000000000..f9a361ad932
Binary files /dev/null and b/desktop/src-tauri/icons/Square71x71Logo.png differ
diff --git a/desktop/src-tauri/icons/Square89x89Logo.png b/desktop/src-tauri/icons/Square89x89Logo.png
new file mode 100644
index 00000000000..eafa6f2087d
Binary files /dev/null and b/desktop/src-tauri/icons/Square89x89Logo.png differ
diff --git a/desktop/src-tauri/icons/StoreLogo.png b/desktop/src-tauri/icons/StoreLogo.png
new file mode 100644
index 00000000000..86218245878
Binary files /dev/null and b/desktop/src-tauri/icons/StoreLogo.png differ
diff --git a/desktop/src-tauri/icons/icon.icns b/desktop/src-tauri/icons/icon.icns
new file mode 100644
index 00000000000..12ddb09d391
Binary files /dev/null and b/desktop/src-tauri/icons/icon.icns differ
diff --git a/desktop/src-tauri/icons/icon.ico b/desktop/src-tauri/icons/icon.ico
new file mode 100644
index 00000000000..80ded4a940b
Binary files /dev/null and b/desktop/src-tauri/icons/icon.ico differ
diff --git a/desktop/src-tauri/icons/icon.png b/desktop/src-tauri/icons/icon.png
new file mode 100644
index 00000000000..5c8fa696c68
Binary files /dev/null and b/desktop/src-tauri/icons/icon.png differ
diff --git a/desktop/src-tauri/icons/icon.svg b/desktop/src-tauri/icons/icon.svg
new file mode 100644
index 00000000000..7070d673ad5
--- /dev/null
+++ b/desktop/src-tauri/icons/icon.svg
@@ -0,0 +1,43 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024" role="img" aria-label="opencodex">
+  <!--
+    The opencodex mark, as a vector. Every committed raster in this directory is this file rendered
+    at one size by desktop/scripts/generate-icons.ts, so the sizes cannot drift apart.
+
+    Where the geometry comes from. The cloud, the two braces, the four orbit arcs and the two dots
+    are traced from the alpha channel of assets/logo-light.png, upsampled 4x and thresholded at
+    alpha 110 — the outline is measured from the brand artwork, not redrawn by eye.
+
+    Why the prompt is drawn instead of traced. In that artwork the chevron and the underscore are
+    engraved: alpha 217+ against a 206 body, with a lit rim on one edge. That reads as depth at
+    512px and as nothing at all below 128px, which is where an app icon actually lives. They are
+    redrawn here as flat geometry on the measured centreline and cut out of the mark, so the
+    backdrop shows through them. The cut is what also gives the menu bar template real holes
+    instead of a black blob — see tray/icon.svg.
+
+    Why the backdrop is a full-bleed opaque square. Apple's current app icon guidance asks for a
+    square, unmasked, full-bleed source: macOS applies its own rounded-rectangle mask and material,
+    and a pre-masked corner fights that and shows as jagged edges. The transparent-cornered mark
+    this file replaces is what made Finder fall back to a default grey tile.
+  -->
+  <defs>
+    <mask id="prompt" maskUnits="userSpaceOnUse" x="0" y="0" width="512" height="512">
+      <rect x="0" y="0" width="512" height="512" fill="#ffffff"/>
+      <g fill="#000000" stroke="#000000" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M193.4 206.5 214.6 244 193.4 281.5" fill="none" stroke-width="22"/>
+        <rect x="253.5" y="271" width="71" height="22.5" rx="11.25"/>
+      </g>
+    </mask>
+  </defs>
+  <rect id="backdrop" x="0" y="0" width="1024" height="1024" fill="#fcfcfc"/>
+  <g id="mark" fill="#2c2c2c" mask="url(#prompt)" transform="translate(2 26) scale(2)">
+    <path d="M228 72.9c-3.25 0.38 -13.45 2.6 -18.88 4.1 -2.12 0.58 -10.23 3.25 -12.12 4 -0.75 0.3 -1.88 0.73 -2.48 0.93 -0.62 0.23 -1.4 0.55 -1.75 0.75 -0.38 0.18 -0.75 0.33 -0.85 0.33 -0.25 0 -0.93 0.3 -4.05 1.75 -1.1 0.53 -2.85 1.3 -3.88 1.75 -1.03 0.45 -1.98 0.9 -2.12 1 -0.12 0.1 -1.78 0.98 -3.62 1.93 -2.78 1.45 -6.1 3.33 -8.28 4.7 -0.23 0.12 -0.9 0.53 -1.48 0.88 -1.7 1 -4.05 2.55 -6.5 4.28 -0.62 0.45 -1.45 1.05 -1.88 1.33 -8.58 6 -19.12 15.48 -26.08 23.38 -1.68 1.93 -2.05 2.5 -2.05 3.18 0 1.03 0.98 2.23 2.15 2.6 1.15 0.4 1.6 0.08 4.45 -2.98 5.45 -5.85 11 -11.08 16.3 -15.33 4.65 -3.75 7.1 -5.53 12.38 -9.05 1.85 -1.23 3.62 -2.4 3.98 -2.62 0.6 -0.43 2.55 -1.6 4.45 -2.68 4.78 -2.75 11.7 -6.15 17.3 -8.47 4.9 -2.02 6.38 -2.6 10.62 -4 7.62 -2.55 16.35 -4.73 23.5 -5.88 3.88 -0.62 4.88 -1.28 4.88 -3.18 0 -2 -1.45 -2.95 -4 -2.68z"/>
+    <path d="M280.25 73.05c-0.85 0.45 -1.58 2 -1.38 2.93 0.23 1.1 1.43 2.08 2.8 2.3 7 1.15 15.43 3.05 19.58 4.42 0.48 0.18 2.45 0.8 4.38 1.43 1.93 0.62 4.53 1.55 5.75 2.02 1.25 0.5 2.65 1.05 3.12 1.23 6.4 2.5 15.75 7.18 21.83 10.95 13.8 8.55 26.78 19.78 36.35 31.48 2.85 3.5 3.65 4.2 4.8 4.2 0.95 0 2.43 -1.25 2.65 -2.23 0.23 -1.07 -0.33 -2.12 -2.62 -4.9 -7.93 -9.6 -16.85 -18.12 -27.12 -25.9 -2.62 -2 -10.25 -7.15 -12 -8.12 -0.28 -0.15 -1.4 -0.83 -2.5 -1.48 -2.8 -1.68 -10.95 -5.8 -14.53 -7.35 -1.62 -0.73 -3.2 -1.4 -3.48 -1.53 -1.95 -0.88 -10.05 -3.85 -12.25 -4.53 -3.93 -1.18 -5.2 -1.53 -7.75 -2.2 -3.1 -0.8 -7 -1.68 -8.5 -1.93 -0.55 -0.08 -1.6 -0.3 -2.33 -0.5 -2.05 -0.53 -6.05 -0.7 -6.8 -0.3z"/>
+    <path d="M112.7 321.9c-0.7 0.38 -1.45 1.53 -1.45 2.23 0 0.4 0.7 1.9 2 4.25 0.45 0.83 1.28 2.35 1.8 3.38 0.55 1.03 1.23 2.18 1.48 2.53 0.25 0.38 0.48 0.73 0.48 0.8 0 0.08 0.55 0.95 1.2 1.98 0.68 1 1.62 2.45 2.1 3.2 3.78 5.9 4.83 7.35 10.48 14.45 11.62 14.62 25.65 27.38 40.4 36.73 1.7 1.07 3.55 2.25 4.12 2.62 3.08 1.95 5.5 3.33 9.7 5.5 1.85 0.95 3.5 1.83 3.62 1.95 0.35 0.28 8.75 3.98 10.25 4.5 0.7 0.25 1.88 0.7 2.62 1 6.88 2.65 11.5 4.15 17.93 5.78 9.12 2.27 12.2 2.78 13.2 2.12 0.85 -0.55 1.43 -1.75 1.23 -2.53 -0.25 -1 -1.5 -2.08 -2.55 -2.25 -2.6 -0.38 -12.03 -2.62 -15.43 -3.68 -3.03 -0.93 -10.73 -3.48 -11.5 -3.83 -1.15 -0.5 -5.12 -2.15 -6.18 -2.53 -0.88 -0.33 -4.55 -2.02 -7.7 -3.55 -0.75 -0.38 -2.05 -1.05 -2.88 -1.53 -0.83 -0.45 -2.58 -1.4 -3.88 -2.08 -1.3 -0.7 -2.55 -1.4 -2.78 -1.6 -0.2 -0.2 -0.48 -0.35 -0.55 -0.35 -0.15 0 -1.15 -0.6 -3.93 -2.38 -7.55 -4.78 -15.18 -10.45 -21.25 -15.85 -3.43 -3.03 -12.68 -12.3 -15.43 -15.48 -4.12 -4.75 -8.1 -9.8 -10.95 -13.93 -0.68 -0.98 -1.62 -2.33 -2.1 -3 -2.68 -3.8 -6.9 -10.83 -10.15 -16.82 -1.05 -1.93 -2.4 -2.5 -3.93 -1.65z"/>
+    <path d="M393.85 326.73c-0.78 0.48 -1.18 1.03 -2.53 3.53 -1.73 3.18 -7.4 12.08 -10.15 15.88 -0.3 0.43 -1 1.38 -1.55 2.12 -4.35 6.03 -10.88 13.58 -16.8 19.45 -6.2 6.12 -14.03 12.75 -19.83 16.78 -2.7 1.88 -8.33 5.58 -9.58 6.3 -0.83 0.48 -1.78 1.03 -2.12 1.25 -5.55 3.35 -13.45 7.2 -20.3 9.88 -1.58 0.62 -3.15 1.25 -3.5 1.4 -0.83 0.35 -6.58 2.23 -9.25 3 -5.18 1.53 -4.75 1.43 -11.75 2.9 -5.25 1.1 -7.6 1.55 -8.22 1.55 -0.85 0 -2.02 1.38 -2.02 2.38 0 0.98 0.8 2.08 1.85 2.5 0.65 0.28 1.35 0.2 4.78 -0.38 6.03 -1.05 12.93 -2.62 16.8 -3.83 8 -2.5 9.03 -2.83 12.08 -4.05 0.48 -0.18 1.6 -0.62 2.5 -0.98 2.08 -0.8 8.68 -3.73 10.58 -4.67 0.8 -0.4 2.65 -1.38 4.12 -2.15 2.27 -1.18 3.5 -1.88 6.6 -3.7 3.18 -1.85 9.73 -6.2 12.83 -8.5 12.53 -9.25 25.48 -22.35 35.65 -36.05 1.6 -2.15 6.38 -9.2 8.12 -11.95 1.07 -1.73 5.45 -9.4 5.68 -9.95 0.43 -1.1 -1.28 -3.18 -2.62 -3.18 -0.3 0 -0.93 0.23 -1.35 0.48z"/>
+    <path d="M252.55 65.57c-1.6 0.7 -2.83 1.85 -3.85 3.68 -0.7 1.23 -0.8 1.6 -0.8 3.5 -0.03 1.9 0.05 2.27 0.73 3.48 0.8 1.48 2.4 3 3.8 3.65 1.38 0.65 3.75 0.78 5.3 0.25 1.88 -0.6 4.03 -2.68 4.73 -4.53 1.5 -3.85 -0.18 -8.25 -3.78 -10.05 -1.55 -0.78 -4.3 -0.75 -6.12 0.03z"/>
+    <path d="M253.23 407.07c-3.93 1.48 -6.12 6.33 -4.5 10 0.7 1.65 2.85 3.68 4.42 4.25 3.48 1.23 7.68 -0.45 9.35 -3.73 0.53 -1.05 0.62 -1.58 0.62 -3.48 0 -2 -0.08 -2.38 -0.7 -3.38 -0.98 -1.6 -1.65 -2.33 -2.88 -3.15 -0.95 -0.6 -1.38 -0.7 -3.25 -0.78 -1.4 -0.05 -2.5 0.05 -3.08 0.25z"/>
+    <path d="M99.25 145.22c-4.42 0.28 -6.1 0.73 -10.5 2.88 -6.1 2.98 -11.18 9.18 -13.18 16.15 -0.55 1.88 -0.65 2.88 -0.83 8.38 -0.12 3.43 -0.23 10.95 -0.23 16.68 -0.03 10.98 -0.18 13.08 -1.15 16.03 -1.48 4.48 -4.05 7.68 -9.4 11.6 -2.8 2.05 -3.98 3.38 -5 5.5 -1.05 2.2 -1.35 4.08 -1 6.35 0.53 3.28 2.27 5.73 6.1 8.55 5.45 4.05 8 7.08 9.4 11.15 0.48 1.38 0.58 2.43 0.75 7.38 0.1 3.18 0.15 10.68 0.12 16.65 -0.08 14.38 0.25 17.03 2.9 22.28 1.15 2.33 1.98 3.48 4.1 5.68 4.1 4.28 8.95 6.83 14.75 7.7 2.73 0.4 9.25 0.45 10.75 0.08 1.73 -0.43 3.4 -1.85 4.35 -3.7 0.7 -1.4 0.8 -1.85 0.8 -3.53 0 -3.03 -1.2 -4.98 -3.88 -6.33 -1.1 -0.55 -1.7 -0.65 -4.75 -0.78 -2.33 -0.1 -4 -0.3 -5 -0.6 -4.95 -1.53 -7.55 -4.53 -8.35 -9.55 -0.18 -0.98 -0.28 -7.48 -0.28 -16.5 0 -16.1 -0.1 -17.57 -1.43 -22.38 -0.53 -1.93 -2.1 -5.55 -3.15 -7.25 -1.88 -3.05 -4.73 -6.43 -7.28 -8.62 -1.07 -0.93 -1.88 -1.8 -1.83 -2.02 0.03 -0.2 0.85 -1.07 1.85 -1.93 1.9 -1.65 5.4 -5.75 6.9 -8.08 2.1 -3.28 3.95 -8.2 4.42 -11.73 0.15 -1.15 0.38 -2.23 0.45 -2.38 0.1 -0.12 0.25 -7.9 0.33 -17.25 0.12 -16.9 0.12 -17 0.7 -18.48 1.43 -3.78 4.35 -6.28 8.3 -7.15 0.75 -0.15 2.8 -0.38 4.58 -0.5 3.78 -0.28 5.28 -0.83 6.62 -2.5 1.3 -1.62 1.78 -2.9 1.78 -4.95 0 -1.45 -0.12 -2.05 -0.6 -3 -0.8 -1.55 -1.83 -2.62 -3.18 -3.3 -1.25 -0.65 -4.1 -0.8 -8.97 -0.53z"/>
+    <path d="M402.88 145.8c-1.48 0.75 -2.33 1.65 -3.15 3.25 -1.93 3.83 0.15 8.9 4.12 10.08 0.73 0.23 2.25 0.38 3.62 0.38 4.48 0 7.2 0.83 9.53 2.93 1.58 1.43 2.65 3 3.33 4.93 0.5 1.48 0.53 2.08 0.68 19.4 0.15 17.12 0.18 17.98 0.7 20.25 0.58 2.53 1.4 4.95 2.45 7.15 1.5 3.15 5.1 7.7 8.43 10.6 1.2 1.03 2.15 2.05 2.18 2.3 0 0.23 -0.75 1.07 -1.68 1.88 -3.35 2.95 -6.98 7.62 -8.68 11.2 -1.4 3 -2.02 4.88 -2.7 8.25 -0.48 2.3 -0.53 3.8 -0.68 19.75l-0.15 17.25 -0.73 1.5c-1.53 3.28 -3.68 5.2 -7.03 6.33 -1.38 0.48 -2.55 0.62 -5.5 0.78 -4.15 0.2 -5.03 0.48 -6.53 2.08 -1.5 1.58 -1.98 2.83 -1.95 5.2 0 2.45 0.53 3.83 1.93 5.28 1.58 1.6 2.35 1.85 6.55 1.93 6.48 0.15 10.05 -0.45 14.3 -2.45 2.55 -1.2 4.23 -2.4 6.55 -4.62 2.43 -2.33 3.88 -4.25 5.28 -7.05 2.58 -5.15 2.75 -6.78 2.75 -25.3 0 -11.7 0.08 -15.43 0.38 -17.4 0.83 -5.73 3.3 -9.25 9.98 -14.35 3.03 -2.3 4.5 -3.93 5.5 -6.03 0.7 -1.5 0.75 -1.85 0.78 -4.25 0 -4.65 -1.3 -6.75 -6.68 -10.83 -5.15 -3.9 -7.4 -6.73 -8.9 -11.05 -0.93 -2.73 -1.05 -4.93 -1.05 -18.7 -0.03 -16.25 -0.2 -20.23 -1.12 -23.18 -0.7 -2.2 -2.1 -5.33 -3 -6.62 -3.08 -4.53 -7.53 -8.18 -11.88 -9.75 -3.98 -1.45 -5.08 -1.62 -11 -1.6 -5.2 0 -5.7 0.03 -6.62 0.53z"/>
+    <path d="M233.25 106.67c-4.62 0.33 -9.55 1.15 -13.88 2.3 -6.6 1.73 -15.08 5.6 -20.43 9.28 -5.8 4 -11.78 9.5 -15.73 14.5 -1.73 2.18 -4.23 5.62 -4.23 5.83 0 0.05 -0.6 1.1 -1.35 2.33 -0.73 1.23 -1.93 3.58 -2.62 5.23 -0.73 1.65 -1.4 3.23 -1.53 3.5 -0.83 1.88 -1.33 3.28 -1.88 5.25 -0.38 1.23 -0.8 2.4 -0.98 2.58 -0.18 0.18 -0.93 0.48 -1.68 0.65 -3.55 0.9 -12.4 4.65 -14.93 6.38 -0.38 0.25 -1.68 1.1 -2.93 1.93 -8.5 5.55 -17.05 14.48 -21.78 22.7 -2.53 4.4 -2.9 5.08 -3.25 5.9 -0.23 0.48 -0.65 1.43 -0.98 2.12 -2.18 4.75 -4.4 12.1 -5.48 18.12 -1.25 7.03 -1.18 17.88 0.2 24.38 1.6 7.68 2.65 11.05 4.78 15.53 0.75 1.6 1.38 2.95 1.38 3 0 0.08 0.53 1.05 1.18 2.18 1.05 1.83 1.53 2.58 3.43 5.3 1.15 1.65 4.15 5.35 5.73 7.05 1.78 1.93 1.83 2.15 1.15 4.45 -0.1 0.4 -0.5 2.78 -0.88 5.25 -0.6 4.23 -0.65 4.93 -0.53 11.5 0.12 7.15 0.28 8.72 1.45 14.12 0.83 3.75 2.98 10.33 3.98 12.23 0.12 0.23 0.75 1.53 1.43 2.9 4.75 9.93 12.88 19.83 21.38 26.05 4.67 3.43 6.25 4.38 12.08 7.3 4.73 2.38 12.78 5 18.12 5.9 4.3 0.73 7.53 0.93 12.75 0.78 5.33 -0.12 10.28 -0.8 14.12 -1.9 0.98 -0.25 1.93 -0.48 2.12 -0.48 0.2 0 1.43 1 2.73 2.25 5.62 5.38 12.03 9.7 18.65 12.6 0.83 0.35 1.68 0.75 1.93 0.88 0.9 0.5 7.23 2.5 9.33 2.98 7.4 1.65 7.45 1.65 15.75 1.65 6.38 0 8.25 -0.08 10.62 -0.48 6.45 -1.05 12.53 -2.83 18.25 -5.35 3.4 -1.5 6.55 -3.1 7.25 -3.68 0.2 -0.15 0.95 -0.6 1.62 -1 5.03 -2.88 12.78 -9.8 17.07 -15.25 3.25 -4.12 7.2 -10.75 8.72 -14.62 0.35 -0.9 0.78 -1.98 0.98 -2.38 0.73 -1.68 1.8 -4.62 2.45 -6.68l0.68 -2.18 2.18 -0.68c4.35 -1.35 10.12 -4 14.43 -6.65 4.6 -2.83 8.08 -5.62 12.65 -10.18 4.23 -4.23 6 -6.35 8.93 -10.65 1.2 -1.73 4.3 -7 4.3 -7.25 0 -0.08 0.38 -0.9 0.85 -1.83 0.45 -0.95 0.95 -2.05 1.1 -2.45 0.15 -0.4 0.62 -1.58 1.05 -2.6 0.83 -1.93 1 -2.48 2.12 -6.5 2 -7.23 2.73 -13.35 2.55 -21.2 -0.18 -7.58 -0.98 -12.73 -3.2 -20.18 -2.73 -9.1 -8.18 -18.65 -14.83 -25.98 -2.25 -2.48 -2.27 -2.53 -1.93 -3.62 1.07 -3.58 2.08 -11.78 2.05 -17.03 -0.03 -10.28 -2.43 -20.25 -7.2 -30 -3.5 -7.15 -7.88 -13.3 -13.45 -18.88 -4.17 -4.17 -9 -7.9 -14.08 -10.85 -2.2 -1.28 -6.93 -3.62 -8.38 -4.17 -9.43 -3.53 -14.6 -4.58 -23.3 -4.78 -7.23 -0.18 -9.53 0.08 -17.65 1.8l-2.15 0.48 -1.73 -1.73c-2.15 -2.15 -6.88 -5.93 -9.35 -7.5 -1.03 -0.65 -2.15 -1.38 -2.5 -1.6 -1.03 -0.7 -6.75 -3.43 -8.62 -4.12 -0.95 -0.38 -1.93 -0.75 -2.12 -0.88 -0.2 -0.1 -1.45 -0.5 -2.75 -0.88 -1.3 -0.35 -2.88 -0.83 -3.5 -1.03 -1.95 -0.6 -7.75 -1.6 -10.88 -1.88 -2.8 -0.23 -8.28 -0.28 -10.88 -0.08z"/>
+  </g>
+</svg>
diff --git a/desktop/src-tauri/icons/tray/icon.png b/desktop/src-tauri/icons/tray/icon.png
new file mode 100644
index 00000000000..1eec4cccaf1
Binary files /dev/null and b/desktop/src-tauri/icons/tray/icon.png differ
diff --git a/desktop/src-tauri/icons/tray/icon.svg b/desktop/src-tauri/icons/tray/icon.svg
new file mode 100644
index 00000000000..1f917f1f018
--- /dev/null
+++ b/desktop/src-tauri/icons/tray/icon.svg
@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="44" height="44" viewBox="45.62 34.12 419.76 419.76" role="img" aria-label="opencodex">
+  <!--
+    The menu bar variant of icon.svg: same traced curves, same prompt cut, no backdrop.
+
+    macOS treats a status item image as a template — it reads the alpha channel as coverage and
+    paints it with the current menu bar tint, so the artwork has to be black and transparent and
+    the prompt has to be an actual hole. The orbit arcs and dots are dropped: at 22pt they resolve
+    into a ring of grey specks rather than a dashed circle. The viewBox is the ink bounds of what
+    is left, plus 6%, so the glyph fills the menu bar height instead of the source margin.
+
+    tests/ci-workflows/build-desktop-icon-set.test.ts requires every path here to appear verbatim
+    in icon.svg, so the two files cannot drift.
+  -->
+  <defs>
+    <mask id="prompt" maskUnits="userSpaceOnUse" x="0" y="0" width="512" height="512">
+      <rect x="0" y="0" width="512" height="512" fill="#ffffff"/>
+      <g fill="#000000" stroke="#000000" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M193.4 206.5 214.6 244 193.4 281.5" fill="none" stroke-width="22"/>
+        <rect x="253.5" y="271" width="71" height="22.5" rx="11.25"/>
+      </g>
+    </mask>
+  </defs>
+  <g id="mark" fill="#000000" mask="url(#prompt)">
+    <path d="M99.25 145.22c-4.42 0.28 -6.1 0.73 -10.5 2.88 -6.1 2.98 -11.18 9.18 -13.18 16.15 -0.55 1.88 -0.65 2.88 -0.83 8.38 -0.12 3.43 -0.23 10.95 -0.23 16.68 -0.03 10.98 -0.18 13.08 -1.15 16.03 -1.48 4.48 -4.05 7.68 -9.4 11.6 -2.8 2.05 -3.98 3.38 -5 5.5 -1.05 2.2 -1.35 4.08 -1 6.35 0.53 3.28 2.27 5.73 6.1 8.55 5.45 4.05 8 7.08 9.4 11.15 0.48 1.38 0.58 2.43 0.75 7.38 0.1 3.18 0.15 10.68 0.12 16.65 -0.08 14.38 0.25 17.03 2.9 22.28 1.15 2.33 1.98 3.48 4.1 5.68 4.1 4.28 8.95 6.83 14.75 7.7 2.73 0.4 9.25 0.45 10.75 0.08 1.73 -0.43 3.4 -1.85 4.35 -3.7 0.7 -1.4 0.8 -1.85 0.8 -3.53 0 -3.03 -1.2 -4.98 -3.88 -6.33 -1.1 -0.55 -1.7 -0.65 -4.75 -0.78 -2.33 -0.1 -4 -0.3 -5 -0.6 -4.95 -1.53 -7.55 -4.53 -8.35 -9.55 -0.18 -0.98 -0.28 -7.48 -0.28 -16.5 0 -16.1 -0.1 -17.57 -1.43 -22.38 -0.53 -1.93 -2.1 -5.55 -3.15 -7.25 -1.88 -3.05 -4.73 -6.43 -7.28 -8.62 -1.07 -0.93 -1.88 -1.8 -1.83 -2.02 0.03 -0.2 0.85 -1.07 1.85 -1.93 1.9 -1.65 5.4 -5.75 6.9 -8.08 2.1 -3.28 3.95 -8.2 4.42 -11.73 0.15 -1.15 0.38 -2.23 0.45 -2.38 0.1 -0.12 0.25 -7.9 0.33 -17.25 0.12 -16.9 0.12 -17 0.7 -18.48 1.43 -3.78 4.35 -6.28 8.3 -7.15 0.75 -0.15 2.8 -0.38 4.58 -0.5 3.78 -0.28 5.28 -0.83 6.62 -2.5 1.3 -1.62 1.78 -2.9 1.78 -4.95 0 -1.45 -0.12 -2.05 -0.6 -3 -0.8 -1.55 -1.83 -2.62 -3.18 -3.3 -1.25 -0.65 -4.1 -0.8 -8.97 -0.53z"/>
+    <path d="M402.88 145.8c-1.48 0.75 -2.33 1.65 -3.15 3.25 -1.93 3.83 0.15 8.9 4.12 10.08 0.73 0.23 2.25 0.38 3.62 0.38 4.48 0 7.2 0.83 9.53 2.93 1.58 1.43 2.65 3 3.33 4.93 0.5 1.48 0.53 2.08 0.68 19.4 0.15 17.12 0.18 17.98 0.7 20.25 0.58 2.53 1.4 4.95 2.45 7.15 1.5 3.15 5.1 7.7 8.43 10.6 1.2 1.03 2.15 2.05 2.18 2.3 0 0.23 -0.75 1.07 -1.68 1.88 -3.35 2.95 -6.98 7.62 -8.68 11.2 -1.4 3 -2.02 4.88 -2.7 8.25 -0.48 2.3 -0.53 3.8 -0.68 19.75l-0.15 17.25 -0.73 1.5c-1.53 3.28 -3.68 5.2 -7.03 6.33 -1.38 0.48 -2.55 0.62 -5.5 0.78 -4.15 0.2 -5.03 0.48 -6.53 2.08 -1.5 1.58 -1.98 2.83 -1.95 5.2 0 2.45 0.53 3.83 1.93 5.28 1.58 1.6 2.35 1.85 6.55 1.93 6.48 0.15 10.05 -0.45 14.3 -2.45 2.55 -1.2 4.23 -2.4 6.55 -4.62 2.43 -2.33 3.88 -4.25 5.28 -7.05 2.58 -5.15 2.75 -6.78 2.75 -25.3 0 -11.7 0.08 -15.43 0.38 -17.4 0.83 -5.73 3.3 -9.25 9.98 -14.35 3.03 -2.3 4.5 -3.93 5.5 -6.03 0.7 -1.5 0.75 -1.85 0.78 -4.25 0 -4.65 -1.3 -6.75 -6.68 -10.83 -5.15 -3.9 -7.4 -6.73 -8.9 -11.05 -0.93 -2.73 -1.05 -4.93 -1.05 -18.7 -0.03 -16.25 -0.2 -20.23 -1.12 -23.18 -0.7 -2.2 -2.1 -5.33 -3 -6.62 -3.08 -4.53 -7.53 -8.18 -11.88 -9.75 -3.98 -1.45 -5.08 -1.62 -11 -1.6 -5.2 0 -5.7 0.03 -6.62 0.53z"/>
+    <path d="M233.25 106.67c-4.62 0.33 -9.55 1.15 -13.88 2.3 -6.6 1.73 -15.08 5.6 -20.43 9.28 -5.8 4 -11.78 9.5 -15.73 14.5 -1.73 2.18 -4.23 5.62 -4.23 5.83 0 0.05 -0.6 1.1 -1.35 2.33 -0.73 1.23 -1.93 3.58 -2.62 5.23 -0.73 1.65 -1.4 3.23 -1.53 3.5 -0.83 1.88 -1.33 3.28 -1.88 5.25 -0.38 1.23 -0.8 2.4 -0.98 2.58 -0.18 0.18 -0.93 0.48 -1.68 0.65 -3.55 0.9 -12.4 4.65 -14.93 6.38 -0.38 0.25 -1.68 1.1 -2.93 1.93 -8.5 5.55 -17.05 14.48 -21.78 22.7 -2.53 4.4 -2.9 5.08 -3.25 5.9 -0.23 0.48 -0.65 1.43 -0.98 2.12 -2.18 4.75 -4.4 12.1 -5.48 18.12 -1.25 7.03 -1.18 17.88 0.2 24.38 1.6 7.68 2.65 11.05 4.78 15.53 0.75 1.6 1.38 2.95 1.38 3 0 0.08 0.53 1.05 1.18 2.18 1.05 1.83 1.53 2.58 3.43 5.3 1.15 1.65 4.15 5.35 5.73 7.05 1.78 1.93 1.83 2.15 1.15 4.45 -0.1 0.4 -0.5 2.78 -0.88 5.25 -0.6 4.23 -0.65 4.93 -0.53 11.5 0.12 7.15 0.28 8.72 1.45 14.12 0.83 3.75 2.98 10.33 3.98 12.23 0.12 0.23 0.75 1.53 1.43 2.9 4.75 9.93 12.88 19.83 21.38 26.05 4.67 3.43 6.25 4.38 12.08 7.3 4.73 2.38 12.78 5 18.12 5.9 4.3 0.73 7.53 0.93 12.75 0.78 5.33 -0.12 10.28 -0.8 14.12 -1.9 0.98 -0.25 1.93 -0.48 2.12 -0.48 0.2 0 1.43 1 2.73 2.25 5.62 5.38 12.03 9.7 18.65 12.6 0.83 0.35 1.68 0.75 1.93 0.88 0.9 0.5 7.23 2.5 9.33 2.98 7.4 1.65 7.45 1.65 15.75 1.65 6.38 0 8.25 -0.08 10.62 -0.48 6.45 -1.05 12.53 -2.83 18.25 -5.35 3.4 -1.5 6.55 -3.1 7.25 -3.68 0.2 -0.15 0.95 -0.6 1.62 -1 5.03 -2.88 12.78 -9.8 17.07 -15.25 3.25 -4.12 7.2 -10.75 8.72 -14.62 0.35 -0.9 0.78 -1.98 0.98 -2.38 0.73 -1.68 1.8 -4.62 2.45 -6.68l0.68 -2.18 2.18 -0.68c4.35 -1.35 10.12 -4 14.43 -6.65 4.6 -2.83 8.08 -5.62 12.65 -10.18 4.23 -4.23 6 -6.35 8.93 -10.65 1.2 -1.73 4.3 -7 4.3 -7.25 0 -0.08 0.38 -0.9 0.85 -1.83 0.45 -0.95 0.95 -2.05 1.1 -2.45 0.15 -0.4 0.62 -1.58 1.05 -2.6 0.83 -1.93 1 -2.48 2.12 -6.5 2 -7.23 2.73 -13.35 2.55 -21.2 -0.18 -7.58 -0.98 -12.73 -3.2 -20.18 -2.73 -9.1 -8.18 -18.65 -14.83 -25.98 -2.25 -2.48 -2.27 -2.53 -1.93 -3.62 1.07 -3.58 2.08 -11.78 2.05 -17.03 -0.03 -10.28 -2.43 -20.25 -7.2 -30 -3.5 -7.15 -7.88 -13.3 -13.45 -18.88 -4.17 -4.17 -9 -7.9 -14.08 -10.85 -2.2 -1.28 -6.93 -3.62 -8.38 -4.17 -9.43 -3.53 -14.6 -4.58 -23.3 -4.78 -7.23 -0.18 -9.53 0.08 -17.65 1.8l-2.15 0.48 -1.73 -1.73c-2.15 -2.15 -6.88 -5.93 -9.35 -7.5 -1.03 -0.65 -2.15 -1.38 -2.5 -1.6 -1.03 -0.7 -6.75 -3.43 -8.62 -4.12 -0.95 -0.38 -1.93 -0.75 -2.12 -0.88 -0.2 -0.1 -1.45 -0.5 -2.75 -0.88 -1.3 -0.35 -2.88 -0.83 -3.5 -1.03 -1.95 -0.6 -7.75 -1.6 -10.88 -1.88 -2.8 -0.23 -8.28 -0.28 -10.88 -0.08z"/>
+  </g>
+</svg>
diff --git a/desktop/src-tauri/src/auth.rs b/desktop/src-tauri/src/auth.rs
new file mode 100644
index 00000000000..81a16467b05
--- /dev/null
+++ b/desktop/src-tauri/src/auth.rs
@@ -0,0 +1,31 @@
+use std::path::PathBuf;
+
+#[derive(Clone, Debug)]
+pub struct Auth {
+    home: PathBuf,
+    environment_token: Option<String>,
+}
+
+impl Auth {
+    pub fn new(home: PathBuf) -> Self {
+        Self {
+            home,
+            environment_token: std::env::var("OPENCODEX_ADMIN_AUTH_TOKEN")
+                .ok()
+                .filter(|value| !value.is_empty()),
+        }
+    }
+
+    pub fn token(&self) -> Option<String> {
+        self.environment_token.clone().or_else(|| {
+            std::fs::read_to_string(self.home.join("admin-api-token"))
+                .ok()
+                .map(|value| value.trim().to_owned())
+                .filter(|value| !value.is_empty())
+        })
+    }
+
+    pub fn user_agent() -> &'static str {
+        concat!("OpenCodexDesktop/", env!("CARGO_PKG_VERSION"))
+    }
+}
diff --git a/desktop/src-tauri/src/endpoint.rs b/desktop/src-tauri/src/endpoint.rs
new file mode 100644
index 00000000000..09a78e22fb7
--- /dev/null
+++ b/desktop/src-tauri/src/endpoint.rs
@@ -0,0 +1,33 @@
+//! The loopback endpoint the shell talks to.
+//!
+//! This file was `discovery.rs`, and it resolved the endpoint itself: it read `runtime-port.json`,
+//! fell back to 10100 and let the shell start there, so a user with a configured `config.port` was
+//! started on a port they had not chosen. Resolution belongs to the bundled CLI now — see
+//! `resolve.rs` — and what is left here is the value it hands back.
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ProxyEndpoint {
+    pub host: &'static str,
+    pub port: u16,
+}
+
+impl ProxyEndpoint {
+    pub fn url(&self, path: &str) -> String {
+        format!("http://{}:{}{}", self.host, self.port, path)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::ProxyEndpoint;
+
+    #[test]
+    fn the_endpoint_is_loopback_and_carries_its_port() {
+        let endpoint = ProxyEndpoint {
+            host: "127.0.0.1",
+            port: 12345,
+        };
+        assert_eq!(endpoint.url("/healthz"), "http://127.0.0.1:12345/healthz");
+        assert_eq!(endpoint.url(""), "http://127.0.0.1:12345");
+    }
+}
diff --git a/desktop/src-tauri/src/exit.rs b/desktop/src-tauri/src/exit.rs
new file mode 100644
index 00000000000..aba0aab4b39
--- /dev/null
+++ b/desktop/src-tauri/src/exit.rs
@@ -0,0 +1,756 @@
+//! Who is allowed to end the process, and what has to happen first.
+//!
+//! Three gestures arrive looking like an exit: closing the window, the platform's own quit gesture
+//! (Cmd+Q on macOS, Alt+F4 on Windows, the window manager's close on Linux), and the tray's Quit
+//! item. Only the last one means "end the runtime". Until this module existed the shell had no
+//! `ExitRequested` handler, so the quit gesture went straight to `RunEvent::Exit`, which called
+//! `CommandChild::kill()` — a SIGKILL on Unix — on a keystroke the user reads as "hide".
+//!
+//! Tauri separates a user gesture from a programmatic exit: `RunEvent::ExitRequested` carries
+//! `code: None` for the gesture and `Some(_)` for `AppHandle::exit` or `AppHandle::restart`. What
+//! it cannot tell apart is the tray's Quit from an update's restart, and those end differently.
+//! [`ExitReason`] records which one asked. macOS needs one more thing on top, because its menu Quit
+//! never raises the event at all; see [`crate::menu`].
+//!
+//! Everything that stops the runtime funnels through one phase here — the tray's Quit, the tray's
+//! Stop, an update, and a window close on a session with no tray. Two of them running at once is
+//! two stops racing over one child, so a second one waits rather than starting its own.
+//!
+//! A drain that does not complete is **not** recorded as a drain. A quit may still proceed on one,
+//! because refusing to close is the worse answer and a standing runtime is recoverable. A restart
+//! may not: coming back onto a runtime that was never stopped puts the user on the old version
+//! while they believe they are on the new one.
+
+use crate::{
+    proxy::ProxyClient, runtime_stop, sidecar, tray_availability::TrayAvailability, window,
+    AppState,
+};
+use std::sync::{Mutex, MutexGuard, PoisonError};
+use tauri::{AppHandle, ExitRequestApi, Manager};
+use tokio::time::Instant;
+
+/// Why the process has been asked to end.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ExitReason {
+    /// The tray's Quit item, or a window close on a session with no tray to hide into.
+    UserQuit,
+    /// An installed update restarting the app. It drains exactly as a quit does and then comes
+    /// back, which is why it is a coordinated restart rather than an exception to the quit rule.
+    CoordinatedRestart,
+}
+
+/// How far the one drain sequence has got.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ExitPhase {
+    /// Nothing is in flight.
+    Idle,
+    /// A runtime is being started. An exit arriving now is held until the child exists and is
+    /// recorded, because the alternative is a process nobody owns and nobody will stop.
+    Spawning,
+    /// The runtime is being stopped without ending the app: the tray's Stop.
+    Stopping,
+    /// The drain that ends the app is running.
+    Draining,
+    /// The runtime this app owned is confirmed stopped, or was never ours to stop.
+    Drained,
+    /// The stop was refused, or the runtime still answered after the deadline.
+    DrainFailed,
+    /// Who owns the runtime could not be established, so nothing was stopped and nothing may be
+    /// replaced on the assumption that it was.
+    OwnershipUnknown,
+}
+
+/// What the event loop should do with an exit request.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ExitDecision {
+    /// Nothing asked the app to end and there is a tray to come back from: hide instead.
+    Hide,
+    /// Hold the exit and drain for this reason; the exit is requested again when the drain reports.
+    Drain(ExitReason),
+    /// Something else is already draining. Hold the exit and let that one finish.
+    Wait,
+    /// The drain has reported success. Let the process end.
+    Proceed,
+    /// The drain did not complete, and this reason is one that may not proceed on that.
+    Refuse,
+}
+
+/// What a drain established.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum DrainVerdict {
+    /// The runtime this app owned is gone, or there was never one of ours to stop.
+    Drained,
+    /// The stop was refused, or the endpoint still answered after the deadline.
+    Failed,
+    /// The process answering could not be identified, so nothing was stopped.
+    OwnershipUnknown,
+}
+
+/// Whether an update may start replacing files.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum RestartReadiness {
+    /// The runtime is confirmed stopped. The install may proceed.
+    Ready,
+    /// The drain did not complete, so the install must not start.
+    DrainFailed,
+    /// Who owns the runtime could not be established.
+    OwnershipUnknown,
+    /// Something else is already ending or stopping the runtime.
+    Busy,
+}
+
+impl RestartReadiness {
+    pub fn describe(self) -> &'static str {
+        match self {
+            Self::Ready => "the runtime is stopped",
+            Self::DrainFailed => "the runtime did not stop",
+            Self::OwnershipUnknown => "the running proxy could not be identified",
+            Self::Busy => "the app is already stopping its runtime",
+        }
+    }
+}
+
+/// Decide what an exit request means.
+///
+/// `reason` is what the app itself asked for and is `None` for a bare user gesture.
+/// `hides_to_tray` is D6: on a session with no usable tray there is nowhere to hide, so a close is
+/// a quit and takes the same graceful drain rather than leaving a running process unreachable.
+pub fn decide(phase: ExitPhase, reason: Option<ExitReason>, hides_to_tray: bool) -> ExitDecision {
+    match phase {
+        ExitPhase::Spawning | ExitPhase::Stopping | ExitPhase::Draining => ExitDecision::Wait,
+        ExitPhase::Drained => ExitDecision::Proceed,
+        // A quit that could not drain still closes the app: refusing to close is the worse answer
+        // and the runtime is recoverable. A restart is a different judgement — it would come back
+        // attached to a runtime that was never stopped, under a user who believes they upgraded.
+        ExitPhase::DrainFailed | ExitPhase::OwnershipUnknown => match reason {
+            Some(ExitReason::CoordinatedRestart) => ExitDecision::Refuse,
+            _ => ExitDecision::Proceed,
+        },
+        ExitPhase::Idle => match reason {
+            Some(reason) => ExitDecision::Drain(reason),
+            None if hides_to_tray => ExitDecision::Hide,
+            None => ExitDecision::Drain(ExitReason::UserQuit),
+        },
+    }
+}
+
+struct Inner {
+    phase: ExitPhase,
+    reason: Option<ExitReason>,
+    hides_to_tray: bool,
+    /// An exit that arrived while a runtime was being started or stopped, and still has to happen.
+    deferred: bool,
+}
+
+/// The exit sequence's state, managed by the app.
+pub struct ExitCoordinator {
+    inner: Mutex<Inner>,
+}
+
+impl ExitCoordinator {
+    pub fn new() -> Self {
+        Self {
+            inner: Mutex::new(Inner {
+                phase: ExitPhase::Idle,
+                reason: None,
+                // Until the probe answers, assume only what the platform guarantees. Assuming a
+                // tray that turns out not to exist is the exact failure D6 is about.
+                hides_to_tray: TrayAvailability::assumed().hides_to_tray(),
+                deferred: false,
+            }),
+        }
+    }
+
+    fn inner(&self) -> MutexGuard<'_, Inner> {
+        self.inner.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Record the session's tray verdict once the probe has answered and an icon exists.
+    pub fn set_tray(&self, tray: TrayAvailability) {
+        self.inner().hides_to_tray = tray.hides_to_tray();
+    }
+
+    pub fn decision(&self) -> ExitDecision {
+        let inner = self.inner();
+        decide(inner.phase, inner.reason, inner.hides_to_tray)
+    }
+
+    /// Record why the app is ending, without starting anything. The first reason wins.
+    pub fn claim(&self, reason: ExitReason) {
+        let mut inner = self.inner();
+        inner.reason.get_or_insert(reason);
+    }
+
+    /// Take ownership of the drain, and with it the reason the app is ending.
+    ///
+    /// Claiming the reason and moving out of `Idle` is one step on purpose. Split apart, a Quit
+    /// that claimed first could still be overtaken by an update that started the drain, and the app
+    /// would restart under a user who asked it to stop. `fallback` is only used when nothing has
+    /// claimed a reason yet.
+    ///
+    /// While a runtime is being started or stopped the answer is "not yet": the reason is recorded
+    /// and the drain is handed to whichever of [`ExitCoordinator::finish_spawn`] or
+    /// [`ExitCoordinator::finish_stop`] is holding the phase.
+    pub fn claim_drain(&self, fallback: ExitReason) -> Option<ExitReason> {
+        let mut inner = self.inner();
+        match inner.phase {
+            ExitPhase::Idle => {
+                let reason = *inner.reason.get_or_insert(fallback);
+                inner.phase = ExitPhase::Draining;
+                Some(reason)
+            }
+            ExitPhase::Spawning | ExitPhase::Stopping => {
+                inner.reason.get_or_insert(fallback);
+                inner.deferred = true;
+                None
+            }
+            // A failed drain is a terminal failure, not work in flight, and retrying it is the
+            // recovery: the update stayed pending, so the next attempt runs the stop again. Without
+            // this the first refusal would be permanent until the app was restarted by hand — which
+            // is the one thing a user with a runtime that would not stop cannot easily do.
+            ExitPhase::DrainFailed | ExitPhase::OwnershipUnknown => {
+                let reason = *inner.reason.get_or_insert(fallback);
+                inner.phase = ExitPhase::Draining;
+                Some(reason)
+            }
+            ExitPhase::Draining | ExitPhase::Drained => None,
+        }
+    }
+
+    /// Record what the drain established. A failure is not a drain.
+    pub fn finish_drain(&self, verdict: DrainVerdict) {
+        self.inner().phase = match verdict {
+            DrainVerdict::Drained => ExitPhase::Drained,
+            DrainVerdict::Failed => ExitPhase::DrainFailed,
+            DrainVerdict::OwnershipUnknown => ExitPhase::OwnershipUnknown,
+        };
+    }
+
+    /// Reserve the right to start a runtime. False once something else owns the phase.
+    ///
+    /// The reservation exists instead of holding the lock across the spawn. Holding it would make
+    /// the main thread's exit handler wait on process creation, so a wedged spawn would be a Quit
+    /// that never responds. An exit arriving in between is deferred rather than lost — which is the
+    /// thing that must not happen, because a quit that reads "we own nothing" leaves the child it
+    /// just missed running forever.
+    pub fn begin_spawn(&self) -> bool {
+        self.begin(ExitPhase::Spawning)
+    }
+
+    /// Release the spawn reservation, handing back a reason that arrived meanwhile.
+    pub fn finish_spawn(&self) -> Option<ExitReason> {
+        self.finish(ExitPhase::Spawning)
+    }
+
+    /// Reserve the runtime for a stop that does not end the app.
+    pub fn begin_stop(&self) -> bool {
+        self.begin(ExitPhase::Stopping)
+    }
+
+    /// Release the stop, handing back a reason that arrived meanwhile.
+    pub fn finish_stop(&self) -> Option<ExitReason> {
+        self.finish(ExitPhase::Stopping)
+    }
+
+    fn begin(&self, phase: ExitPhase) -> bool {
+        let mut inner = self.inner();
+        if inner.phase != ExitPhase::Idle {
+            return false;
+        }
+        inner.phase = phase;
+        true
+    }
+
+    fn finish(&self, phase: ExitPhase) -> Option<ExitReason> {
+        let mut inner = self.inner();
+        if inner.phase != phase {
+            return None;
+        }
+        if inner.deferred {
+            let reason = *inner.reason.get_or_insert(ExitReason::UserQuit);
+            inner.phase = ExitPhase::Draining;
+            inner.deferred = false;
+            return Some(reason);
+        }
+        inner.phase = ExitPhase::Idle;
+        None
+    }
+
+    #[cfg(test)]
+    fn phase(&self) -> ExitPhase {
+        self.inner().phase
+    }
+
+    #[cfg(test)]
+    fn hides_to_tray(&self) -> bool {
+        self.inner().hides_to_tray
+    }
+}
+
+impl Default for ExitCoordinator {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// The platform's quit gesture, and what closing the window means.
+///
+/// It is not a request to end. D2 makes it mean the same thing on all three platforms: hide where
+/// there is a tray to come back from, and a graceful quit where there is not. Closing the window
+/// arrives here too: one decision point, so the two gestures cannot drift apart.
+pub fn gesture(app: &AppHandle) {
+    let Some(coordinator) = app.try_state::<ExitCoordinator>() else {
+        return;
+    };
+    match coordinator.decision() {
+        ExitDecision::Hide => hide_windows(app),
+        ExitDecision::Drain(reason) => start_drain(app, reason),
+        ExitDecision::Wait | ExitDecision::Proceed | ExitDecision::Refuse => {}
+    }
+}
+
+/// Ask the app to end for a stated reason. This is the only way the shell ends itself.
+pub fn request(app: &AppHandle, reason: ExitReason) {
+    if let Some(coordinator) = app.try_state::<ExitCoordinator>() {
+        coordinator.claim(reason);
+    }
+    app.exit(0);
+}
+
+/// Stop the runtime without ending the app: the tray's Stop item.
+///
+/// It takes the same phase the quit path takes, so pressing Stop twice, or Stop and then Quit, or
+/// Stop during an update, is one execution rather than two racing over one child. Unlike a quit it
+/// returns the coordinator to idle, because the app is still running and may start a runtime again.
+pub fn request_stop(app: &AppHandle) {
+    let app = app.clone();
+    tauri::async_runtime::spawn(async move {
+        let Some(claimed) = app
+            .try_state::<ExitCoordinator>()
+            .map(|coordinator| coordinator.begin_stop())
+        else {
+            return;
+        };
+        if !claimed {
+            return;
+        }
+        let verdict = drain_current(&app).await;
+        if verdict == DrainVerdict::Drained {
+            if let Some(state) = app.try_state::<AppState>() {
+                state.release();
+            }
+            crate::tray::set_owned(&app, false);
+        } else {
+            crate::logging::log_once("the runtime could not be stopped", verdict.describe());
+        }
+        let deferred = app
+            .try_state::<ExitCoordinator>()
+            .and_then(|coordinator| coordinator.finish_stop());
+        if let Some(reason) = deferred {
+            drain_now(&app, reason);
+        }
+    });
+}
+
+impl DrainVerdict {
+    pub fn describe(self) -> &'static str {
+        match self {
+            Self::Drained => "the runtime is stopped",
+            Self::Failed => "the stop was refused or the runtime still answered",
+            Self::OwnershipUnknown => "the running proxy could not be identified",
+        }
+    }
+}
+
+/// Handle `RunEvent::ExitRequested`.
+pub fn on_exit_requested(app: &AppHandle, code: Option<i32>, api: &ExitRequestApi) {
+    // `AppHandle::restart` documents that `prevent_exit` is ignored for its own exit code, so a
+    // restart cannot be held here even to drain. The update path therefore drains before it
+    // restarts, and this branch only records the reason so nothing reads the restart as a quit.
+    if code == Some(tauri::RESTART_EXIT_CODE) {
+        if let Some(coordinator) = app.try_state::<ExitCoordinator>() {
+            coordinator.claim(ExitReason::CoordinatedRestart);
+        }
+        return;
+    }
+    let Some(coordinator) = app.try_state::<ExitCoordinator>() else {
+        return;
+    };
+    match coordinator.decision() {
+        ExitDecision::Hide => {
+            api.prevent_exit();
+            hide_windows(app);
+        }
+        ExitDecision::Wait => api.prevent_exit(),
+        ExitDecision::Refuse => api.prevent_exit(),
+        ExitDecision::Drain(reason) => {
+            api.prevent_exit();
+            start_drain(app, reason);
+        }
+        ExitDecision::Proceed => {}
+    }
+}
+
+/// Drain and then ask to end again.
+pub fn start_drain(app: &AppHandle, reason: ExitReason) {
+    let Some(coordinator) = app.try_state::<ExitCoordinator>() else {
+        return;
+    };
+    let Some(reason) = coordinator.claim_drain(reason) else {
+        return;
+    };
+    drain_now(app, reason);
+}
+
+/// Run the drain for a reason the coordinator has already moved to draining for.
+pub fn drain_now(app: &AppHandle, reason: ExitReason) {
+    let app = app.clone();
+    tauri::async_runtime::spawn(async move {
+        finish_and_exit_after(&app, reason).await;
+    });
+}
+
+async fn finish_and_exit_after(app: &AppHandle, reason: ExitReason) {
+    let verdict = drain_current(app).await;
+    if let Some(coordinator) = app.try_state::<ExitCoordinator>() {
+        coordinator.finish_drain(verdict);
+    }
+    match (reason, verdict) {
+        (ExitReason::UserQuit, _) => app.exit(0),
+        (ExitReason::CoordinatedRestart, DrainVerdict::Drained) => {
+            app.restart();
+        }
+        (ExitReason::CoordinatedRestart, _) => {
+            crate::logging::log_once("the update restart was refused", verdict.describe());
+        }
+    }
+}
+
+/// Prepare for an update's restart: confirm ownership, drain, and confirm the child is gone.
+///
+/// This is awaited rather than fired and forgotten, because the pinned updater's Windows install
+/// ends the process itself. A restart asked for after `install` returns is a restart that never
+/// happens there, so the stop has to be finished before the installer is started at all.
+pub async fn prepare_restart(app: &AppHandle) -> RestartReadiness {
+    let Some(reason) = app
+        .try_state::<ExitCoordinator>()
+        .and_then(|coordinator| coordinator.claim_drain(ExitReason::CoordinatedRestart))
+    else {
+        return RestartReadiness::Busy;
+    };
+    if reason != ExitReason::CoordinatedRestart {
+        // A quit claimed the exit first. It owns the drain now, and the update does not install
+        // into an app that is on its way out.
+        drain_now(app, reason);
+        return RestartReadiness::Busy;
+    }
+    let verdict = drain_current(app).await;
+    if let Some(coordinator) = app.try_state::<ExitCoordinator>() {
+        coordinator.finish_drain(verdict);
+    }
+    match verdict {
+        DrainVerdict::Drained => RestartReadiness::Ready,
+        DrainVerdict::Failed => RestartReadiness::DrainFailed,
+        DrainVerdict::OwnershipUnknown => RestartReadiness::OwnershipUnknown,
+    }
+}
+
+/// Come back, once the installer has finished and returned.
+pub fn complete_restart(app: &AppHandle) -> ! {
+    app.restart()
+}
+
+/// Stop the runtime this app owns and confirm it is gone.
+///
+/// Ownership is re-established here rather than read off a flag. A flag set when the child was
+/// spawned says nothing about the process answering the endpoint now: the child can have exited and
+/// a service can have taken the port back. Sending an owner's stop to that listener is sending it
+/// to somebody else's runtime, so the pid is checked first and a listener that cannot be identified
+/// is left alone.
+///
+/// The stop itself is the bundled `ocx stop` (D4), not a management call from inside this process.
+/// The CLI's stop owns the receipt-backed teardown, the drain, the Windows respawn verification and
+/// the client-configuration restore, and an in-process endpoint cannot own its own teardown: launchd
+/// and systemd can terminate the request handler during self-unload. Nothing kills the child either
+/// — the original path did, with `CommandChild::kill()`, a SIGKILL on Unix that cut off exactly the
+/// work the CLI's stop exists to finish.
+pub async fn drain_current(app: &AppHandle) -> DrainVerdict {
+    let Some((proxy, child_pid, watch)) = app
+        .try_state::<AppState>()
+        .map(|state| (state.proxy(), state.child_pid(), state.watch.clone()))
+    else {
+        return DrainVerdict::OwnershipUnknown;
+    };
+    let Some(proxy) = proxy else {
+        // Nothing resolved, so there is nothing of ours listening anywhere.
+        return DrainVerdict::Drained;
+    };
+    let Some(child_pid) = child_pid else {
+        // This app never started a runtime, so it does not stop one.
+        return DrainVerdict::Drained;
+    };
+    match confirm(&proxy, child_pid, &watch).await {
+        Ownership::Gone => DrainVerdict::Drained,
+        Ownership::Foreign => DrainVerdict::Drained,
+        Ownership::Unknown => DrainVerdict::OwnershipUnknown,
+        Ownership::Ours => {
+            let deadline = Instant::now() + runtime_stop::DEADLINE;
+            let result = runtime_stop::run(app, deadline).await;
+            if result.is_stopped() {
+                DrainVerdict::Drained
+            } else {
+                // The CLI's own outcome and exit code, carried rather than reinterpreted. A stop
+                // that did not end in exit 0 with the runtime down is a stop that did not happen.
+                crate::logging::log_once("the bundled stop did not complete", &result.describe());
+                DrainVerdict::Failed
+            }
+        }
+    }
+}
+
+enum Ownership {
+    /// The process answering is the child this app started.
+    Ours,
+    /// Something else holds the port.
+    Foreign,
+    /// Nothing is listening, and the child has reported its own exit.
+    Gone,
+    /// The listener could not be identified.
+    Unknown,
+}
+
+async fn confirm(proxy: &ProxyClient, child_pid: u32, watch: &sidecar::SidecarWatch) -> Ownership {
+    match proxy.identify().await {
+        Ok(identity) if identity.pid == child_pid => Ownership::Ours,
+        Ok(_) => Ownership::Foreign,
+        Err(error) if error.is_unreachable() => {
+            // Nothing is listening. That is only proof the child is gone if the child said so.
+            if watch.exit().is_some() {
+                Ownership::Gone
+            } else {
+                Ownership::Unknown
+            }
+        }
+        Err(_) => Ownership::Unknown,
+    }
+}
+
+fn hide_windows(app: &AppHandle) {
+    for window in app.webview_windows().values() {
+        window::hide(window);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        decide, DrainVerdict, ExitCoordinator, ExitDecision, ExitPhase, ExitReason,
+        RestartReadiness,
+    };
+    use crate::tray_availability::TrayAvailability;
+
+    #[test]
+    fn a_bare_gesture_hides_when_there_is_a_tray_to_come_back_from() {
+        assert_eq!(decide(ExitPhase::Idle, None, true), ExitDecision::Hide);
+    }
+
+    #[test]
+    fn a_bare_gesture_quits_through_the_drain_when_there_is_no_tray() {
+        assert_eq!(
+            decide(ExitPhase::Idle, None, false),
+            ExitDecision::Drain(ExitReason::UserQuit)
+        );
+    }
+
+    #[test]
+    fn an_explicit_quit_drains_even_though_a_tray_exists() {
+        assert_eq!(
+            decide(ExitPhase::Idle, Some(ExitReason::UserQuit), true),
+            ExitDecision::Drain(ExitReason::UserQuit)
+        );
+    }
+
+    #[test]
+    fn every_in_flight_phase_holds_the_exit() {
+        for phase in [
+            ExitPhase::Spawning,
+            ExitPhase::Stopping,
+            ExitPhase::Draining,
+        ] {
+            assert_eq!(
+                decide(phase, Some(ExitReason::UserQuit), true),
+                ExitDecision::Wait
+            );
+            assert_eq!(decide(phase, None, false), ExitDecision::Wait);
+        }
+    }
+
+    #[test]
+    fn only_a_reported_drain_lets_the_process_end() {
+        assert_eq!(
+            decide(ExitPhase::Drained, Some(ExitReason::UserQuit), true),
+            ExitDecision::Proceed
+        );
+    }
+
+    #[test]
+    fn a_quit_tolerates_a_failed_drain_and_a_restart_refuses_it() {
+        for phase in [ExitPhase::DrainFailed, ExitPhase::OwnershipUnknown] {
+            assert_eq!(
+                decide(phase, Some(ExitReason::UserQuit), true),
+                ExitDecision::Proceed
+            );
+            assert_eq!(
+                decide(phase, Some(ExitReason::CoordinatedRestart), true),
+                ExitDecision::Refuse
+            );
+        }
+    }
+
+    #[test]
+    fn a_failed_drain_is_not_recorded_as_a_drain() {
+        let coordinator = ExitCoordinator::new();
+        coordinator.claim_drain(ExitReason::CoordinatedRestart);
+        coordinator.finish_drain(DrainVerdict::Failed);
+        assert_eq!(coordinator.phase(), ExitPhase::DrainFailed);
+        // The restart that asked for it does not get to proceed on that.
+        assert_eq!(coordinator.decision(), ExitDecision::Refuse);
+    }
+
+    #[test]
+    fn an_unidentified_runtime_is_its_own_state() {
+        let coordinator = ExitCoordinator::new();
+        coordinator.claim_drain(ExitReason::CoordinatedRestart);
+        coordinator.finish_drain(DrainVerdict::OwnershipUnknown);
+        assert_eq!(coordinator.phase(), ExitPhase::OwnershipUnknown);
+        assert_eq!(coordinator.decision(), ExitDecision::Refuse);
+    }
+
+    #[test]
+    fn a_refused_restart_can_be_tried_again() {
+        let coordinator = ExitCoordinator::new();
+        coordinator.claim_drain(ExitReason::CoordinatedRestart);
+        coordinator.finish_drain(DrainVerdict::Failed);
+        // The update stayed pending, so pressing Install again runs the stop again rather than
+        // finding the app permanently unable to try.
+        assert_eq!(
+            coordinator.claim_drain(ExitReason::CoordinatedRestart),
+            Some(ExitReason::CoordinatedRestart)
+        );
+        assert_eq!(coordinator.phase(), ExitPhase::Draining);
+        coordinator.finish_drain(DrainVerdict::Drained);
+        assert_eq!(coordinator.decision(), ExitDecision::Proceed);
+    }
+
+    #[test]
+    fn a_successful_drain_is_not_re_entered() {
+        let coordinator = ExitCoordinator::new();
+        coordinator.claim_drain(ExitReason::UserQuit);
+        coordinator.finish_drain(DrainVerdict::Drained);
+        assert_eq!(coordinator.claim_drain(ExitReason::UserQuit), None);
+    }
+
+    #[test]
+    fn the_first_claimed_reason_wins_the_drain() {
+        let coordinator = ExitCoordinator::new();
+        coordinator.claim(ExitReason::UserQuit);
+        assert_eq!(
+            coordinator.claim_drain(ExitReason::CoordinatedRestart),
+            Some(ExitReason::UserQuit)
+        );
+        assert_eq!(coordinator.phase(), ExitPhase::Draining);
+    }
+
+    #[test]
+    fn only_one_caller_owns_the_drain() {
+        let coordinator = ExitCoordinator::new();
+        assert_eq!(
+            coordinator.claim_drain(ExitReason::UserQuit),
+            Some(ExitReason::UserQuit)
+        );
+        assert_eq!(coordinator.claim_drain(ExitReason::UserQuit), None);
+        coordinator.finish_drain(DrainVerdict::Drained);
+        assert_eq!(coordinator.phase(), ExitPhase::Drained);
+        assert_eq!(coordinator.claim_drain(ExitReason::UserQuit), None);
+    }
+
+    #[test]
+    fn a_stop_and_a_spawn_both_hold_the_runtime_alone() {
+        for begin in [ExitPhase::Spawning, ExitPhase::Stopping] {
+            let coordinator = ExitCoordinator::new();
+            let started = match begin {
+                ExitPhase::Spawning => coordinator.begin_spawn(),
+                _ => coordinator.begin_stop(),
+            };
+            assert!(started);
+            assert!(!coordinator.begin_spawn());
+            assert!(!coordinator.begin_stop());
+            assert_eq!(coordinator.decision(), ExitDecision::Wait);
+        }
+    }
+
+    #[test]
+    fn a_quit_during_a_stop_is_deferred_rather_than_lost() {
+        let coordinator = ExitCoordinator::new();
+        assert!(coordinator.begin_stop());
+        assert_eq!(coordinator.claim_drain(ExitReason::UserQuit), None);
+        assert_eq!(coordinator.phase(), ExitPhase::Stopping);
+        assert_eq!(coordinator.finish_stop(), Some(ExitReason::UserQuit));
+        assert_eq!(coordinator.phase(), ExitPhase::Draining);
+        assert_eq!(coordinator.finish_stop(), None);
+    }
+
+    #[test]
+    fn a_quit_during_a_spawn_is_deferred_rather_than_lost() {
+        let coordinator = ExitCoordinator::new();
+        assert!(coordinator.begin_spawn());
+        assert_eq!(coordinator.decision(), ExitDecision::Wait);
+        assert_eq!(coordinator.claim_drain(ExitReason::UserQuit), None);
+        assert_eq!(coordinator.finish_spawn(), Some(ExitReason::UserQuit));
+        assert_eq!(coordinator.phase(), ExitPhase::Draining);
+    }
+
+    #[test]
+    fn a_deferred_update_restart_keeps_its_own_reason() {
+        let coordinator = ExitCoordinator::new();
+        assert!(coordinator.begin_spawn());
+        assert_eq!(
+            coordinator.claim_drain(ExitReason::CoordinatedRestart),
+            None
+        );
+        assert_eq!(
+            coordinator.finish_spawn(),
+            Some(ExitReason::CoordinatedRestart)
+        );
+    }
+
+    #[test]
+    fn an_undrained_runtime_is_never_reported_as_ready_to_install_over() {
+        assert_eq!(RestartReadiness::Ready.describe(), "the runtime is stopped");
+        for refused in [
+            RestartReadiness::DrainFailed,
+            RestartReadiness::OwnershipUnknown,
+            RestartReadiness::Busy,
+        ] {
+            assert_ne!(refused, RestartReadiness::Ready);
+            assert!(!refused.describe().is_empty());
+        }
+    }
+
+    #[test]
+    fn the_tray_verdict_replaces_the_platform_assumption() {
+        let coordinator = ExitCoordinator::new();
+        assert_eq!(
+            coordinator.hides_to_tray(),
+            TrayAvailability::assumed().hides_to_tray()
+        );
+        coordinator.set_tray(TrayAvailability::Unavailable);
+        assert!(!coordinator.hides_to_tray());
+        assert_eq!(
+            coordinator.decision(),
+            ExitDecision::Drain(ExitReason::UserQuit)
+        );
+        coordinator.set_tray(TrayAvailability::Available);
+        assert_eq!(coordinator.decision(), ExitDecision::Hide);
+    }
+}
diff --git a/desktop/src-tauri/src/first_run.rs b/desktop/src-tauri/src/first_run.rs
new file mode 100644
index 00000000000..3fc7616b93f
--- /dev/null
+++ b/desktop/src-tauri/src/first_run.rs
@@ -0,0 +1,111 @@
+use std::fs;
+use tauri::{AppHandle, Manager};
+use tauri_plugin_autostart::ManagerExt;
+
+/// Marker file recording that the one-time Start at Login default has already been applied.
+const MARKER: &str = "start-at-login-claimed";
+
+/// Marker file recording that the login item names the launch-origin argument.
+const ORIGIN_MARKER: &str = "start-at-login-origin-flag";
+
+/// What the one-time Start at Login decision did on this launch.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum StartAtLogin {
+    /// This installation had already decided, so whatever the user set is left alone.
+    AlreadyDecided,
+    /// Turned on for the first time on this installation.
+    Enabled,
+    /// The default could not be applied. The app still starts and the tray item still toggles it.
+    Unavailable,
+}
+
+impl StartAtLogin {
+    pub fn describe(self) -> &'static str {
+        match self {
+            Self::AlreadyDecided => "already decided on this installation, left as the user set it",
+            Self::Enabled => "turned on for this installation",
+            Self::Unavailable => "could not be registered; the tray item still toggles it",
+        }
+    }
+}
+
+/// Turn Start at Login on once, the first time this installation runs.
+///
+/// A menu bar app that is not running has no menu bar item. Leaving autostart off by default
+/// therefore means that after the next reboot an installed app is simply absent, with nothing on
+/// screen to explain why — which is not a neutral default for an app whose main surface *is* the
+/// menu bar.
+///
+/// This runs exactly once per installation. The marker is written **before** the login item is
+/// touched, and is never removed, so a user who turns Start at Login back off keeps it off: the
+/// next launch sees the marker and does nothing. Writing afterwards instead would mean that a
+/// failed or partial enable retries on every launch, and would eventually flip the setting back on
+/// under a user who had deliberately turned it off in between.
+///
+/// No failure stops the app. Not being able to write a marker or register a login item is not a
+/// reason to refuse to start, and the user can still toggle the menu item. What has changed is that
+/// the outcome is returned rather than swallowed: D7's startup sequence reports this decision as
+/// one of its named states, so a registration that did not happen is visible instead of silent.
+pub fn apply_start_at_login_default(app: &AppHandle) -> StartAtLogin {
+    let Ok(dir) = app.path().app_config_dir() else {
+        return StartAtLogin::Unavailable;
+    };
+    let marker = dir.join(MARKER);
+    if marker.exists() {
+        return StartAtLogin::AlreadyDecided;
+    }
+    if fs::create_dir_all(&dir).is_err() {
+        return StartAtLogin::Unavailable;
+    }
+    if fs::write(&marker, b"").is_err() {
+        return StartAtLogin::Unavailable;
+    }
+    if app.autolaunch().is_enabled().unwrap_or(false) {
+        return StartAtLogin::AlreadyDecided;
+    }
+    match app.autolaunch().enable() {
+        Ok(()) => StartAtLogin::Enabled,
+        Err(_) => StartAtLogin::Unavailable,
+    }
+}
+
+/// Rewrite an existing login item so a launch from it can be recognised as one.
+///
+/// The autostart entry is written once, carrying whatever arguments the plugin was configured with
+/// at the time. An installation that registered before the launch-origin argument existed has an
+/// entry without it, and a bare launch carries nothing else that distinguishes login from manual —
+/// so D7's hidden login start would quietly never happen for exactly the users who already had
+/// autostart on. Re-registering rewrites the entry with the current arguments.
+///
+/// It runs once, behind its own marker, and only where autostart is already on. It never turns the
+/// setting on and never turns it off; the worst case is an entry that keeps its old arguments and a
+/// login launch that shows its window, which is the visible failure rather than the silent one.
+pub fn adopt_launch_origin_argument(app: &AppHandle) {
+    let Ok(dir) = app.path().app_config_dir() else {
+        return;
+    };
+    let claimed = dir.join(ORIGIN_MARKER);
+    if claimed.exists() {
+        return;
+    }
+    if fs::create_dir_all(&dir).is_err() {
+        return;
+    }
+    // Unlike the default above, the marker is written *after* the work, and that difference is
+    // deliberate. Writing first exists there to stop a failed enable from flipping a setting the
+    // user turned off. Here there is no setting to flip: the rewrite only ever runs on an entry
+    // that is already enabled, so retrying after a transient registry, LaunchAgent or desktop-file
+    // error is free — and claiming the marker first would suppress the migration permanently and
+    // leave a login launch showing its window forever.
+    match app.autolaunch().is_enabled() {
+        Ok(true) => {
+            if app.autolaunch().enable().is_err() {
+                return;
+            }
+        }
+        // Nothing registered to migrate. A later enable writes the current arguments anyway.
+        Ok(false) => {}
+        Err(_) => return,
+    }
+    let _ = fs::write(&claimed, b"");
+}
diff --git a/desktop/src-tauri/src/formatting.rs b/desktop/src-tauri/src/formatting.rs
new file mode 100644
index 00000000000..5f940b68fed
--- /dev/null
+++ b/desktop/src-tauri/src/formatting.rs
@@ -0,0 +1,79 @@
+pub fn tokens(value: Option<i64>) -> String {
+    abbreviate(value, true)
+}
+
+pub fn count(value: Option<i64>) -> String {
+    abbreviate(value, false)
+}
+
+pub fn cost(value: Option<f64>) -> String {
+    let Some(value) = value else {
+        return "—".into();
+    };
+    if value < 1_000.0 {
+        return format!("${value:.2}");
+    }
+    format!("${}", abbreviate_float(value, false))
+}
+
+fn abbreviate(value: Option<i64>, integer: bool) -> String {
+    let Some(value) = value else {
+        return "—".into();
+    };
+    if !integer && value < 10_000 {
+        return format!("{value}");
+    }
+    if integer && value < 1_000 {
+        return format!("{value}");
+    }
+    abbreviate_float(value as f64, integer)
+}
+
+fn abbreviate_float(value: f64, integer: bool) -> String {
+    let units = [
+        (1_000_000_000_000.0, "T"),
+        (1_000_000_000.0, "B"),
+        (1_000_000.0, "M"),
+        (1_000.0, "K"),
+    ];
+    for (threshold, suffix) in units {
+        if value >= threshold * 0.9995 {
+            let scaled = value / threshold;
+            let decimals = if integer || scaled >= 100.0 {
+                0
+            } else if scaled >= 10.0 {
+                1
+            } else {
+                2
+            };
+            let rendered = format!("{scaled:.decimals$}");
+            return format!(
+                "{}{}",
+                rendered.trim_end_matches('0').trim_end_matches('.'),
+                suffix
+            );
+        }
+    }
+    format!("{value:.0}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn token_boundaries_match_swift_formatting() {
+        assert_eq!(tokens(Some(999_600)), "1M");
+        assert_eq!(tokens(Some(1_234)), "1K");
+        assert_eq!(tokens(Some(2_401_634_303)), "2B");
+        assert_eq!(tokens(None), "—");
+    }
+
+    #[test]
+    fn counts_and_costs_have_expected_precision() {
+        assert_eq!(count(Some(9_999)), "9999");
+        assert_eq!(count(Some(12_345)), "12.3K");
+        assert_eq!(cost(Some(12.345)), "$12.35");
+        assert_eq!(cost(Some(1_234.0)), "$1.23K");
+    }
+}
diff --git a/desktop/src-tauri/src/identity.rs b/desktop/src-tauri/src/identity.rs
new file mode 100644
index 00000000000..9deb1c32e0a
--- /dev/null
+++ b/desktop/src-tauri/src/identity.rs
@@ -0,0 +1,111 @@
+//! This installation's own identity.
+//!
+//! The shared service install state records who owns the running proxy, and the claim names the
+//! owning *installation* rather than the user or the machine. So the app has to hold a value of its
+//! own to compare against, which is this: an opaque id written once into the app's config directory
+//! and never rewritten.
+//!
+//! Two records rather than one is D3, and its cost is recorded there. An id stored only in the
+//! shared record would be whoever wrote it last, which gives a reinstalled app no way to tell its
+//! own prior consent from another installation's. The price is that a reinstall which keeps this
+//! directory keeps its consent, and one that loses it has to ask again.
+
+use std::{
+    fs,
+    io::{ErrorKind, Write},
+    path::Path,
+};
+use tauri::{AppHandle, Manager};
+use uuid::Uuid;
+
+/// The file holding this installation's id, in the app's own config directory.
+const FILE: &str = "install-id";
+
+pub fn install_id(app: &AppHandle) -> Option<String> {
+    let directory = app.path().app_config_dir().ok()?;
+    install_id_in(&directory)
+}
+
+/// Read this installation's id, minting it the first time.
+///
+/// The mint is exclusive and the value is read back afterwards, so two launches racing each other
+/// both answer to the id that won rather than to two different ones. Two ids would be two
+/// installations as far as the recorded claim is concerned, and the second would find a claim that
+/// is not its own and ask again for consent the user had already given.
+pub fn install_id_in(directory: &Path) -> Option<String> {
+    let path = directory.join(FILE);
+    if let Some(existing) = read(&path) {
+        return Some(existing);
+    }
+    fs::create_dir_all(directory).ok()?;
+    match mint(&path) {
+        Ok(()) => {}
+        // The file is there and says nothing: a blank or truncated write from an interrupted first
+        // run. An empty id matches nothing, so every comparison against the recorded claim would
+        // quietly be false and the app would ask for consent it already had. Replace it.
+        Err(ErrorKind::AlreadyExists) => {
+            if read(&path).is_none() {
+                fs::write(&path, Uuid::new_v4().to_string()).ok()?;
+            }
+        }
+        Err(_) => return None,
+    }
+    read(&path)
+}
+
+fn mint(path: &Path) -> Result<(), ErrorKind> {
+    fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(path)
+        .and_then(|mut file| file.write_all(Uuid::new_v4().to_string().as_bytes()))
+        .map_err(|error| error.kind())
+}
+
+fn read(path: &Path) -> Option<String> {
+    let value = fs::read_to_string(path).ok()?;
+    let trimmed = value.trim();
+    (!trimmed.is_empty()).then(|| trimmed.to_owned())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{install_id_in, FILE};
+    use std::fs;
+
+    fn scratch(name: &str) -> std::path::PathBuf {
+        let directory =
+            std::env::temp_dir().join(format!("ocx-identity-{name}-{}", std::process::id()));
+        let _ = fs::remove_dir_all(&directory);
+        directory
+    }
+
+    #[test]
+    fn the_id_is_minted_once_and_then_read_back() {
+        let directory = scratch("mint");
+        let first = install_id_in(&directory).expect("an id");
+        assert!(!first.is_empty());
+        assert_eq!(install_id_in(&directory).as_deref(), Some(first.as_str()));
+        let _ = fs::remove_dir_all(&directory);
+    }
+
+    #[test]
+    fn two_installations_do_not_share_an_id() {
+        let one = scratch("one");
+        let two = scratch("two");
+        assert_ne!(install_id_in(&one), install_id_in(&two));
+        let _ = fs::remove_dir_all(&one);
+        let _ = fs::remove_dir_all(&two);
+    }
+
+    #[test]
+    fn a_blank_record_is_replaced_rather_than_answered_with() {
+        let directory = scratch("blank");
+        fs::create_dir_all(&directory).unwrap();
+        fs::write(directory.join(FILE), "   \n").unwrap();
+        let minted = install_id_in(&directory).expect("an id");
+        assert!(!minted.trim().is_empty());
+        assert_eq!(install_id_in(&directory).as_deref(), Some(minted.as_str()));
+        let _ = fs::remove_dir_all(&directory);
+    }
+}
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
new file mode 100644
index 00000000000..d24fefba790
--- /dev/null
+++ b/desktop/src-tauri/src/lib.rs
@@ -0,0 +1,236 @@
+mod auth;
+mod endpoint;
+mod exit;
+mod first_run;
+mod formatting;
+mod identity;
+mod logging;
+// macOS only: it exists to replace one item in a menu no other platform installs. Compiling it
+// elsewhere would leave its contents unreachable, which -D warnings rejects.
+#[cfg(target_os = "macos")]
+mod menu;
+mod ownership;
+mod proxy;
+mod resolve;
+mod runtime_stop;
+mod sidecar;
+mod startup;
+mod tray;
+mod tray_availability;
+mod updater;
+mod widget;
+mod window;
+
+use std::sync::{
+    atomic::{AtomicBool, Ordering},
+    Mutex, MutexGuard, PoisonError,
+};
+use tauri::{Manager, WebviewUrl, WebviewWindowBuilder};
+use tauri_plugin_autostart::MacosLauncher;
+use tauri_plugin_shell::process::CommandChild;
+
+pub struct AppState {
+    /// Absent until the startup sequence has resolved a home and a port. Nothing guesses an
+    /// endpoint any more, so there is no client to hand out before that.
+    proxy: Mutex<Option<proxy::ProxyClient>>,
+    child: Mutex<Option<CommandChild>>,
+    /// The pid of the child this app started, if it started one.
+    child_pid: Mutex<Option<u32>>,
+    /// Whether the process answering the endpoint has been confirmed to be that child.
+    ///
+    /// Durable consent and current process ownership are different facts. Consent is a recorded
+    /// claim that survives restarts; this is a statement about the process on the other end of the
+    /// endpoint right now, and it has to be re-established whenever the endpoint or the answering
+    /// process can have changed. Carrying a bool across an attach is how a retry that lands on a
+    /// foreign runtime would still send it an owner's stop.
+    confirmed: AtomicBool,
+    /// The consumed spawn event stream of the child, if this app started one.
+    pub watch: sidecar::SidecarWatch,
+}
+
+impl AppState {
+    pub fn new() -> Self {
+        Self {
+            proxy: Mutex::new(None),
+            child: Mutex::new(None),
+            child_pid: Mutex::new(None),
+            confirmed: AtomicBool::new(false),
+            watch: sidecar::SidecarWatch::default(),
+        }
+    }
+
+    fn slot<T>(lock: &Mutex<T>) -> MutexGuard<'_, T> {
+        lock.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    pub fn proxy(&self) -> Option<proxy::ProxyClient> {
+        Self::slot(&self.proxy).clone()
+    }
+
+    /// Point at a runtime. Nothing is owned until it is confirmed again.
+    pub fn attach(&self, proxy: proxy::ProxyClient) {
+        self.confirmed.store(false, Ordering::Release);
+        *Self::slot(&self.proxy) = Some(proxy);
+    }
+
+    pub fn owns_runtime(&self) -> bool {
+        self.confirmed.load(Ordering::Acquire)
+    }
+
+    pub fn child_pid(&self) -> Option<u32> {
+        *Self::slot(&self.child_pid)
+    }
+
+    /// Confirm that the instance answering is the child this app started.
+    ///
+    /// This is the only thing that grants ownership. A spawn records a pid; it does not record that
+    /// the pid is what holds the port, because between the two the child can exit and a service can
+    /// take the port back.
+    pub fn confirm_ownership(&self, identity: proxy::RuntimeIdentity) -> bool {
+        let ours = self.child_pid() == Some(identity.pid);
+        self.confirmed.store(ours, Ordering::Release);
+        ours
+    }
+
+    pub fn adopt(&self, child: CommandChild) {
+        *Self::slot(&self.child_pid) = Some(child.pid());
+        *Self::slot(&self.child) = Some(child);
+        // Spawned, not yet confirmed: the health probe is what establishes that this pid is the
+        // one answering.
+        self.confirmed.store(false, Ordering::Release);
+    }
+
+    /// Let go of a runtime that has already been drained.
+    ///
+    /// Dropping the handle does not signal the process — the shell plugin installs no `Drop` — so
+    /// this releases ownership without reintroducing the `kill()` that D2 removed.
+    pub fn release(&self) {
+        self.confirmed.store(false, Ordering::Release);
+        let _ = Self::slot(&self.child_pid).take();
+        let _ = Self::slot(&self.child).take();
+    }
+}
+
+impl Default for AppState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[tauri::command]
+fn show_dashboard(app: tauri::AppHandle) {
+    if let Some(window) = app.get_webview_window("main") {
+        window::show(&window);
+    }
+}
+
+#[tauri::command]
+fn hide_dashboard(app: tauri::AppHandle) {
+    if let Some(window) = app.get_webview_window("main") {
+        window::hide(&window);
+    }
+}
+
+/// Everything the startup sequence has said so far, including the states it has already finished.
+///
+/// The page asks for this when it loads rather than relying only on the event stream: the first
+/// states finish in milliseconds and an event emitted before the listener exists is simply gone.
+#[tauri::command]
+fn startup_snapshot(app: tauri::AppHandle) -> Option<startup::Progress> {
+    app.try_state::<startup::Startup>()
+        .map(|startup| startup.latest())
+}
+
+/// The named states the startup sequence moves through, in order.
+///
+/// The page asks for them instead of restating them, so a state added in the shell appears in the
+/// UI and one removed cannot leave a row behind.
+#[tauri::command]
+fn startup_phases() -> Vec<startup::PhaseInfo> {
+    startup::phase_list()
+}
+
+/// Run the startup sequence again. A run already in flight is left alone.
+#[tauri::command]
+fn retry_startup(app: tauri::AppHandle) {
+    startup::begin(&app);
+}
+
+pub fn run() {
+    let builder = tauri::Builder::default()
+        .plugin(tauri_plugin_single_instance::init(|app, _args, _cwd| {
+            if let Some(window) = app.get_webview_window("main") {
+                window::show(&window);
+            }
+        }))
+        .plugin(tauri_plugin_opener::init())
+        .plugin(tauri_plugin_process::init())
+        // The argument is what makes a login launch recognisable. Nothing else in a bare launch
+        // distinguishes it from a person opening the app, and D7 needs the difference.
+        .plugin(tauri_plugin_autostart::init(
+            MacosLauncher::LaunchAgent,
+            Some(vec![startup::AUTOSTART_FLAG]),
+        ))
+        .plugin(tauri_plugin_shell::init())
+        .plugin(tauri_plugin_updater::Builder::new().build());
+
+    // macOS is the one platform where the event loop cannot enforce D2 on its own: Tauri's default
+    // menu carries a predefined Quit wired to Cocoa's terminate:, and the pinned tao raises no
+    // cancellable event for it. Replacing that one item is what lets Cmd+Q mean hide.
+    #[cfg(target_os = "macos")]
+    let builder = builder
+        .menu(menu::build)
+        .on_menu_event(|app, event| menu::on_event(app, event.id().as_ref()));
+
+    builder
+        .invoke_handler(tauri::generate_handler![
+            show_dashboard,
+            hide_dashboard,
+            startup_snapshot,
+            startup_phases,
+            retry_startup
+        ])
+        .setup(|app| {
+            app.manage(AppState::new());
+            app.manage(updater::PendingUpdate(Mutex::new(None)));
+            app.manage(tray::TrayState::default());
+            app.manage(exit::ExitCoordinator::new());
+            app.manage(startup::Startup::new());
+
+            // D7: the window is created and shown before anything is registered, resolved, probed
+            // or started, so every state below has somewhere to be reported. A login launch stays
+            // hidden until the tray verdict, because R1 shows it after all when there turns out to
+            // be nowhere to hide.
+            let window =
+                WebviewWindowBuilder::new(app, "main", WebviewUrl::App("index.html".into()))
+                    .title("OpenCodex")
+                    .inner_size(1100.0, 720.0)
+                    .visible(false)
+                    .user_agent(&window::webview_user_agent())
+                    .on_navigation(window::navigation_allowed(app.handle().clone()))
+                    .build()?;
+            window::configure(&window);
+            if startup::LaunchOrigin::detect() == startup::LaunchOrigin::User {
+                window::show(&window);
+            } else {
+                window::set_tray_policy(app.handle(), false);
+            }
+
+            startup::begin(app.handle());
+
+            if !cfg!(debug_assertions) {
+                updater::start_background_checks(app.handle().clone());
+            }
+            Ok(())
+        })
+        .build(tauri::generate_context!())
+        .expect("error while building OpenCodex desktop shell")
+        .run(|app, event| {
+            // Window close and the platform quit gesture arrive here as an exit request, and until
+            // this handler existed they went straight through to a SIGKILL of the runtime. D2 makes
+            // them hide; only the tray's Quit, and an update's coordinated restart, get past.
+            if let tauri::RunEvent::ExitRequested { code, api, .. } = event {
+                exit::on_exit_requested(app, code, &api);
+            }
+        });
+}
diff --git a/desktop/src-tauri/src/logging.rs b/desktop/src-tauri/src/logging.rs
new file mode 100644
index 00000000000..a3b71fb5f47
--- /dev/null
+++ b/desktop/src-tauri/src/logging.rs
@@ -0,0 +1,14 @@
+use std::{
+    collections::HashSet,
+    sync::{Mutex, OnceLock},
+};
+
+pub fn log_once(scope: &str, message: &str) {
+    static LOGGED: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();
+    let logged = LOGGED.get_or_init(|| Mutex::new(HashSet::new()));
+    if let Ok(mut logged) = logged.lock() {
+        if logged.insert(format!("{scope}: {message}")) {
+            eprintln!("{scope}: {message}");
+        }
+    }
+}
diff --git a/desktop/src-tauri/src/main.rs b/desktop/src-tauri/src/main.rs
new file mode 100644
index 00000000000..8d5174cf6fa
--- /dev/null
+++ b/desktop/src-tauri/src/main.rs
@@ -0,0 +1,5 @@
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    opencodex_desktop_lib::run();
+}
diff --git a/desktop/src-tauri/src/menu.rs b/desktop/src-tauri/src/menu.rs
new file mode 100644
index 00000000000..58bc4346613
--- /dev/null
+++ b/desktop/src-tauri/src/menu.rs
@@ -0,0 +1,120 @@
+//! The macOS application menu.
+//!
+//! Tauri installs a default menu when the app sets none, and that menu's Quit is a predefined item
+//! wired straight to Cocoa's `terminate:`. The pinned tao implements only
+//! `applicationWillTerminate`, never the cancellable `applicationShouldTerminate`, so a Cmd+Q
+//! through that item reaches `RunEvent::Exit` without ever raising `RunEvent::ExitRequested`.
+//! Nothing can hold it, which means D2's rule — the quit gesture hides, only the tray's Quit ends
+//! the app — cannot be enforced from the event loop alone on macOS. The one item is replaced here
+//! with an ordinary item on the same accelerator, routed through the same gesture path as closing
+//! the window.
+//!
+//! The rest is reproduced rather than mutated: `Menu::default` is not decomposable, and dropping it
+//! would take Cut, Copy, Paste and Select All with it — which the startup diagnostic needs the user
+//! to be able to use. This mirrors `tauri::menu::Menu::default` for the pinned version, minus that
+//! item.
+
+/// The id of the replacement Quit item. Nothing else in the app uses it, so a menu event carrying
+/// it is unambiguously this one.
+pub const QUIT_ID: &str = "app-menu-quit";
+
+pub fn build(app: &tauri::AppHandle) -> tauri::Result<tauri::menu::Menu<tauri::Wry>> {
+    use tauri::menu::{
+        AboutMetadata, Menu, MenuItem, PredefinedMenuItem, Submenu, HELP_SUBMENU_ID,
+        WINDOW_SUBMENU_ID,
+    };
+
+    let package = app.package_info();
+    let config = app.config();
+    let about = AboutMetadata {
+        name: Some(package.name.clone()),
+        version: Some(package.version.to_string()),
+        copyright: config.bundle.copyright.clone(),
+        authors: config
+            .bundle
+            .publisher
+            .clone()
+            .map(|publisher| vec![publisher]),
+        ..Default::default()
+    };
+
+    // Labelled as a quit because that is the gesture the user is making. What it means here is
+    // D2's answer to that gesture: the window goes away and the runtime keeps serving.
+    let quit = MenuItem::with_id(
+        app,
+        QUIT_ID,
+        format!("Quit {}", package.name),
+        true,
+        Some("CmdOrCtrl+Q"),
+    )?;
+
+    Menu::with_items(
+        app,
+        &[
+            &Submenu::with_items(
+                app,
+                package.name.clone(),
+                true,
+                &[
+                    &PredefinedMenuItem::about(app, None, Some(about))?,
+                    &PredefinedMenuItem::separator(app)?,
+                    &PredefinedMenuItem::services(app, None)?,
+                    &PredefinedMenuItem::separator(app)?,
+                    &PredefinedMenuItem::hide(app, None)?,
+                    &PredefinedMenuItem::hide_others(app, None)?,
+                    &PredefinedMenuItem::separator(app)?,
+                    &quit,
+                ],
+            )?,
+            &Submenu::with_items(
+                app,
+                "File",
+                true,
+                &[&PredefinedMenuItem::close_window(app, None)?],
+            )?,
+            &Submenu::with_items(
+                app,
+                "Edit",
+                true,
+                &[
+                    &PredefinedMenuItem::undo(app, None)?,
+                    &PredefinedMenuItem::redo(app, None)?,
+                    &PredefinedMenuItem::separator(app)?,
+                    &PredefinedMenuItem::cut(app, None)?,
+                    &PredefinedMenuItem::copy(app, None)?,
+                    &PredefinedMenuItem::paste(app, None)?,
+                    &PredefinedMenuItem::select_all(app, None)?,
+                ],
+            )?,
+            &Submenu::with_items(
+                app,
+                "View",
+                true,
+                &[&PredefinedMenuItem::fullscreen(app, None)?],
+            )?,
+            &Submenu::with_id_and_items(
+                app,
+                WINDOW_SUBMENU_ID,
+                "Window",
+                true,
+                &[
+                    &PredefinedMenuItem::minimize(app, None)?,
+                    &PredefinedMenuItem::maximize(app, None)?,
+                    &PredefinedMenuItem::separator(app)?,
+                    &PredefinedMenuItem::close_window(app, None)?,
+                ],
+            )?,
+            &Submenu::with_id_and_items(app, HELP_SUBMENU_ID, "Help", true, &[])?,
+        ],
+    )
+}
+
+/// Route an application-menu event.
+///
+/// Only the replacement Quit is ours. Tray menu events are handled by the tray's own handler and
+/// carry different ids, so an id that is not [`QUIT_ID`] is left alone.
+pub fn on_event(app: &tauri::AppHandle, id: &str) {
+    if id == QUIT_ID {
+        crate::exit::gesture(app);
+    }
+}
diff --git a/desktop/src-tauri/src/ownership.rs b/desktop/src-tauri/src/ownership.rs
new file mode 100644
index 00000000000..a27bbf6a8e2
--- /dev/null
+++ b/desktop/src-tauri/src/ownership.rs
@@ -0,0 +1,249 @@
+//! Who owns the running proxy, as the shared service install state records it.
+//!
+//! The rule is not this lane's to invent. `src/service/state.ts` defines the claim — an owner, an
+//! opaque install id naming the owning installation, and a consent generation — and
+//! `ownershipGrantedTo` defines the comparison an installation applies to its own locally stored
+//! install id. This is that comparison, and the three-valued reading it is applied to, so the shell
+//! reaches the same verdict the CLI does instead of a weaker one of its own.
+//!
+//! What the shell deliberately does not do is read the record itself. Resolving a claim means
+//! reading every state path and failing closed on an unreadable one, on a corrupt anchor record and
+//! on paths that name different owners; absence is the only thing that means nobody owns the
+//! runtime. Reimplementing that here is how `discovery.rs` ended up asking a weaker liveness
+//! question than the one core already answered. The bundled CLI answers it: see [`resolve`].
+//!
+//! The types below are the CLI's own answer as it will arrive on the wire, field for field, so the
+//! contract that lands fills a hole rather than reshaping this file.
+
+use serde::Deserialize;
+use tauri::AppHandle;
+
+/// Who a claim names.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Owner {
+    Cli,
+    Desktop,
+}
+
+/// A recorded ownership claim.
+#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Claim {
+    pub owner: Owner,
+    pub install_id: String,
+    /// Moves once per grant, and never back: the recorded ceiling survives a release so a later
+    /// grant cannot reuse a number an app-local record may still be holding.
+    ///
+    /// The record accepts any non-negative integer, and this accepts the ones it can represent. A
+    /// generation outside that range fails to parse, which makes the whole answer unreadable and
+    /// so refuses a takeover — the safe direction, and unreachable in practice by a counter that
+    /// moves by one per grant.
+    pub consent_generation: u64,
+}
+
+/// What the recorded state says, in the CLI's own three answers.
+#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
+#[serde(tag = "kind", rename_all = "lowercase")]
+pub enum Recorded {
+    /// No claim. The CLI install that registered the service owns the runtime, which is also what
+    /// every record written before the field existed says.
+    None,
+    /// A claim, whoever it names.
+    Owned { ownership: Claim },
+    /// The claim could not be read for a decision. This is not "nobody owns it": an unreadable
+    /// path, a corrupt anchor record and paths naming different owners all land here.
+    Unknown { reason: String },
+}
+
+/// The comparison `ownershipGrantedTo` defines: same owner, same install id.
+///
+/// True means this installation already holds consent. False against a recorded claim means a
+/// different installation owns the runtime and consent has to be asked again. No claim means the
+/// CLI install still owns it. The generation is not part of the comparison.
+pub fn granted_to(claim: Option<&Claim>, owner: Owner, install_id: &str) -> bool {
+    matches!(claim, Some(claim) if claim.owner == owner && claim.install_id == install_id)
+}
+
+/// What this installation should do about consent.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Consent {
+    /// This installation already holds consent. Asked once, owned permanently — so a second launch
+    /// does not ask again.
+    Held,
+    /// Nothing is recorded, so the CLI install still owns the runtime. This is the first discovery
+    /// of an existing installation, and the one time the user is asked.
+    AskFirstTime,
+    /// A claim exists and it is not ours: another installation, or the CLI explicitly.
+    AskAgain,
+    /// The record could not be read for a decision, so nothing is taken over on a guess.
+    Refuse,
+}
+
+pub fn consent(recorded: &Recorded, install_id: &str) -> Consent {
+    match recorded {
+        Recorded::Unknown { .. } => Consent::Refuse,
+        Recorded::None => Consent::AskFirstTime,
+        Recorded::Owned { ownership } => {
+            if granted_to(Some(ownership), Owner::Desktop, install_id) {
+                Consent::Held
+            } else {
+                Consent::AskAgain
+            }
+        }
+    }
+}
+
+/// Read the recorded claim through the bundled CLI.
+///
+/// Empty on purpose. Lane A publishes the machine-readable resolve the shell drives, and this is
+/// the one call site that changes when it lands: it has to return the CLI's own answer, including
+/// its refusals, rather than a verdict computed here. Until then the answer is *unavailable*, which
+/// is not [`Recorded::None`] — the shell has not been told that nobody owns the runtime, it has not
+/// asked — so no takeover is attempted and nothing is recorded.
+pub fn resolve(_app: &AppHandle) -> Option<Recorded> {
+    None
+}
+
+/// One line for the startup state and for the diagnostic.
+pub fn describe(recorded: Option<&Recorded>, install_id: Option<&str>) -> String {
+    let installation = match install_id {
+        Some(id) => format!("installation {id}"),
+        None => "installation id unavailable".to_owned(),
+    };
+    let verdict = match (recorded, install_id) {
+        (None, _) => {
+            "recorded owner not read: the bundled CLI's resolve contract has not landed".to_owned()
+        }
+        (Some(Recorded::Unknown { reason }), _) => {
+            format!("recorded owner could not be read ({reason}), so nothing is claimed")
+        }
+        (Some(_), None) => {
+            "recorded owner read, but this installation has no id to compare".to_owned()
+        }
+        (Some(recorded), Some(id)) => match (consent(recorded, id), recorded) {
+            (Consent::Held, Recorded::Owned { ownership }) => format!(
+                "this installation owns the runtime (consent generation {})",
+                ownership.consent_generation
+            ),
+            (Consent::AskFirstTime, _) => "the CLI install owns the runtime".to_owned(),
+            (Consent::AskAgain, _) => "another installation owns the runtime".to_owned(),
+            _ => "recorded owner could not be read, so nothing is claimed".to_owned(),
+        },
+    };
+    format!("{installation}; {verdict}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{consent, describe, granted_to, Claim, Consent, Owner, Recorded};
+
+    fn owned(owner: Owner, install_id: &str, generation: u64) -> Recorded {
+        Recorded::Owned {
+            ownership: Claim {
+                owner,
+                install_id: install_id.to_owned(),
+                consent_generation: generation,
+            },
+        }
+    }
+
+    fn claim(owner: Owner, install_id: &str) -> Claim {
+        Claim {
+            owner,
+            install_id: install_id.to_owned(),
+            consent_generation: 1,
+        }
+    }
+
+    #[test]
+    fn the_comparison_is_the_owner_and_the_install_id_together() {
+        let ours = claim(Owner::Desktop, "abc");
+        assert!(granted_to(Some(&ours), Owner::Desktop, "abc"));
+        assert!(!granted_to(Some(&ours), Owner::Desktop, "def"));
+        assert!(!granted_to(Some(&ours), Owner::Cli, "abc"));
+        assert!(!granted_to(None, Owner::Desktop, "abc"));
+    }
+
+    #[test]
+    fn the_generation_is_not_part_of_the_comparison() {
+        let mut later = claim(Owner::Desktop, "abc");
+        later.consent_generation = 9;
+        assert!(granted_to(Some(&later), Owner::Desktop, "abc"));
+    }
+
+    #[test]
+    fn consent_is_asked_once_and_then_held() {
+        assert_eq!(
+            consent(&owned(Owner::Desktop, "abc", 1), "abc"),
+            Consent::Held
+        );
+        assert_eq!(consent(&Recorded::None, "abc"), Consent::AskFirstTime);
+    }
+
+    #[test]
+    fn a_claim_that_is_not_ours_asks_again() {
+        assert_eq!(
+            consent(&owned(Owner::Desktop, "other", 2), "abc"),
+            Consent::AskAgain
+        );
+        assert_eq!(
+            consent(&owned(Owner::Cli, "abc", 1), "abc"),
+            Consent::AskAgain
+        );
+    }
+
+    #[test]
+    fn an_unreadable_record_refuses_instead_of_reading_as_unowned() {
+        let unknown = Recorded::Unknown {
+            reason: "a service state path could not be read".to_owned(),
+        };
+        assert_eq!(consent(&unknown, "abc"), Consent::Refuse);
+        assert!(describe(Some(&unknown), Some("abc")).contains("could not be read"));
+    }
+
+    #[test]
+    fn the_wire_shape_is_the_one_the_cli_records() {
+        let resolution: Recorded = serde_json::from_str(
+            r#"{"kind":"owned","ownership":{"owner":"desktop","installId":"abc","consentGeneration":3}}"#,
+        )
+        .expect("the recorded resolution");
+        assert_eq!(resolution, owned(Owner::Desktop, "abc", 3));
+        assert_eq!(consent(&resolution, "abc"), Consent::Held);
+        assert!(describe(Some(&resolution), Some("abc")).contains("consent generation 3"));
+        assert_eq!(
+            serde_json::from_str::<Recorded>(r#"{"kind":"none"}"#).expect("no claim"),
+            Recorded::None
+        );
+        assert_eq!(
+            serde_json::from_str::<Recorded>(r#"{"kind":"unknown","reason":"why"}"#)
+                .expect("a refusal"),
+            Recorded::Unknown {
+                reason: "why".to_owned()
+            }
+        );
+    }
+
+    #[test]
+    fn the_description_separates_not_asked_from_nobody_owns_it() {
+        let not_asked = describe(None, Some("abc"));
+        let unowned = describe(Some(&Recorded::None), Some("abc"));
+        assert!(not_asked.contains("abc"));
+        assert_ne!(not_asked, unowned);
+        assert!(describe(None, None).contains("unavailable"));
+    }
+
+    #[test]
+    fn a_generation_this_cannot_represent_is_not_read_as_a_claim() {
+        // Refusing beats granting on a number we cannot compare, and the claim is what a takeover
+        // would be authorised against.
+        assert!(serde_json::from_str::<Recorded>(
+            r#"{"kind":"owned","ownership":{"owner":"desktop","installId":"abc","consentGeneration":-1}}"#
+        )
+        .is_err());
+        assert!(serde_json::from_str::<Recorded>(
+            r#"{"kind":"owned","ownership":{"owner":"cli","installId":"abc","consentGeneration":"3"}}"#
+        )
+        .is_err());
+    }
+}
diff --git a/desktop/src-tauri/src/proxy.rs b/desktop/src-tauri/src/proxy.rs
new file mode 100644
index 00000000000..fc45d820256
--- /dev/null
+++ b/desktop/src-tauri/src/proxy.rs
@@ -0,0 +1,277 @@
+use crate::{auth::Auth, endpoint::ProxyEndpoint};
+use reqwest::{redirect, Client, Method, StatusCode};
+use serde_json::Value;
+use std::{
+    sync::{Arc, Mutex, MutexGuard, PoisonError},
+    time::Duration,
+};
+use tokio::time::{timeout_at, Instant};
+
+/// Which instance answered, taken from the unauthenticated health body.
+///
+/// The management token is the admin credential for this machine's proxy. Sending it to whatever
+/// happens to hold the port is the thing to avoid, so identity is established first — from a
+/// response that needs no credential to read — and the credential follows only if the answer is the
+/// instance the shell decided to trust.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct RuntimeIdentity {
+    pub pid: u32,
+    pub port: u16,
+}
+
+/// The instance this client is bound to, and the binding it was bound under.
+///
+/// The generation moves every time the shell binds to a runtime. A request authorised under an
+/// earlier binding is not authorised under this one, which is what stops an in-flight management
+/// call from landing on a runtime the shell rebound to in between.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct RuntimeBinding {
+    pub identity: RuntimeIdentity,
+    pub generation: u64,
+}
+
+#[derive(Clone)]
+pub struct ProxyClient {
+    client: Client,
+    endpoint: ProxyEndpoint,
+    auth: Auth,
+    binding: Arc<Mutex<Option<RuntimeBinding>>>,
+    generations: Arc<Mutex<u64>>,
+}
+
+#[derive(Debug)]
+pub enum ProxyError {
+    Unreachable,
+    Unauthorized,
+    Http(StatusCode),
+    Decode(reqwest::Error),
+    /// The listener answered, but not as the instance this client is bound to — a foreign service
+    /// on the port, or a different process than the one the shell confirmed.
+    Foreign,
+}
+
+impl ProxyError {
+    /// Whether nothing is listening on the endpoint at all.
+    ///
+    /// This is the only error that says anything about the process behind the port. A timeout, an
+    /// unauthorized reply or a body that will not parse all mean the listener answered or might
+    /// still be there, and a stop that reads any of them as "gone" reports a drain that did not
+    /// happen.
+    pub fn is_unreachable(&self) -> bool {
+        matches!(self, Self::Unreachable)
+    }
+}
+
+/// Read an identity out of a health body.
+///
+/// The marker is required: a 200 from something else on the port is not this proxy. The port is
+/// required to be the one addressed, so a body describing a different listener cannot authorise a
+/// credential for this one.
+pub fn identity_from(body: &Value, addressed_port: u16) -> Option<RuntimeIdentity> {
+    if body.get("service").and_then(Value::as_str) != Some("opencodex") {
+        return None;
+    }
+    let pid = u32::try_from(body.get("pid").and_then(Value::as_u64)?).ok()?;
+    let port = u16::try_from(body.get("port").and_then(Value::as_u64)?).ok()?;
+    if port != addressed_port {
+        return None;
+    }
+    Some(RuntimeIdentity { pid, port })
+}
+
+impl ProxyClient {
+    pub fn new(endpoint: ProxyEndpoint, auth: Auth) -> Result<Self, reqwest::Error> {
+        Ok(Self {
+            client: Client::builder()
+                .timeout(Duration::from_secs(4))
+                .user_agent(Auth::user_agent())
+                // The admin token attached to these requests is for the loopback endpoint and
+                // nowhere else. Two defaults would carry it off that endpoint, so both are turned
+                // off here rather than re-checked anywhere in the request path.
+                //
+                // A redirect is the first: the pinned client does not treat this custom credential
+                // header as sensitive, so it would follow the hop to wherever it pointed.
+                .redirect(redirect::Policy::none())
+                // System proxy resolution is the second: reqwest honours system proxy
+                // configuration by default, which would route the credential through whatever
+                // proxy the machine declares and put another process between the shell and its
+                // own runtime.
+                .no_proxy()
+                .build()?,
+            endpoint,
+            auth,
+            binding: Arc::new(Mutex::new(None)),
+            generations: Arc::new(Mutex::new(0)),
+        })
+    }
+
+    pub fn endpoint(&self) -> ProxyEndpoint {
+        self.endpoint
+    }
+
+    fn slot<T>(lock: &Mutex<T>) -> MutexGuard<'_, T> {
+        lock.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// Bind this client to an instance, and return the binding it is now on.
+    pub fn bind(&self, identity: RuntimeIdentity) -> RuntimeBinding {
+        let mut generations = Self::slot(&self.generations);
+        *generations += 1;
+        let binding = RuntimeBinding {
+            identity,
+            generation: *generations,
+        };
+        *Self::slot(&self.binding) = Some(binding);
+        binding
+    }
+
+    pub fn binding(&self) -> Option<RuntimeBinding> {
+        *Self::slot(&self.binding)
+    }
+
+    /// Ask the endpoint who it is, without sending anything secret.
+    pub async fn identify(&self) -> Result<RuntimeIdentity, ProxyError> {
+        let response = self.send(&Method::GET, "/healthz", None).await?;
+        let body = decode(response).await?;
+        identity_from(&body, self.endpoint.port).ok_or(ProxyError::Foreign)
+    }
+
+    pub async fn is_alive(&self) -> Result<Value, ProxyError> {
+        self.get("/healthz").await
+    }
+
+    /// A health probe that cannot outlive the caller's deadline.
+    ///
+    /// The client's own timeout is per request and knows nothing about the budget the caller is
+    /// working to. A probe started a moment before a deadline would otherwise overrun it by that
+    /// whole timeout, which is how a stated 30-second startup ceiling quietly becomes 34.
+    /// `None` means the deadline arrived first.
+    pub async fn alive_within(&self, deadline: Instant) -> Option<Result<Value, ProxyError>> {
+        timeout_at(deadline, self.is_alive()).await.ok()
+    }
+
+    pub async fn companion_settings(&self) -> Result<Value, ProxyError> {
+        self.get("/api/companion/settings").await
+    }
+
+    pub async fn usage_summary(&self) -> Result<Value, ProxyError> {
+        self.get("/api/usage?range=7d").await
+    }
+
+    pub async fn usage_today(&self) -> Result<Value, ProxyError> {
+        self.get("/api/usage?range=today").await
+    }
+
+    pub async fn startup_health(&self) -> Result<Value, ProxyError> {
+        self.get("/api/startup-health").await
+    }
+
+    pub async fn quotas(&self) -> Result<Value, ProxyError> {
+        self.get("/api/provider-quotas").await
+    }
+
+    pub async fn timeline(&self, query: &str) -> Result<Value, ProxyError> {
+        self.get(&format!("/api/usage/timeline?{query}")).await
+    }
+
+    async fn get(&self, path: &str) -> Result<Value, ProxyError> {
+        self.request(Method::GET, path).await
+    }
+
+    async fn request(&self, method: Method, path: &str) -> Result<Value, ProxyError> {
+        let response = self.send(&method, path, None).await?;
+        if response.status() == StatusCode::UNAUTHORIZED {
+            let token = self.authorised_token().await?;
+            let response = self.send(&method, path, Some(token)).await?;
+            return decode(response).await;
+        }
+        decode(response).await
+    }
+
+    /// The management token, but only for the instance this client is bound to.
+    ///
+    /// The binding is re-confirmed here rather than trusted from when it was made: between then and
+    /// now the child can have exited and something else can hold the port. A request is therefore
+    /// bound to a pid, a port and the generation the shell authorised, and a mismatch is refused
+    /// instead of being sent the credential.
+    async fn authorised_token(&self) -> Result<String, ProxyError> {
+        let Some(binding) = self.binding() else {
+            return Err(ProxyError::Unauthorized);
+        };
+        let identity = self.identify().await?;
+        if identity != binding.identity {
+            return Err(ProxyError::Foreign);
+        }
+        if self.binding() != Some(binding) {
+            return Err(ProxyError::Foreign);
+        }
+        self.auth.token().ok_or(ProxyError::Unauthorized)
+    }
+
+    async fn send(
+        &self,
+        method: &Method,
+        path: &str,
+        token: Option<String>,
+    ) -> Result<reqwest::Response, ProxyError> {
+        let mut request = self.client.request(method.clone(), self.endpoint.url(path));
+        if let Some(value) = token {
+            request = request.header("X-OpenCodex-API-Key", value);
+        }
+        request.send().await.map_err(|error| {
+            if error.is_connect() {
+                ProxyError::Unreachable
+            } else {
+                ProxyError::Decode(error)
+            }
+        })
+    }
+}
+
+async fn decode(response: reqwest::Response) -> Result<Value, ProxyError> {
+    if response.status() == StatusCode::UNAUTHORIZED {
+        return Err(ProxyError::Unauthorized);
+    }
+    if !response.status().is_success() {
+        return Err(ProxyError::Http(response.status()));
+    }
+    response.json().await.map_err(ProxyError::Decode)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{identity_from, RuntimeIdentity};
+    use serde_json::json;
+
+    #[test]
+    fn a_health_body_without_the_marker_is_not_this_proxy() {
+        let body = json!({ "status": "ok", "pid": 42, "port": 10100 });
+        assert!(identity_from(&body, 10100).is_none());
+        let foreign = json!({ "service": "something-else", "pid": 42, "port": 10100 });
+        assert!(identity_from(&foreign, 10100).is_none());
+    }
+
+    #[test]
+    fn the_body_has_to_describe_the_listener_that_was_addressed() {
+        let body = json!({ "service": "opencodex", "pid": 42, "port": 10101 });
+        assert!(identity_from(&body, 10100).is_none());
+    }
+
+    #[test]
+    fn a_complete_body_identifies_the_instance() {
+        let body = json!({ "service": "opencodex", "version": "2.61.0", "pid": 42, "port": 10100 });
+        assert_eq!(
+            identity_from(&body, 10100),
+            Some(RuntimeIdentity {
+                pid: 42,
+                port: 10100
+            })
+        );
+    }
+
+    #[test]
+    fn a_body_missing_the_instance_facts_identifies_nothing() {
+        assert!(identity_from(&json!({ "service": "opencodex", "port": 10100 }), 10100).is_none());
+        assert!(identity_from(&json!({ "service": "opencodex", "pid": 42 }), 10100).is_none());
+    }
+}
diff --git a/desktop/src-tauri/src/resolve.rs b/desktop/src-tauri/src/resolve.rs
new file mode 100644
index 00000000000..8172006d0ff
--- /dev/null
+++ b/desktop/src-tauri/src/resolve.rs
@@ -0,0 +1,329 @@
+//! What the bundled CLI says about this machine's runtime.
+//!
+//! D5: the shell stops resolving the configuration home, the port and liveness itself. It used to,
+//! in a file called `discovery.rs` that read `runtime-port.json`, fell back to 10100 and started on
+//! that port — so a user with a configured `config.port` was started somewhere else. The tuned probe
+//! budgets it should have been using exist because a shell-side reimplementation answered "nobody is
+//! listening" twice and started duplicate proxies. This asks instead.
+//!
+//! Liveness has three answers and the third one is the point. `live` means attach. `absent-proven`
+//! means every recorded and configured endpoint was definitively dead, and only that authorises
+//! starting a runtime. Anything else is unknown, and the CLI exits 1 rather than putting absence on
+//! the wire. Everything that can go wrong on this side — a missing binary, a timeout, output that
+//! will not parse, a schema this shell does not know — folds into the same unknown, because the one
+//! reading that must never happen is "the resolve failed, so nobody must be listening".
+
+use crate::endpoint::ProxyEndpoint;
+use serde::Deserialize;
+use std::path::PathBuf;
+use tauri::AppHandle;
+use tauri_plugin_shell::ShellExt;
+use tokio::time::{timeout_at, Instant};
+
+/// The wire version this shell understands. A document announcing anything else is unknown.
+pub const SCHEMA: &str = "ocx-resolve/1";
+
+/// The CLI's liveness verdict. Only two reach the wire; the third exits 1.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Status {
+    Live,
+    AbsentProven,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Liveness {
+    pub status: Status,
+    pub pid: Option<u32>,
+    pub port: Option<u16>,
+    /// The bind address that answered. Absent on a proven absence, because nothing answered.
+    pub hostname: Option<String>,
+    pub version: Option<String>,
+    pub role: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Port {
+    /// The port a client should use: the live listener's, or the configured one.
+    pub effective: u16,
+    /// What a start would prefer.
+    pub configured: u16,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Resolved {
+    pub schema: String,
+    pub cli_version: String,
+    pub config_home: String,
+    pub port: Port,
+    pub liveness: Liveness,
+}
+
+impl Resolved {
+    pub fn endpoint(&self) -> ProxyEndpoint {
+        ProxyEndpoint {
+            host: "127.0.0.1",
+            port: self.port.effective,
+        }
+    }
+
+    pub fn home(&self) -> PathBuf {
+        PathBuf::from(&self.config_home)
+    }
+}
+
+/// What the shell got back.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Resolution {
+    /// The CLI produced a verdict this shell trusts.
+    Answered(Box<Resolved>),
+    /// It did not, for whatever reason. Never read as absence.
+    Unknown(String),
+}
+
+impl Resolution {
+    pub fn resolved(&self) -> Option<&Resolved> {
+        match self {
+            Self::Answered(resolved) => Some(resolved.as_ref()),
+            Self::Unknown(_) => None,
+        }
+    }
+
+    pub fn reason(&self) -> Option<&str> {
+        match self {
+            Self::Unknown(reason) => Some(reason),
+            Self::Answered(_) => None,
+        }
+    }
+}
+
+/// Whether the shell may start a runtime of its own.
+///
+/// Proven absence and nothing else. `live` means attach to what is there, and unknown means refuse:
+/// a resolution that could not be trusted must never read as "nobody is listening", which is the
+/// reading that puts a second proxy next to the one already running.
+pub fn may_start(resolution: &Resolution) -> bool {
+    matches!(
+        resolution
+            .resolved()
+            .map(|resolved| resolved.liveness.status),
+        Some(Status::AbsentProven)
+    )
+}
+
+/// What the shell may do with a listener the CLI found alive.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum LiveVerdict {
+    /// Nothing is listening; this verdict does not apply.
+    NotLive,
+    /// It is a proxy, on an address this shell can reach. Attach as a guest.
+    Attach,
+    /// Something is listening and this shell cannot use it. Never a reason to start a second one.
+    Unusable(String),
+}
+
+/// Whether the address the CLI reported is one this shell can reach on loopback.
+///
+/// The shell speaks to loopback and nothing else — that is what makes sending the management token
+/// to it safe. A proxy bound to either loopback spelling, or to every interface, is reachable at
+/// 127.0.0.1. One bound to the IPv6 loopback or to a specific external address is not, and
+/// addressing 127.0.0.1 anyway would turn a running proxy into a health wait that times out.
+pub fn loopback_reachable(hostname: Option<&str>) -> bool {
+    matches!(
+        hostname,
+        None | Some("127.0.0.1") | Some("localhost") | Some("0.0.0.0")
+    )
+}
+
+/// Read a live verdict.
+///
+/// Liveness answers "is something there", and core's predicate accepts a connected client's
+/// listener on purpose so duplicate-start avoidance can see it. This shell needs the management
+/// plane, so it has to discriminate on the role the CLI carried: a client listener serves machine
+/// routes, not `/api/*`, and attaching to it would report Ready against an endpoint the dashboard
+/// and the tray cannot use.
+pub fn live_verdict(resolution: &Resolution) -> LiveVerdict {
+    let Some(resolved) = resolution.resolved() else {
+        return LiveVerdict::NotLive;
+    };
+    if resolved.liveness.status != Status::Live {
+        return LiveVerdict::NotLive;
+    }
+    if resolved.liveness.role.as_deref() == Some("client") {
+        return LiveVerdict::Unusable(
+            "a connected client is listening on this port, not a proxy this app can manage".into(),
+        );
+    }
+    if !loopback_reachable(resolved.liveness.hostname.as_deref()) {
+        return LiveVerdict::Unusable(format!(
+            "the runtime is bound to {} and this app only speaks to loopback",
+            resolved
+                .liveness
+                .hostname
+                .as_deref()
+                .unwrap_or("an unknown address")
+        ));
+    }
+    LiveVerdict::Attach
+}
+
+/// Read one resolve document, refusing anything that is not exactly one.
+///
+/// The CLI puts the document on stdout and its human output on stderr, so stdout is parsed whole.
+/// A non-zero exit is the CLI's own refusal — including the exit 1 it uses for unknown liveness and
+/// for a config it will not guess at — and is carried through rather than reinterpreted here.
+pub fn read(exit_code: Option<i32>, stdout: &[u8], stderr: &[u8]) -> Resolution {
+    if exit_code != Some(0) {
+        let detail = String::from_utf8_lossy(stderr);
+        let detail = detail.trim();
+        let code = exit_code
+            .map(|code| code.to_string())
+            .unwrap_or_else(|| "no exit code".to_owned());
+        return Resolution::Unknown(if detail.is_empty() {
+            format!("the bundled CLI could not resolve the runtime (exit {code})")
+        } else {
+            format!("the bundled CLI could not resolve the runtime (exit {code}): {detail}")
+        });
+    }
+    let text = String::from_utf8_lossy(stdout);
+    let resolved: Resolved = match serde_json::from_str(text.trim()) {
+        Ok(resolved) => resolved,
+        Err(error) => {
+            return Resolution::Unknown(format!(
+                "the bundled CLI's resolve output could not be read ({error})"
+            ))
+        }
+    };
+    if resolved.schema != SCHEMA {
+        return Resolution::Unknown(format!(
+            "the bundled CLI answered with schema {} and this app understands {SCHEMA}",
+            resolved.schema
+        ));
+    }
+    Resolution::Answered(Box::new(resolved))
+}
+
+/// Ask the bundled CLI, under the caller's deadline.
+pub async fn run(app: &AppHandle, deadline: Instant) -> Resolution {
+    let command = match app.shell().sidecar("ocx") {
+        Ok(command) => command.args(["resolve", "--json"]),
+        Err(error) => {
+            return Resolution::Unknown(format!("the bundled CLI could not be started ({error})"))
+        }
+    };
+    match timeout_at(deadline, command.output()).await {
+        Ok(Ok(output)) => read(output.status.code(), &output.stdout, &output.stderr),
+        Ok(Err(error)) => {
+            Resolution::Unknown(format!("the bundled CLI could not be run ({error})"))
+        }
+        Err(_) => Resolution::Unknown(
+            "the bundled CLI did not answer before the startup deadline".to_owned(),
+        ),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        live_verdict, loopback_reachable, may_start, read, LiveVerdict, Resolution, Status, SCHEMA,
+    };
+
+    const LIVE: &str = r#"{"schema":"ocx-resolve/1","cliVersion":"2.61.0","configHome":"/h",
+        "port":{"effective":10100,"configured":10100,"source":"runtime-record"},
+        "liveness":{"status":"live","pid":42,"port":10100,"source":"runtime-record","version":"2.61.0"}}"#;
+    const ABSENT: &str = r#"{"schema":"ocx-resolve/1","cliVersion":"2.61.0","configHome":"/h",
+        "port":{"effective":10100,"configured":10100,"source":"config"},
+        "liveness":{"status":"absent-proven","pid":null,"port":null,"source":null}}"#;
+
+    #[test]
+    fn a_live_verdict_is_read_whole() {
+        let resolution = read(Some(0), LIVE.as_bytes(), b"");
+        let resolved = resolution.resolved().expect("a document");
+        assert_eq!(resolved.schema, SCHEMA);
+        assert_eq!(resolved.liveness.status, Status::Live);
+        assert_eq!(resolved.liveness.pid, Some(42));
+        assert_eq!(resolved.endpoint().port, 10100);
+        assert_eq!(resolved.home().display().to_string(), "/h");
+        assert_eq!(live_verdict(&resolution), LiveVerdict::Attach);
+        assert!(!may_start(&resolution));
+    }
+
+    #[test]
+    fn only_a_proven_absence_authorises_a_start() {
+        let resolution = read(Some(0), ABSENT.as_bytes(), b"");
+        assert_eq!(
+            resolution.resolved().map(|r| r.liveness.status),
+            Some(Status::AbsentProven)
+        );
+        assert!(may_start(&resolution));
+        assert_eq!(live_verdict(&resolution), LiveVerdict::NotLive);
+    }
+
+    #[test]
+    fn a_connected_client_is_live_but_not_a_runtime_to_attach_to() {
+        let client = LIVE.replace(
+            r#""version":"2.61.0""#,
+            r#""version":"2.61.0","role":"client""#,
+        );
+        let resolution = read(Some(0), client.as_bytes(), b"");
+        assert!(matches!(
+            live_verdict(&resolution),
+            LiveVerdict::Unusable(_)
+        ));
+        // Live and unusable is still live: it is never a reason to start a second one.
+        assert!(!may_start(&resolution));
+    }
+
+    #[test]
+    fn only_a_loopback_bind_is_addressed_as_loopback() {
+        for reachable in [None, Some("127.0.0.1"), Some("localhost"), Some("0.0.0.0")] {
+            assert!(loopback_reachable(reachable), "{reachable:?}");
+        }
+        for elsewhere in [Some("::1"), Some("192.168.1.10"), Some("example.internal")] {
+            assert!(!loopback_reachable(elsewhere), "{elsewhere:?}");
+        }
+        let bound = LIVE.replace(r#""pid":42"#, r#""pid":42,"hostname":"::1""#);
+        let resolution = read(Some(0), bound.as_bytes(), b"");
+        assert!(matches!(
+            live_verdict(&resolution),
+            LiveVerdict::Unusable(_)
+        ));
+        assert!(!may_start(&resolution));
+    }
+
+    #[test]
+    fn the_clis_own_refusal_is_unknown_and_never_authorises_a_start() {
+        // Exit 1 is what the CLI uses for unknown liveness and for a config it will not guess at.
+        let resolution = read(Some(1), b"", b"resolve: liveness is unknown");
+        assert!(matches!(resolution, Resolution::Unknown(_)));
+        assert!(resolution.reason().unwrap().contains("liveness is unknown"));
+        assert!(!may_start(&resolution));
+        assert_eq!(live_verdict(&resolution), LiveVerdict::NotLive);
+    }
+
+    #[test]
+    fn everything_that_can_go_wrong_here_folds_into_unknown() {
+        for (code, out) in [
+            (Some(64), &b""[..]),
+            (None, &b""[..]),
+            (Some(0), &b"not json"[..]),
+            (Some(0), &b"{}"[..]),
+        ] {
+            let resolution = read(code, out, b"");
+            assert!(matches!(resolution, Resolution::Unknown(_)), "{code:?}");
+            assert!(!may_start(&resolution));
+        }
+    }
+
+    #[test]
+    fn a_schema_this_app_does_not_know_is_unknown() {
+        let future = LIVE.replace("ocx-resolve/1", "ocx-resolve/2");
+        let resolution = read(Some(0), future.as_bytes(), b"");
+        assert!(matches!(resolution, Resolution::Unknown(_)));
+        assert!(resolution.reason().unwrap().contains("ocx-resolve/2"));
+        assert!(!may_start(&resolution));
+    }
+}
diff --git a/desktop/src-tauri/src/runtime_stop.rs b/desktop/src-tauri/src/runtime_stop.rs
new file mode 100644
index 00000000000..c4099b8304b
--- /dev/null
+++ b/desktop/src-tauri/src/runtime_stop.rs
@@ -0,0 +1,306 @@
+//! Stopping a runtime through the bundled CLI.
+//!
+//! D4: the shell drives the real `ocx stop` as a child process, so the receipt-backed teardown, the
+//! drain, the Windows respawn verification and the client-configuration restore all run exactly as
+//! they do from a terminal. An in-process management call cannot own that teardown — launchd and
+//! systemd can terminate the request handler during self-unload, and the Windows respawn window can
+//! only be verified after the process exits — so the shell reads the run's result instead of
+//! performing it.
+//!
+//! The result is a document, not a guess. `ocx stop --json` puts one summary on stdout and its
+//! human output on stderr, and this consumes the outcome and the exit code rather than inferring
+//! either. A stop that did not end in exit 0 with the runtime down is a stop that did not happen.
+
+use serde::Deserialize;
+use std::time::Duration;
+use tauri::AppHandle;
+use tauri_plugin_shell::ShellExt;
+use tokio::time::{timeout_at, Instant};
+
+/// The wire version this shell understands.
+pub const SCHEMA: &str = "ocx-stop/1";
+
+/// How long the stop may take.
+///
+/// The CLI's stop drains in-flight requests, restores client configuration and verifies the Windows
+/// respawn window, so this is generous on purpose: it bounds a hang, it does not pace a healthy
+/// stop. Overrunning it is a failure, not a stop, because the caller's next step is to end the app
+/// or replace the files the runtime is serving out of.
+pub const DEADLINE: Duration = Duration::from_secs(30);
+
+/// The outcomes the CLI can report. An outcome this shell does not know fails to parse, which is
+/// the same answer as a stop that did not happen.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Outcome {
+    Stopped,
+    NotRunning,
+    HistoryIncomplete,
+    HistoryDeferred,
+    Failed,
+}
+
+impl Outcome {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Stopped => "stopped",
+            Self::NotRunning => "not-running",
+            Self::HistoryIncomplete => "history-incomplete",
+            Self::HistoryDeferred => "history-deferred",
+            Self::Failed => "failed",
+        }
+    }
+}
+
+/// How the proxy half of the stop ended.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Proxy {
+    Stopped,
+    StoppedOrphan,
+    NotRunning,
+    StopFailed,
+    OwnershipRefused,
+    UnresolvablePid,
+    Respawned,
+    Unknown,
+}
+
+impl Proxy {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Stopped => "stopped",
+            Self::StoppedOrphan => "stopped-orphan",
+            Self::NotRunning => "not-running",
+            Self::StopFailed => "stop-failed",
+            Self::OwnershipRefused => "ownership-refused",
+            Self::UnresolvablePid => "unresolvable-pid",
+            Self::Respawned => "respawned",
+            Self::Unknown => "unknown",
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct StopSummary {
+    pub schema: String,
+    /// Strict exit-code view: true only for exit 0.
+    pub ok: bool,
+    pub outcome: Outcome,
+    pub exit_code: i32,
+    /// True when this stop left no proxy of this home running by its own paths.
+    pub runtime_down: bool,
+    pub proxy: Proxy,
+    pub message: String,
+}
+
+/// What the shell concluded.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum StopResult {
+    /// The CLI reported a clean stop and a runtime that is down.
+    Stopped(StopSummary),
+    /// It reported anything else, or the run could not be read at all.
+    Failed(String),
+}
+
+impl StopResult {
+    pub fn is_stopped(&self) -> bool {
+        matches!(self, Self::Stopped(_))
+    }
+
+    pub fn describe(&self) -> String {
+        match self {
+            Self::Stopped(summary) => summary.message.clone(),
+            Self::Failed(reason) => reason.clone(),
+        }
+    }
+}
+
+/// Read one stop summary.
+///
+/// Five facts have to hold together, and no four of them are enough.
+///
+/// The process has to have exited 0, and the document has to say so too: `ok` is the strict
+/// exit-code view and `exitCode` is the number behind it, so 1, 79 and 80 are refusals however the
+/// rest of the document reads. Reading only the document would take a run's word for its own exit
+/// status; reading only the status would accept a summary that disagrees with it. And `runtimeDown`
+/// is the CLI's own statement that no proxy of this home is left running — a service that failed
+/// while the proxy happened to stop satisfies that and not the others, and it is exactly the case
+/// that may respawn the runtime a moment later.
+///
+/// The fifth is that the document agrees with itself. The CLI's own summarizer cannot emit a
+/// `failed` outcome beside a `stopped` proxy, but a reader that assumes that is trusting a
+/// document to be self-consistent rather than checking. Only the two shapes that mean a runtime is
+/// down are accepted, and an outcome or a proxy state this shell does not know fails to parse —
+/// which is the same answer as a stop that did not happen.
+pub fn read(exit_code: Option<i32>, stdout: &[u8], stderr: &[u8]) -> StopResult {
+    let text = String::from_utf8_lossy(stdout);
+    let summary: StopSummary = match serde_json::from_str(text.trim()) {
+        Ok(summary) => summary,
+        Err(error) => {
+            let detail = String::from_utf8_lossy(stderr);
+            let detail = detail.trim();
+            let code = exit_code
+                .map(|code| code.to_string())
+                .unwrap_or_else(|| "no exit code".to_owned());
+            return StopResult::Failed(if detail.is_empty() {
+                format!("the bundled CLI's stop output could not be read (exit {code}: {error})")
+            } else {
+                format!("the bundled CLI's stop output could not be read (exit {code}): {detail}")
+            });
+        }
+    };
+    if summary.schema != SCHEMA {
+        return StopResult::Failed(format!(
+            "the bundled CLI answered with schema {} and this app understands {SCHEMA}",
+            summary.schema
+        ));
+    }
+    let agrees = matches!(
+        (summary.outcome, summary.proxy),
+        (Outcome::Stopped, Proxy::Stopped)
+            | (Outcome::Stopped, Proxy::StoppedOrphan)
+            | (Outcome::NotRunning, Proxy::NotRunning)
+    );
+    if exit_code != Some(0)
+        || !summary.ok
+        || summary.exit_code != 0
+        || !summary.runtime_down
+        || !agrees
+    {
+        return StopResult::Failed(format!(
+            "{} (outcome {}, proxy {}, exit {}, process exit {})",
+            summary.message,
+            summary.outcome.as_str(),
+            summary.proxy.as_str(),
+            summary.exit_code,
+            exit_code
+                .map(|code| code.to_string())
+                .unwrap_or_else(|| "none".to_owned())
+        ));
+    }
+    StopResult::Stopped(summary)
+}
+
+/// Run the bundled `ocx stop --json`, under the caller's deadline.
+pub async fn run(app: &AppHandle, deadline: Instant) -> StopResult {
+    let command = match app.shell().sidecar("ocx") {
+        Ok(command) => command.args(["stop", "--json"]),
+        Err(error) => {
+            return StopResult::Failed(format!("the bundled CLI could not be started ({error})"))
+        }
+    };
+    match timeout_at(deadline, command.output()).await {
+        Ok(Ok(output)) => read(output.status.code(), &output.stdout, &output.stderr),
+        Ok(Err(error)) => StopResult::Failed(format!("the bundled CLI could not be run ({error})")),
+        Err(_) => {
+            StopResult::Failed("the bundled CLI did not finish stopping before the deadline".into())
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{read, Outcome, Proxy, StopResult, SCHEMA};
+
+    fn document(ok: bool, outcome: &str, exit: i32, down: bool, proxy: &str) -> String {
+        format!(
+            r#"{{"schema":"ocx-stop/1","ok":{ok},"outcome":"{outcome}","exitCode":{exit},
+               "runtimeDown":{down},"service":"absent","proxy":"{proxy}",
+               "sharedTeardown":"restored","message":"a message"}}"#
+        )
+    }
+
+    #[test]
+    fn a_clean_stop_with_the_runtime_down_is_the_only_success() {
+        let ok = document(true, "stopped", 0, true, "stopped");
+        let result = read(Some(0), ok.as_bytes(), b"");
+        assert!(result.is_stopped());
+        match result {
+            StopResult::Stopped(summary) => {
+                assert_eq!(summary.schema, SCHEMA);
+                assert_eq!(summary.outcome, Outcome::Stopped);
+                assert_eq!(summary.proxy, Proxy::Stopped);
+                assert!(summary.runtime_down);
+            }
+            StopResult::Failed(reason) => panic!("{reason}"),
+        }
+        // Nothing was running is equally a runtime that is down.
+        assert!(read(
+            Some(0),
+            document(true, "not-running", 0, true, "not-running").as_bytes(),
+            b""
+        )
+        .is_stopped());
+    }
+
+    #[test]
+    fn a_non_zero_exit_is_never_folded_into_success() {
+        // 79 and 80 report a proxy that went down with an obligation still owed. The runtime may
+        // be down, but the run did not succeed, and an update must not install over it.
+        for (outcome, exit) in [
+            ("history-incomplete", 79),
+            ("history-deferred", 80),
+            ("failed", 1),
+        ] {
+            let document = document(false, outcome, exit, true, "stopped");
+            let result = read(Some(exit), document.as_bytes(), b"");
+            assert!(!result.is_stopped(), "{outcome}");
+            assert!(result.describe().contains(outcome));
+        }
+    }
+
+    #[test]
+    fn the_process_status_and_the_document_have_to_agree() {
+        let clean = document(true, "stopped", 0, true, "stopped");
+        // A run that exited non-zero is a refusal even when its summary reads clean: taking the
+        // document's word for its own exit status is taking one claim as evidence of itself.
+        assert!(!read(Some(1), clean.as_bytes(), b"").is_stopped());
+        assert!(!read(None, clean.as_bytes(), b"").is_stopped());
+        // And a summary that contradicts its own exit code is not a stop either.
+        let contradictory = document(true, "stopped", 1, true, "stopped");
+        assert!(!read(Some(0), contradictory.as_bytes(), b"").is_stopped());
+    }
+
+    #[test]
+    fn a_document_that_contradicts_itself_is_not_a_stop() {
+        // The CLI's summarizer cannot emit this, and the reader does not assume that.
+        let mixed = document(true, "failed", 0, true, "respawned");
+        assert!(!read(Some(0), mixed.as_bytes(), b"").is_stopped());
+        let orphan = document(true, "stopped", 0, true, "stopped-orphan");
+        assert!(read(Some(0), orphan.as_bytes(), b"").is_stopped());
+        // An outcome or a proxy state this shell does not know is not read at all.
+        let future = document(true, "stopped", 0, true, "stopped")
+            .replace("\"proxy\":\"stopped\"", "\"proxy\":\"parked\"");
+        assert!(!read(Some(0), future.as_bytes(), b"").is_stopped());
+    }
+
+    #[test]
+    fn a_runtime_still_up_is_a_failure_however_the_exit_reads() {
+        for proxy in [
+            "respawned",
+            "stop-failed",
+            "ownership-refused",
+            "unresolvable-pid",
+        ] {
+            let document = document(true, "stopped", 0, false, proxy);
+            assert!(
+                !read(Some(0), document.as_bytes(), b"").is_stopped(),
+                "{proxy}"
+            );
+        }
+    }
+
+    #[test]
+    fn output_that_cannot_be_read_is_a_failure_not_a_stop() {
+        assert!(!read(Some(0), b"", b"boom").is_stopped());
+        assert!(!read(Some(0), b"not json", b"").is_stopped());
+        assert!(!read(None, b"", b"").is_stopped());
+        let future =
+            document(true, "stopped", 0, true, "stopped").replace("ocx-stop/1", "ocx-stop/2");
+        let result = read(Some(0), future.as_bytes(), b"");
+        assert!(!result.is_stopped());
+        assert!(result.describe().contains("ocx-stop/2"));
+    }
+}
diff --git a/desktop/src-tauri/src/sidecar.rs b/desktop/src-tauri/src/sidecar.rs
new file mode 100644
index 00000000000..2a1da6e90c7
--- /dev/null
+++ b/desktop/src-tauri/src/sidecar.rs
@@ -0,0 +1,226 @@
+//! Starting and watching the runtime this app owns.
+//!
+//! The spawn event stream used to be discarded into `_events`, which is why a sidecar that exited
+//! immediately — a binary built for a CPU instruction set this machine does not have, a port
+//! already taken, a corrupt install — presented as the same generic health failure as a slow start.
+//! The child's exit code and its last output were both available and both thrown away. They are
+//! consumed here instead, and they are what the startup diagnostic is made of.
+//!
+//! Stopping it is not here. D4 gives that to the bundled `ocx stop`, which owns the receipt-backed
+//! teardown this process cannot perform on itself; see `runtime_stop.rs`.
+
+use crate::endpoint::ProxyEndpoint;
+use std::{
+    collections::VecDeque,
+    sync::{Arc, Mutex},
+};
+use tauri::{async_runtime::Receiver, AppHandle, Manager};
+use tauri_plugin_shell::{
+    process::{CommandChild, CommandEvent},
+    ShellExt,
+};
+/// How much sidecar output the diagnostic keeps. Enough to carry a stack trace or a startup
+/// refusal, bounded so a chatty runtime cannot grow the buffer for the life of the process.
+const MAX_LINES: usize = 40;
+
+/// How the sidecar process ended.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct SidecarExit {
+    pub code: Option<i32>,
+    pub signal: Option<i32>,
+}
+
+impl SidecarExit {
+    pub fn describe(&self) -> String {
+        match (self.code, self.signal) {
+            (Some(code), _) => format!("exit code {code}"),
+            (None, Some(signal)) => format!("terminated by signal {signal}"),
+            (None, None) => "exited without reporting a code".to_owned(),
+        }
+    }
+}
+
+/// One thing the spawned child told us.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum SidecarEvent {
+    Line(String),
+    Exited(SidecarExit),
+}
+
+#[derive(Default)]
+struct WatchInner {
+    lines: VecDeque<String>,
+    exit: Option<SidecarExit>,
+}
+
+impl WatchInner {
+    fn record(&mut self, event: SidecarEvent) {
+        match event {
+            SidecarEvent::Line(line) => {
+                let line = line.trim_end().to_owned();
+                if line.is_empty() {
+                    return;
+                }
+                if self.lines.len() == MAX_LINES {
+                    self.lines.pop_front();
+                }
+                self.lines.push_back(line);
+            }
+            SidecarEvent::Exited(exit) => self.exit = Some(exit),
+        }
+    }
+}
+
+/// The consumed spawn event stream of the child this app started.
+#[derive(Clone, Default)]
+pub struct SidecarWatch {
+    inner: Arc<Mutex<WatchInner>>,
+}
+
+impl SidecarWatch {
+    pub fn record(&self, event: SidecarEvent) {
+        if let Ok(mut inner) = self.inner.lock() {
+            inner.record(event);
+        }
+    }
+
+    pub fn exit(&self) -> Option<SidecarExit> {
+        self.inner.lock().ok().and_then(|inner| inner.exit)
+    }
+
+    pub fn lines(&self) -> Vec<String> {
+        self.inner
+            .lock()
+            .map(|inner| inner.lines.iter().cloned().collect())
+            .unwrap_or_default()
+    }
+
+    /// Forget the previous attempt so a retry's diagnostic describes the retry.
+    pub fn reset(&self) {
+        if let Ok(mut inner) = self.inner.lock() {
+            inner.lines.clear();
+            inner.exit = None;
+        }
+    }
+
+    /// Drain the spawn event stream into this record for as long as the child lives.
+    pub fn follow(&self, mut events: Receiver<CommandEvent>) {
+        let watch = self.clone();
+        tauri::async_runtime::spawn(async move {
+            while let Some(event) = events.recv().await {
+                if let Some(event) = translate(event) {
+                    watch.record(event);
+                }
+            }
+        });
+    }
+}
+
+fn translate(event: CommandEvent) -> Option<SidecarEvent> {
+    match event {
+        CommandEvent::Stdout(bytes) | CommandEvent::Stderr(bytes) => Some(SidecarEvent::Line(
+            String::from_utf8_lossy(&bytes).into_owned(),
+        )),
+        CommandEvent::Error(message) => Some(SidecarEvent::Line(format!("error: {message}"))),
+        CommandEvent::Terminated(payload) => Some(SidecarEvent::Exited(SidecarExit {
+            code: payload.code,
+            signal: payload.signal,
+        })),
+        _ => None,
+    }
+}
+
+/// Start the bundled runtime and begin consuming what it says.
+///
+/// The port is still passed explicitly. D5 hands that resolution to the bundled CLI so a user on a
+/// custom `config.port` is not started on a different one; this is the call site that changes when
+/// lane A's resolve verb lands, and nothing else here depends on where the number came from.
+pub fn start(
+    app: &AppHandle,
+    endpoint: ProxyEndpoint,
+    watch: &SidecarWatch,
+) -> Result<CommandChild, String> {
+    let gui_dist = app
+        .path()
+        .resource_dir()
+        .map_err(|error| error.to_string())?
+        .join("gui")
+        .join("dist");
+    let command = app
+        .shell()
+        .sidecar("ocx")
+        .map_err(|error| error.to_string())?
+        .args(["start", "--port", &endpoint.port.to_string()])
+        .env("OPENCODEX_GUI_DIST", gui_dist);
+    let (events, child) = command.spawn().map_err(|error| error.to_string())?;
+    watch.follow(events);
+    Ok(child)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{SidecarEvent, SidecarExit, SidecarWatch, MAX_LINES};
+
+    #[test]
+    fn the_exit_code_survives_the_event_stream() {
+        let watch = SidecarWatch::default();
+        watch.record(SidecarEvent::Line("listening on 10100".into()));
+        watch.record(SidecarEvent::Exited(SidecarExit {
+            code: Some(1),
+            signal: None,
+        }));
+        assert_eq!(watch.exit().and_then(|exit| exit.code), Some(1));
+        assert_eq!(watch.lines(), vec!["listening on 10100".to_owned()]);
+    }
+
+    #[test]
+    fn output_is_bounded_and_keeps_the_end() {
+        let watch = SidecarWatch::default();
+        for index in 0..(MAX_LINES + 5) {
+            watch.record(SidecarEvent::Line(format!("line {index}")));
+        }
+        let lines = watch.lines();
+        assert_eq!(lines.len(), MAX_LINES);
+        assert_eq!(lines.first().unwrap(), "line 5");
+        assert_eq!(lines.last().unwrap(), &format!("line {}", MAX_LINES + 4));
+    }
+
+    #[test]
+    fn blank_output_is_not_recorded_and_a_reset_forgets_the_attempt() {
+        let watch = SidecarWatch::default();
+        watch.record(SidecarEvent::Line("   \n".into()));
+        assert!(watch.lines().is_empty());
+        watch.record(SidecarEvent::Line("boom".into()));
+        watch.record(SidecarEvent::Exited(SidecarExit {
+            code: None,
+            signal: Some(9),
+        }));
+        watch.reset();
+        assert!(watch.lines().is_empty());
+        assert!(watch.exit().is_none());
+    }
+
+    #[test]
+    fn an_exit_reads_as_a_code_a_signal_or_neither() {
+        assert_eq!(
+            SidecarExit {
+                code: Some(2),
+                signal: None
+            }
+            .describe(),
+            "exit code 2"
+        );
+        assert_eq!(
+            SidecarExit {
+                code: None,
+                signal: Some(9)
+            }
+            .describe(),
+            "terminated by signal 9"
+        );
+        assert_eq!(
+            SidecarExit::default().describe(),
+            "exited without reporting a code"
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/startup.rs b/desktop/src-tauri/src/startup.rs
new file mode 100644
index 00000000000..bcc08ba2279
--- /dev/null
+++ b/desktop/src-tauri/src/startup.rs
@@ -0,0 +1,876 @@
+//! The startup sequence, as named states inside a window the user can already see.
+//!
+//! Everything below used to run inside `setup()` before any window existed, and the window was
+//! then created hidden. That ordering is why a failed start had no surface: the spawn event stream
+//! was discarded, so the child's exit code was gone, and a run of probes that time out rather than
+//! refuse takes over a minute with nothing on screen to explain it. D7 inverts it. The window is
+//! created and shown first, and the sequence runs inside it as named states under one overall
+//! deadline, with a retry, the child's exit code and a diagnostic the user can copy.
+//!
+//! Registration comes first, before the runtime is touched at all. The order looks backwards until
+//! you follow the failing case: a login launch starts hidden, and if the tray were installed only
+//! after a successful start then a start that failed would leave a running process with no window
+//! and no icon — invisible. The app establishes its own surface, then deals with the runtime.
+//!
+//! A launch that came from login autostart starts hidden, and that is the only difference — except
+//! where there is no usable tray to hide into, which is R1 and lives in [`shows_window`].
+
+use crate::{
+    auth::Auth,
+    endpoint::ProxyEndpoint,
+    first_run::{self, StartAtLogin},
+    identity, ownership,
+    proxy::{ProxyClient, RuntimeIdentity},
+    resolve,
+    sidecar::{self, SidecarWatch},
+    tray_availability::{self, TrayAvailability},
+    AppState,
+};
+use serde::Serialize;
+use std::{
+    path::PathBuf,
+    sync::{
+        atomic::{AtomicBool, Ordering},
+        Mutex, MutexGuard, PoisonError,
+    },
+};
+use tauri::{AppHandle, Emitter, Manager};
+use tokio::time::{sleep, Duration, Instant};
+
+/// The event the bootstrap page listens on.
+pub const PHASE_EVENT: &str = "startup-phase";
+
+/// One deadline for the whole sequence.
+///
+/// Per-step budgets were what produced the unbounded case: a two-second attach loop whose probes
+/// each cost a four-second client timeout, followed by twenty more waits, adds up to something no
+/// single number in the code admitted to. One ceiling over the whole run is a promise that can be
+/// read — and every probe under it is bounded by the remaining time rather than by its own
+/// timeout, because otherwise the last probe overruns the ceiling by the whole client timeout.
+pub const DEADLINE: Duration = Duration::from_secs(30);
+
+const POLL: Duration = Duration::from_millis(250);
+
+/// Where the launch came from.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum LaunchOrigin {
+    /// A person opened the app.
+    User,
+    /// The login item started it.
+    Autostart,
+}
+
+/// The argument the autostart registration passes back to us. Nothing else supplies it, so its
+/// presence is the launch origin.
+pub const AUTOSTART_FLAG: &str = "--autostart";
+
+impl LaunchOrigin {
+    pub fn from_args(mut args: impl Iterator<Item = String>) -> Self {
+        if args.any(|argument| argument == AUTOSTART_FLAG) {
+            Self::Autostart
+        } else {
+            Self::User
+        }
+    }
+
+    pub fn detect() -> Self {
+        Self::from_args(std::env::args())
+    }
+}
+
+/// Whether this launch shows its window.
+///
+/// D7 shows it always and exempts a login launch, which starts hidden. D6 shows it wherever there
+/// is no usable tray. A no-tray login launch satisfies both rules and they disagree, so R1 settles
+/// it: tray availability wins. Starting hidden is a property of having somewhere to be hidden in,
+/// not of how the process was started.
+pub fn shows_window(origin: LaunchOrigin, tray: TrayAvailability) -> bool {
+    !tray.is_available() || origin == LaunchOrigin::User
+}
+
+/// A named state of the startup sequence.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Phase {
+    Registering,
+    Resolving,
+    Probing,
+    Attaching,
+    Starting,
+    Waiting,
+    Ready,
+    Failed,
+}
+
+/// Every phase, in the order they run. The bootstrap page derives its checklist from this rather
+/// than restating it, so a phase cannot exist in one place and be missing from the other.
+pub const PHASES: [Phase; 8] = [
+    Phase::Registering,
+    Phase::Resolving,
+    Phase::Probing,
+    Phase::Attaching,
+    Phase::Starting,
+    Phase::Waiting,
+    Phase::Ready,
+    Phase::Failed,
+];
+
+impl Phase {
+    /// The stable identifier the bootstrap page keys on.
+    pub fn id(self) -> &'static str {
+        match self {
+            Self::Registering => "registering",
+            Self::Resolving => "resolving",
+            Self::Probing => "probing",
+            Self::Attaching => "attaching",
+            Self::Starting => "starting",
+            Self::Waiting => "waiting",
+            Self::Ready => "ready",
+            Self::Failed => "failed",
+        }
+    }
+
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Registering => "Registering the tray and the login item",
+            Self::Resolving => "Resolving the configuration home and port",
+            Self::Probing => "Looking for a runtime that is already listening",
+            Self::Attaching => "Attaching to the runtime that answered",
+            Self::Starting => "Starting the bundled runtime",
+            Self::Waiting => "Waiting for the runtime to report healthy",
+            Self::Ready => "Ready",
+            Self::Failed => "OpenCodex could not start its runtime",
+        }
+    }
+
+    pub fn is_terminal(self) -> bool {
+        matches!(self, Self::Ready | Self::Failed)
+    }
+}
+
+/// One phase, as the bootstrap page sees it.
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PhaseInfo {
+    pub id: &'static str,
+    pub label: &'static str,
+    pub terminal: bool,
+}
+
+/// The phase list the page renders. Derived from [`PHASES`] so the two cannot drift.
+pub fn phase_list() -> Vec<PhaseInfo> {
+    PHASES
+        .iter()
+        .map(|phase| PhaseInfo {
+            id: phase.id(),
+            label: phase.label(),
+            terminal: phase.is_terminal(),
+        })
+        .collect()
+}
+
+/// What the bootstrap page is told.
+///
+/// It carries the phases already finished, not just the current one. An event emitted before the
+/// page's listener exists is gone, and the early phases finish in milliseconds, so a page that
+/// reconstructed history from events alone would show a run in progress with nothing behind it.
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Progress {
+    pub phase: &'static str,
+    pub label: &'static str,
+    pub detail: Option<String>,
+    pub completed: Vec<&'static str>,
+    pub failed_phase: Option<&'static str>,
+    pub elapsed_ms: u64,
+    pub dashboard: Option<String>,
+    pub diagnostic: Option<String>,
+    pub can_retry: bool,
+}
+
+impl Progress {
+    fn new(phase: Phase, elapsed_ms: u64) -> Self {
+        Self {
+            phase: phase.id(),
+            label: phase.label(),
+            detail: None,
+            completed: Vec::new(),
+            failed_phase: None,
+            elapsed_ms,
+            dashboard: None,
+            diagnostic: None,
+            can_retry: phase == Phase::Failed,
+        }
+    }
+}
+
+/// Where the sequence is pointed, once the CLI has said.
+#[derive(Clone)]
+struct Target {
+    endpoint: ProxyEndpoint,
+    home: PathBuf,
+}
+
+/// What registering established about this installation.
+#[derive(Clone, Debug)]
+pub struct Registration {
+    pub login: StartAtLogin,
+    /// This installation's own id, and what the recorded runtime owner says about it.
+    pub identity: String,
+}
+
+struct Live {
+    latest: Progress,
+    reported: Vec<&'static str>,
+}
+
+/// The sequence's managed state: the latest thing it said, what it has already finished, and
+/// whether it is running, so a retry cannot start a second run alongside the first.
+pub struct Startup {
+    live: Mutex<Live>,
+    running: AtomicBool,
+    /// The outcome of the one-time registration, once it has happened.
+    registered: Mutex<Option<Registration>>,
+}
+
+impl Startup {
+    pub fn new() -> Self {
+        Self {
+            live: Mutex::new(Live {
+                latest: Progress::new(Phase::Registering, 0),
+                reported: Vec::new(),
+            }),
+            running: AtomicBool::new(false),
+            registered: Mutex::new(None),
+        }
+    }
+
+    fn live(&self) -> MutexGuard<'_, Live> {
+        self.live.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    fn registration(&self) -> Option<Registration> {
+        self.registered
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .clone()
+    }
+
+    fn remember_registration(&self, registration: Registration) {
+        *self
+            .registered
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner) = Some(registration);
+    }
+
+    /// The whole state of the run so far, which is what the page asks for when it loads.
+    pub fn latest(&self) -> Progress {
+        self.live().latest.clone()
+    }
+
+    fn restart(&self) {
+        let mut live = self.live();
+        live.reported.clear();
+        live.latest = Progress::new(Phase::Registering, 0);
+    }
+
+    fn publish(&self, progress: &mut Progress, failed_in: Option<Phase>) {
+        let mut live = self.live();
+        if !live.reported.contains(&progress.phase)
+            && progress.phase != Phase::Ready.id()
+            && progress.phase != Phase::Failed.id()
+        {
+            live.reported.push(progress.phase);
+        }
+        progress.completed = live
+            .reported
+            .iter()
+            .copied()
+            .filter(|id| *id != progress.phase)
+            .collect();
+        progress.failed_phase = failed_in.map(Phase::id);
+        live.latest = progress.clone();
+    }
+}
+
+impl Default for Startup {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Run the sequence, unless it is already running. This is also the retry.
+pub fn begin(app: &AppHandle) {
+    let Some(startup) = app.try_state::<Startup>() else {
+        return;
+    };
+    if startup
+        .running
+        .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
+        .is_err()
+    {
+        return;
+    }
+    startup.restart();
+    let app = app.clone();
+    tauri::async_runtime::spawn(async move {
+        run(&app).await;
+        if let Some(startup) = app.try_state::<Startup>() {
+            startup.running.store(false, Ordering::Release);
+        }
+    });
+}
+
+async fn run(app: &AppHandle) {
+    let started = Instant::now();
+    let deadline = started + DEADLINE;
+    let Some(watch) = app.try_state::<AppState>().map(|state| state.watch.clone()) else {
+        return;
+    };
+    report(app, started, Phase::Registering, None);
+    let registration = register(app, deadline).await;
+    report(
+        app,
+        started,
+        Phase::Registering,
+        Some(format!(
+            "{}; {}",
+            registration.login.describe(),
+            registration.identity
+        )),
+    );
+
+    report(app, started, Phase::Resolving, None);
+    // D5: the shell no longer resolves the home, the port or liveness. It asks the bundled CLI,
+    // which owns the tuned probe budgets that exist because a shell-side reimplementation answered
+    // "nobody is listening" twice and started duplicate proxies. The call is inside the sequence, so
+    // a CLI that is missing or slow has a state, a diagnostic and a retry rather than a guess.
+    let resolution = resolve::run(app, deadline).await;
+    let Some(answer) = resolution.resolved() else {
+        // Fail-closed. A resolution that could not be trusted is not an absence, and nothing below
+        // may read it as one.
+        fail(
+            app,
+            started,
+            None,
+            &registration,
+            &watch,
+            Phase::Resolving,
+            resolution
+                .reason()
+                .unwrap_or("the runtime could not be resolved")
+                .to_owned(),
+        );
+        return;
+    };
+    let endpoint = answer.endpoint();
+    let target = Target {
+        endpoint,
+        home: answer.home(),
+    };
+    let proxy = match ProxyClient::new(endpoint, Auth::new(answer.home())) {
+        Ok(proxy) => proxy,
+        Err(error) => {
+            fail(
+                app,
+                started,
+                Some(&target),
+                &registration,
+                &watch,
+                Phase::Resolving,
+                error.to_string(),
+            );
+            return;
+        }
+    };
+    if let Some(state) = app.try_state::<AppState>() {
+        state.attach(proxy.clone());
+    }
+    report(
+        app,
+        started,
+        Phase::Resolving,
+        Some(format!(
+            "{} with a configuration home of {}, resolved by the bundled CLI {}",
+            target.endpoint.url(""),
+            target.home.display(),
+            answer.cli_version
+        )),
+    );
+
+    report(
+        app,
+        started,
+        Phase::Probing,
+        Some(match answer.liveness.status {
+            resolve::Status::Live => "a runtime is already listening".to_owned(),
+            resolve::Status::AbsentProven => {
+                "no runtime is listening, and that absence was proven".to_owned()
+            }
+        }),
+    );
+    match resolve::live_verdict(&resolution) {
+        resolve::LiveVerdict::Attach => {
+            report(
+                app,
+                started,
+                Phase::Attaching,
+                Some("a runtime was already listening, so this app is a guest on it".to_owned()),
+            );
+            if bind(app, &proxy, deadline).await.is_none() {
+                fail(
+                    app,
+                    started,
+                    Some(&target),
+                    &registration,
+                    &watch,
+                    Phase::Attaching,
+                    "the runtime answered but did not identify itself, so this app did not attach"
+                        .to_owned(),
+                );
+                return;
+            }
+            finish(app, started, endpoint);
+            return;
+        }
+        // Something holds the port and this app cannot manage it. That is not an absence, so it
+        // does not authorise starting a second runtime beside it either.
+        resolve::LiveVerdict::Unusable(reason) => {
+            fail(
+                app,
+                started,
+                Some(&target),
+                &registration,
+                &watch,
+                Phase::Attaching,
+                reason,
+            );
+            return;
+        }
+        resolve::LiveVerdict::NotLive => {}
+    }
+    if !resolve::may_start(&resolution) {
+        // Only a proven absence authorises a start. Nothing else may fall through to one.
+        fail(
+            app,
+            started,
+            Some(&target),
+            &registration,
+            &watch,
+            Phase::Probing,
+            "the runtime's liveness could not be established, so no runtime was started".to_owned(),
+        );
+        return;
+    }
+
+    // A retry must not leave a second proxy behind. A child that has not reported an exit is still
+    // out there, whatever the last run concluded, so the retry waits on that one rather than
+    // starting another and racing it for the port.
+    let owns_live_child = app
+        .try_state::<AppState>()
+        .is_some_and(|state| state.owns_runtime())
+        && watch.exit().is_none();
+    if owns_live_child {
+        report(
+            app,
+            started,
+            Phase::Starting,
+            Some("the runtime this app started has not exited; waiting on it again".to_owned()),
+        );
+    } else {
+        report(app, started, Phase::Starting, None);
+        watch.reset();
+        match spawn_runtime(app, endpoint, &watch) {
+            Some(Ok(())) => {}
+            Some(Err(error)) => {
+                fail(
+                    app,
+                    started,
+                    Some(&target),
+                    &registration,
+                    &watch,
+                    Phase::Starting,
+                    error,
+                );
+                return;
+            }
+            // An exit is already in flight, so starting a runtime now would orphan it.
+            None => return,
+        }
+    }
+
+    report(app, started, Phase::Waiting, None);
+    while Instant::now() < deadline {
+        if matches!(proxy.alive_within(deadline).await, Some(Ok(_))) {
+            if bind(app, &proxy, deadline).await.is_none() {
+                // Healthy is not the same as identified: a 200 with a body that does not carry the
+                // marker is something else holding the port, and the token is never sent to it.
+                fail(
+                    app,
+                    started,
+                    Some(&target),
+                    &registration,
+                    &watch,
+                    Phase::Waiting,
+                    "the runtime reported healthy but did not identify itself".to_owned(),
+                );
+                return;
+            }
+            finish(app, started, endpoint);
+            return;
+        }
+        // A child that has already exited will never answer, so the deadline is not worth waiting
+        // out. This is the case the discarded event stream used to hide behind a generic timeout.
+        if let Some(exit) = watch.exit() {
+            fail(
+                app,
+                started,
+                Some(&target),
+                &registration,
+                &watch,
+                Phase::Waiting,
+                format!("the runtime {}", exit.describe()),
+            );
+            return;
+        }
+        sleep(POLL).await;
+    }
+    fail(
+        app,
+        started,
+        Some(&target),
+        &registration,
+        &watch,
+        Phase::Waiting,
+        format!(
+            "the runtime did not report healthy within {} seconds",
+            DEADLINE.as_secs()
+        ),
+    );
+}
+
+/// Establish the app's own surface: the tray verdict, the tray, and the login item.
+///
+/// It happens once per process. A retry re-runs the runtime half of the sequence, and running this
+/// half again would build a second tray icon with its own refresh loop and its own menu handlers —
+/// the failure would look like the app duplicating itself every time the user pressed Retry.
+async fn register(app: &AppHandle, deadline: Instant) -> Registration {
+    if let Some(done) = app
+        .try_state::<Startup>()
+        .and_then(|startup| startup.registration())
+    {
+        return done;
+    }
+
+    // The probe blocks on a session-bus round trip, so it does not belong on an async worker — and
+    // it is bounded by the sequence's own deadline, because a bus that never answers would
+    // otherwise leave the page in this state with a retry that could do nothing about it.
+    let tray = match tokio::time::timeout_at(
+        deadline,
+        tauri::async_runtime::spawn_blocking(tray_availability::detect),
+    )
+    .await
+    {
+        Ok(Ok(tray)) => tray,
+        _ => TrayAvailability::assumed(),
+    };
+
+    // Before the tray, so its Start at Login checkbox reads the state this leaves behind rather
+    // than the state from before first run.
+    let login = first_run::apply_start_at_login_default(app);
+    first_run::adopt_launch_origin_argument(app);
+
+    // The verdict is published only once an icon actually exists. Announcing a tray and then
+    // failing to install it would hide the window into nothing, which is the exact stranding D6
+    // exists to prevent.
+    let verdict = if tray.is_available() && install_tray(app, deadline).await {
+        TrayAvailability::Available
+    } else {
+        TrayAvailability::Unavailable
+    };
+    if let Some(coordinator) = app.try_state::<crate::exit::ExitCoordinator>() {
+        coordinator.set_tray(verdict);
+    }
+
+    if let Some(window) = app.get_webview_window("main") {
+        if shows_window(LaunchOrigin::detect(), verdict) {
+            crate::window::show(&window);
+        }
+    }
+    // This installation's own id, and what the recorded runtime owner says about it. The claim
+    // lives in the shared service install state and the CLI is what reads it; the comparison
+    // against our own id is the rule that record publishes.
+    let install_id = identity::install_id(app);
+    let registration = Registration {
+        login,
+        identity: ownership::describe(ownership::resolve(app).as_ref(), install_id.as_deref()),
+    };
+    if let Some(startup) = app.try_state::<Startup>() {
+        startup.remember_registration(registration.clone());
+    }
+    registration
+}
+
+/// Build the tray on the main thread, which is where GTK requires it on Linux.
+async fn install_tray(app: &AppHandle, deadline: Instant) -> bool {
+    let handle = app.clone();
+    let (sender, receiver) = tokio::sync::oneshot::channel();
+    if app
+        .run_on_main_thread(move || {
+            let _ = sender.send(crate::tray::install(&handle).map_err(|error| error.to_string()));
+        })
+        .is_err()
+    {
+        return false;
+    }
+    match tokio::time::timeout_at(deadline, receiver).await {
+        Ok(Ok(Ok(()))) => true,
+        Ok(Ok(Err(error))) => {
+            crate::logging::log_once("the tray could not be installed", &error);
+            false
+        }
+        _ => {
+            crate::logging::log_once(
+                "the tray could not be installed",
+                "the main thread did not answer",
+            );
+            false
+        }
+    }
+}
+/// Start the runtime, unless an exit is already in flight.
+///
+/// The coordinator reserves the spawn rather than holding its lock across it: holding it would put
+/// process creation in front of the main thread's exit handler, so a wedged spawn would be a Quit
+/// that never answers. A quit arriving in between is deferred until the child is ours and then
+/// drains it, so it cannot observe "we own nothing" and leave a proxy running that nothing stops.
+fn spawn_runtime(
+    app: &AppHandle,
+    endpoint: ProxyEndpoint,
+    watch: &SidecarWatch,
+) -> Option<Result<(), String>> {
+    let coordinator = app.try_state::<crate::exit::ExitCoordinator>()?;
+    if !coordinator.begin_spawn() {
+        return None;
+    }
+    let outcome = match sidecar::start(app, endpoint, watch) {
+        Ok(child) => {
+            if let Some(state) = app.try_state::<AppState>() {
+                state.adopt(child);
+            }
+            Ok(())
+        }
+        Err(error) => Err(error),
+    };
+    if let Some(reason) = coordinator.finish_spawn() {
+        // A quit landed while the child was being created. It is ours now, so it gets drained.
+        crate::exit::drain_now(app, reason);
+        return None;
+    }
+    Some(outcome)
+}
+
+/// Establish which instance is answering, and whether it is the child this app started.
+///
+/// The health body is unauthenticated and carries the marker, the pid and the port, so identity is
+/// settled before any credential is sent. It is also the only thing that grants process ownership:
+/// a spawn records a pid, and this is what says that pid is the one holding the port. An answer
+/// that cannot be read leaves the app owning nothing, which is the safe way round — an owner's stop
+/// sent to a listener that is not ours is a stop sent to somebody else's runtime.
+///
+/// The answer is returned rather than swallowed, because a sequence that cannot identify what it is
+/// talking to has not finished. Reporting Ready there would navigate the window to a dashboard the
+/// shell cannot authenticate against, since the management token is only sent to a bound instance.
+async fn bind(app: &AppHandle, proxy: &ProxyClient, deadline: Instant) -> Option<RuntimeIdentity> {
+    let identity = match tokio::time::timeout_at(deadline, proxy.identify()).await {
+        Ok(Ok(identity)) => identity,
+        _ => return None,
+    };
+    proxy.bind(identity);
+    if let Some(state) = app.try_state::<AppState>() {
+        state.confirm_ownership(identity);
+    }
+    Some(identity)
+}
+
+fn finish(app: &AppHandle, started: Instant, endpoint: ProxyEndpoint) {
+    // Ownership is whatever the confirmation above established, not whatever a spawn assumed.
+    crate::tray::set_owned(
+        app,
+        app.try_state::<AppState>()
+            .is_some_and(|state| state.owns_runtime()),
+    );
+    let dashboard = endpoint.url("/#/usage");
+    let mut progress = Progress::new(Phase::Ready, elapsed(started));
+    progress.dashboard = Some(dashboard.clone());
+    emit(app, progress, None);
+    if let Some(window) = app.get_webview_window("main") {
+        // justified: replacing the bootstrap page with the dashboard is how this window has always
+        // navigated, and the string is a URL this process resolved, not anything a page supplied.
+        let _ = window.eval(format!("window.location.replace({dashboard:?})"));
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn fail(
+    app: &AppHandle,
+    started: Instant,
+    target: Option<&Target>,
+    registration: &Registration,
+    watch: &SidecarWatch,
+    phase: Phase,
+    reason: String,
+) {
+    let elapsed_ms = elapsed(started);
+    let mut progress = Progress::new(Phase::Failed, elapsed_ms);
+    progress.diagnostic = Some(diagnostic(
+        target.map(|target| (target.endpoint, target.home.clone())),
+        registration,
+        watch,
+        phase,
+        &reason,
+        elapsed_ms,
+    ));
+    progress.detail = Some(reason);
+    emit(app, progress, Some(phase));
+}
+
+/// The text the failure surface offers for copying.
+///
+/// It names the state it stopped in, the endpoint and home it was using, how the child ended and
+/// what the child last said. Those together are what separates "the port was taken" from "the
+/// binary will not run on this CPU" from "the home is not the one the accounts are in", and none of
+/// them were reachable from the generic health failure this replaces.
+pub fn diagnostic(
+    target: Option<(ProxyEndpoint, PathBuf)>,
+    registration: &Registration,
+    watch: &SidecarWatch,
+    phase: Phase,
+    reason: &str,
+    elapsed_ms: u64,
+) -> String {
+    let mut lines = vec![
+        format!(
+            "OpenCodex desktop {} on {}",
+            env!("CARGO_PKG_VERSION"),
+            std::env::consts::OS
+        ),
+        format!("state: {}", phase.id()),
+        format!("reason: {reason}"),
+        format!("elapsed: {elapsed_ms}ms"),
+    ];
+    match target {
+        Some((endpoint, home)) => {
+            lines.push(format!("endpoint: {}", endpoint.url("")));
+            lines.push(format!("home: {}", home.display()));
+        }
+        None => lines.push("endpoint: not resolved".to_owned()),
+    }
+    lines.push(format!("start at login: {}", registration.login.describe()));
+    lines.push(format!("runtime ownership: {}", registration.identity));
+    lines.push(match watch.exit() {
+        Some(exit) => format!("runtime process: {}", exit.describe()),
+        None => "runtime process: still running or never started".to_owned(),
+    });
+    let output = watch.lines();
+    if output.is_empty() {
+        lines.push("runtime output: none".to_owned());
+    } else {
+        lines.push("runtime output:".to_owned());
+        lines.extend(output.into_iter().map(|line| format!("  {line}")));
+    }
+    lines.join("\n")
+}
+
+fn report(app: &AppHandle, started: Instant, phase: Phase, detail: Option<String>) {
+    let mut progress = Progress::new(phase, elapsed(started));
+    progress.detail = detail;
+    emit(app, progress, None);
+}
+
+fn emit(app: &AppHandle, mut progress: Progress, failed_in: Option<Phase>) {
+    if let Some(startup) = app.try_state::<Startup>() {
+        startup.publish(&mut progress, failed_in);
+    }
+    let _ = app.emit(PHASE_EVENT, progress);
+}
+
+fn elapsed(started: Instant) -> u64 {
+    started.elapsed().as_millis() as u64
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{shows_window, LaunchOrigin, Phase, AUTOSTART_FLAG, DEADLINE, PHASES, POLL};
+    use crate::tray_availability::TrayAvailability;
+    use tokio::time::Duration;
+
+    #[test]
+    fn only_the_autostart_argument_marks_a_login_launch() {
+        let user = ["/Applications/OpenCodex.app".to_owned()];
+        assert_eq!(
+            LaunchOrigin::from_args(user.into_iter()),
+            LaunchOrigin::User
+        );
+        let login = [
+            "/Applications/OpenCodex.app".to_owned(),
+            AUTOSTART_FLAG.to_owned(),
+        ];
+        assert_eq!(
+            LaunchOrigin::from_args(login.into_iter()),
+            LaunchOrigin::Autostart
+        );
+    }
+
+    #[test]
+    fn a_manual_launch_always_shows_the_window() {
+        assert!(shows_window(
+            LaunchOrigin::User,
+            TrayAvailability::Available
+        ));
+        assert!(shows_window(
+            LaunchOrigin::User,
+            TrayAvailability::Unavailable
+        ));
+    }
+
+    #[test]
+    fn a_login_launch_hides_only_where_there_is_a_tray_to_hide_in() {
+        assert!(!shows_window(
+            LaunchOrigin::Autostart,
+            TrayAvailability::Available
+        ));
+        assert!(shows_window(
+            LaunchOrigin::Autostart,
+            TrayAvailability::Unavailable
+        ));
+    }
+
+    #[test]
+    fn registration_runs_before_the_runtime_is_touched() {
+        let order: Vec<&str> = PHASES.iter().map(|phase| phase.id()).collect();
+        let registering = order.iter().position(|id| *id == "registering").unwrap();
+        for later in ["resolving", "probing", "starting", "waiting"] {
+            assert!(registering < order.iter().position(|id| *id == later).unwrap());
+        }
+    }
+
+    #[test]
+    fn every_phase_has_a_distinct_identifier_and_a_label() {
+        let mut ids: Vec<&str> = PHASES.iter().map(|phase| phase.id()).collect();
+        ids.sort_unstable();
+        ids.dedup();
+        assert_eq!(ids.len(), PHASES.len());
+        assert!(PHASES.iter().all(|phase| !phase.label().is_empty()));
+        assert_eq!(PHASES.iter().filter(|phase| phase.is_terminal()).count(), 2);
+        assert!(PHASES.contains(&Phase::Ready));
+    }
+
+    #[test]
+    fn the_whole_sequence_is_bounded_well_under_the_minute_it_used_to_take() {
+        let budgets = [DEADLINE, POLL];
+        assert!(budgets
+            .iter()
+            .all(|budget| *budget <= Duration::from_secs(45)));
+        assert!(POLL < DEADLINE);
+    }
+}
diff --git a/desktop/src-tauri/src/tray.rs b/desktop/src-tauri/src/tray.rs
new file mode 100644
index 00000000000..57923e19340
--- /dev/null
+++ b/desktop/src-tauri/src/tray.rs
@@ -0,0 +1,384 @@
+use crate::{
+    exit::{self, ExitReason},
+    formatting,
+    proxy::ProxyClient,
+    updater, widget, window,
+};
+use serde_json::Value;
+use std::sync::{
+    atomic::{AtomicBool, Ordering},
+    Mutex,
+};
+use tauri::{
+    menu::{CheckMenuItem, Menu, MenuItem, PredefinedMenuItem},
+    tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent},
+    AppHandle, Manager, Wry,
+};
+use tauri_plugin_autostart::ManagerExt;
+use tauri_plugin_opener::OpenerExt;
+
+pub struct TrayState {
+    pub menu: Mutex<Option<TrayMenu>>,
+    pub installing: AtomicBool,
+}
+
+#[derive(Clone)]
+pub struct TrayMenu {
+    check_updates: MenuItem<Wry>,
+    install_update: MenuItem<Wry>,
+    stop: MenuItem<Wry>,
+}
+
+impl Default for TrayState {
+    fn default() -> Self {
+        Self {
+            menu: Mutex::new(None),
+            installing: AtomicBool::new(false),
+        }
+    }
+}
+
+/// Build the tray.
+///
+/// The proxy is not passed in. The tray is installed before a runtime has been resolved, so every
+/// use reads the current client from the app instead of holding one that might not exist yet.
+pub fn install(app: &AppHandle) -> tauri::Result<()> {
+    let open = MenuItem::with_id(app, "open-dashboard", "Open Dashboard", true, None::<&str>)?;
+    let browser = MenuItem::with_id(app, "open-browser", "Open in Browser", true, None::<&str>)?;
+    let login = CheckMenuItem::with_id(
+        app,
+        "start-at-login",
+        "Start at Login",
+        true,
+        app.autolaunch().is_enabled().unwrap_or(false),
+        None::<&str>,
+    )?;
+    // The tray is built before the startup sequence has decided anything, so nothing owns a
+    // runtime yet. Ownership arrives later and reaches this item through [`set_owned`].
+    let owned = app
+        .try_state::<crate::AppState>()
+        .is_some_and(|state| state.owns_runtime());
+    let stop = MenuItem::with_id(app, "stop-proxy", "Stop proxy", owned, None::<&str>)?;
+    let check_updates = MenuItem::with_id(
+        app,
+        "check-updates",
+        "Check for Updates…",
+        true,
+        None::<&str>,
+    )?;
+    let install_update =
+        MenuItem::with_id(app, "install-update", "Install update", false, None::<&str>)?;
+    let quit = MenuItem::with_id(app, "quit", "Quit", true, None::<&str>)?;
+    let menu = Menu::with_items(
+        app,
+        &[
+            &open,
+            &browser,
+            &PredefinedMenuItem::separator(app)?,
+            &login,
+            &stop,
+            &PredefinedMenuItem::separator(app)?,
+            &check_updates,
+            &install_update,
+            &PredefinedMenuItem::separator(app)?,
+            &quit,
+        ],
+    )?;
+    if let Ok(mut state) = app.state::<TrayState>().menu.lock() {
+        *state = Some(TrayMenu {
+            check_updates: check_updates.clone(),
+            install_update: install_update.clone(),
+            stop: stop.clone(),
+        });
+    }
+
+    let tray = TrayIconBuilder::with_id("main")
+        .icon(icon())
+        .icon_as_template(true)
+        .menu(&menu)
+        .on_tray_icon_event(|tray, event| {
+            if let TrayIconEvent::Click {
+                button: MouseButton::Left,
+                button_state: MouseButtonState::Up,
+                ..
+            } = event
+            {
+                if let Some(window) = tray.app_handle().get_webview_window("main") {
+                    window::show(&window);
+                }
+            }
+        })
+        .on_menu_event(move |app, event| match event.id().as_ref() {
+            "open-dashboard" => {
+                if let Some(window) = app.get_webview_window("main") {
+                    window::show(&window);
+                }
+            }
+            "open-browser" => {
+                let Some(endpoint) = app
+                    .state::<crate::AppState>()
+                    .proxy()
+                    .map(|proxy| proxy.endpoint())
+                else {
+                    return;
+                };
+                let _ = app
+                    .opener()
+                    .open_url(format!("{}#/usage", endpoint.url("/")), None::<String>);
+            }
+            "start-at-login" => {
+                let enabled = app.autolaunch().is_enabled().unwrap_or(false);
+                if enabled {
+                    let _ = app.autolaunch().disable();
+                } else {
+                    let _ = app.autolaunch().enable();
+                }
+            }
+            "stop-proxy" => {
+                // Through the coordinator, not beside it: Stop pressed twice, Stop then Quit, and
+                // Stop during an update all have to be one execution over one child.
+                exit::request_stop(app);
+            }
+            "check-updates" => {
+                let app = app.clone();
+                tauri::async_runtime::spawn(async move {
+                    updater::check_and_show(&app).await;
+                });
+            }
+            "install-update" => {
+                let app = app.clone();
+                tauri::async_runtime::spawn(async move {
+                    let update = app
+                        .state::<crate::updater::PendingUpdate>()
+                        .0
+                        .lock()
+                        .ok()
+                        .and_then(|mut pending| pending.take());
+                    let Some(update) = update else {
+                        return;
+                    };
+                    let version = update.version.clone();
+                    let retry_update = update.clone();
+                    set_installing(&app, &version);
+                    if let Err(error) = updater::install(&app, update).await {
+                        if let Ok(mut pending) =
+                            app.state::<crate::updater::PendingUpdate>().0.lock()
+                        {
+                            *pending = Some(retry_update);
+                        }
+                        set_install_failed(&app, &version);
+                        crate::logging::log_once("updater install failed", &error);
+                    }
+                });
+            }
+            // The only gesture that ends the app. It does not call `exit` itself: the coordinator
+            // holds the exit, drains an app-owned runtime and only then lets the process end.
+            "quit" => exit::request(app, ExitReason::UserQuit),
+            _ => {}
+        })
+        .build(app)?;
+
+    refresh(app, &tray);
+    let tray = tray.clone();
+    let app = app.clone();
+    tauri::async_runtime::spawn(async move {
+        let mut tick = 0;
+        loop {
+            tokio::time::sleep(std::time::Duration::from_secs(60)).await;
+            let Some(proxy) = app
+                .try_state::<crate::AppState>()
+                .and_then(|state| state.proxy())
+            else {
+                continue;
+            };
+            refresh_title(&tray, &proxy);
+            tick += 1;
+            if tick % 5 == 0 {
+                widget::refresh(&proxy);
+            }
+        }
+    });
+    Ok(())
+}
+
+fn refresh(app: &AppHandle, tray: &tauri::tray::TrayIcon<Wry>) {
+    let Some(proxy) = app
+        .try_state::<crate::AppState>()
+        .and_then(|state| state.proxy())
+    else {
+        return;
+    };
+    refresh_title(tray, &proxy);
+    widget::refresh(&proxy);
+}
+
+/// Take a copy of the menu handles, holding the lock only for the copy.
+///
+/// Every Tauri menu setter dispatches to the main thread and waits for it. The tray is built *on*
+/// the main thread and takes this same mutex while doing so, so calling a setter with the lock held
+/// is a cycle: a background update owns the mutex and waits for the main thread, and the main
+/// thread waits for the mutex. The app would stop answering Quit.
+fn menu_handles(app: &AppHandle) -> Option<TrayMenu> {
+    let state = app.try_state::<TrayState>()?;
+    let handles = state.menu.lock().ok()?;
+    handles.as_ref().cloned()
+}
+
+/// Reflect who owns the runtime in the tray's Stop item.
+pub fn set_owned(app: &AppHandle, owned: bool) {
+    if let Some(menu) = menu_handles(app) {
+        let _ = menu.stop.set_enabled(owned);
+    }
+}
+
+pub fn show_update_available(app: &AppHandle, version: &str) {
+    if let Some(menu) = menu_handles(app) {
+        let _ = menu.install_update.set_text(updater::update_label(version));
+        let _ = menu.install_update.set_enabled(true);
+        let _ = menu.check_updates.set_enabled(true);
+        let _ = menu.check_updates.set_text("Check for Updates…");
+    }
+}
+
+pub fn show_up_to_date(app: &AppHandle) {
+    if let Some(menu) = menu_handles(app) {
+        let _ = menu
+            .check_updates
+            .set_text(format!("Up to date (v{})", env!("CARGO_PKG_VERSION")));
+        let _ = menu.check_updates.set_enabled(true);
+        let _ = menu.install_update.set_enabled(false);
+    }
+}
+
+pub fn is_installing(app: &AppHandle) -> bool {
+    app.try_state::<TrayState>()
+        .is_some_and(|state| state.installing.load(Ordering::Acquire))
+}
+
+fn set_installing(app: &AppHandle, version: &str) {
+    if let Some(state) = app.try_state::<TrayState>() {
+        state.installing.store(true, Ordering::Release);
+    }
+    if let Some(menu) = menu_handles(app) {
+        let _ = menu
+            .install_update
+            .set_text(format!("Installing update v{version}…"));
+        let _ = menu.install_update.set_enabled(false);
+        let _ = menu.check_updates.set_enabled(false);
+    }
+}
+
+fn set_install_failed(app: &AppHandle, version: &str) {
+    if let Some(state) = app.try_state::<TrayState>() {
+        state.installing.store(false, Ordering::Release);
+    }
+    show_update_available(app, version);
+}
+
+fn refresh_title(tray: &tauri::tray::TrayIcon<Wry>, proxy: &ProxyClient) {
+    let proxy = proxy.clone();
+    let tray = tray.clone();
+    tauri::async_runtime::spawn(async move {
+        let Ok(settings) = proxy.companion_settings().await else {
+            return;
+        };
+        let Ok(usage) = proxy.usage_summary().await else {
+            return;
+        };
+        let quotas = proxy.quotas().await.unwrap_or(Value::Null);
+        if let Some(title) = render_title(&settings, &usage, &quotas) {
+            let _ = tray.set_title(Some(&title));
+        }
+    });
+}
+
+pub(crate) fn render_title(settings: &Value, usage: &Value, quotas: &Value) -> Option<String> {
+    let metric = settings
+        .pointer("/settings/menuBarMetric")
+        .and_then(Value::as_str)
+        .unwrap_or("tokens");
+    let summary = usage.get("summary").unwrap_or(usage);
+    let quota = quota_percent(quotas);
+    let value = match metric {
+        "requests" => formatting::count(summary.get("requests").and_then(Value::as_i64)),
+        "cost" => formatting::cost(summary.get("estimatedCostUsd").and_then(Value::as_f64)),
+        "quota" => format_percent(quota),
+        "none" => return None,
+        _ => formatting::tokens(summary.get("totalTokens").and_then(Value::as_i64)),
+    };
+    let template = settings
+        .pointer("/settings/menuBarTemplate")
+        .and_then(Value::as_str)
+        .filter(|value| !value.trim().is_empty());
+    let rendered = template
+        .map(|value| {
+            value
+                .replace(
+                    "{requests}",
+                    &formatting::count(summary.get("requests").and_then(Value::as_i64)),
+                )
+                .replace(
+                    "{totalTokens}",
+                    &formatting::tokens(summary.get("totalTokens").and_then(Value::as_i64)),
+                )
+                .replace(
+                    "{costUsd}",
+                    &formatting::cost(summary.get("estimatedCostUsd").and_then(Value::as_f64)),
+                )
+                .replace(
+                    "{inputTokens}",
+                    &formatting::tokens(summary.get("inputTokens").and_then(Value::as_i64)),
+                )
+                .replace(
+                    "{outputTokens}",
+                    &formatting::tokens(summary.get("outputTokens").and_then(Value::as_i64)),
+                )
+                .replace("{quotaPercent}", &format_percent(quota))
+        })
+        .unwrap_or(value);
+    let rendered = rendered.trim();
+    if rendered.is_empty() {
+        None
+    } else if rendered.chars().count() > 24 {
+        Some(format!(
+            "{}…",
+            rendered.chars().take(23).collect::<String>()
+        ))
+    } else {
+        Some(rendered.to_owned())
+    }
+}
+
+fn quota_percent(value: &Value) -> Option<f64> {
+    let reports = value.get("reports")?.as_array()?;
+    let mut values = Vec::new();
+    for report in reports {
+        let Some(quota) = report.get("quota") else {
+            continue;
+        };
+        for key in ["weeklyPercent", "monthlyPercent", "fiveHourPercent"] {
+            if let Some(value) = quota.get(key).and_then(Value::as_f64) {
+                values.push(value);
+            }
+        }
+        if let Some(windows) = quota.get("customWindows").and_then(Value::as_array) {
+            values.extend(
+                windows
+                    .iter()
+                    .filter_map(|window| window.get("percent").and_then(Value::as_f64)),
+            );
+        }
+    }
+    values.into_iter().reduce(f64::min)
+}
+
+fn format_percent(value: Option<f64>) -> String {
+    value
+        .map(|value| format!("{}%", value.round() as i64))
+        .unwrap_or_else(|| "—".into())
+}
+
+fn icon() -> tauri::image::Image<'static> {
+    tauri::image::Image::from_bytes(include_bytes!("../icons/tray/icon.png"))
+        .expect("valid tray icon")
+}
diff --git a/desktop/src-tauri/src/tray_availability.rs b/desktop/src-tauri/src/tray_availability.rs
new file mode 100644
index 00000000000..404c5b75e34
--- /dev/null
+++ b/desktop/src-tauri/src/tray_availability.rs
@@ -0,0 +1,131 @@
+//! Whether this session actually has a tray, as opposed to a tray backend that accepts an icon.
+//!
+//! `TrayIconBuilder::build` returning `Ok` proves nothing on Linux. The pinned backend creates an
+//! AppIndicator and reports success without checking that anything will display it, so on stock
+//! GNOME — which ships no AppIndicator extension — construction succeeds and no icon ever appears.
+//! The shell's macOS-shaped assumptions then compound it: the window was created hidden and close
+//! always hid, which leaves a running process with no way back in.
+//!
+//! So the question is asked of the session bus. Not whether the watcher exists — a watcher with no
+//! host attached still accepts registrations and still draws nothing — but whether it reports a
+//! host registered, which is the StatusNotifier specification's own answer to "is there somewhere
+//! for an icon to appear". macOS and Windows have a status area that is always present and answer
+//! without a probe.
+
+/// The result of asking whether this session can display a tray icon.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum TrayAvailability {
+    /// There is somewhere for the icon to appear, so hiding to the tray is a real place to hide.
+    Available,
+    /// There is not. The window is shown on launch and closing it ends the app through the drain.
+    Unavailable,
+}
+
+impl TrayAvailability {
+    pub fn is_available(self) -> bool {
+        matches!(self, Self::Available)
+    }
+
+    /// Whether a window close or a platform quit gesture may hide the app instead of ending it.
+    pub fn hides_to_tray(self) -> bool {
+        self.is_available()
+    }
+
+    /// What to assume before the probe has answered.
+    ///
+    /// The probe is asynchronous, and a window close can land before it returns. Assuming a tray
+    /// that turns out not to exist is the failure this whole module is about, so the platforms that
+    /// need a probe assume nothing until they have one.
+    pub fn assumed() -> Self {
+        if cfg!(target_os = "linux") {
+            Self::Unavailable
+        } else {
+            Self::Available
+        }
+    }
+}
+
+/// The StatusNotifier watcher, and the property that says a host is attached to it.
+#[cfg(target_os = "linux")]
+pub const WATCHER_NAME: &str = "org.kde.StatusNotifierWatcher";
+#[cfg(target_os = "linux")]
+pub const WATCHER_PATH: &str = "/StatusNotifierWatcher";
+#[cfg(target_os = "linux")]
+pub const HOST_REGISTERED: &str = "IsStatusNotifierHostRegistered";
+
+/// How long the session-bus probe may take.
+#[cfg(target_os = "linux")]
+const PROBE_TIMEOUT_MS: u64 = 750;
+
+/// Read a host-registered answer as an availability verdict.
+///
+/// `None` means the question could not be asked at all — no session bus, no watcher on it, no
+/// reply, a malformed one. That is deliberately folded into the same answer as a watcher with no
+/// host, because the two are indistinguishable from here and the safe response to both is
+/// identical: show the window and let close mean close. Guessing the other way strands the user.
+pub fn from_host_registered(registered: Option<bool>) -> TrayAvailability {
+    match registered {
+        Some(true) => TrayAvailability::Available,
+        Some(false) | None => TrayAvailability::Unavailable,
+    }
+}
+
+#[cfg(not(target_os = "linux"))]
+pub fn detect() -> TrayAvailability {
+    // macOS and Windows both have a status area that is always there, so the answer is known
+    // without asking anything. It still goes through the same reading so there is one place where
+    // an availability verdict is produced.
+    from_host_registered(Some(true))
+}
+
+#[cfg(target_os = "linux")]
+pub fn detect() -> TrayAvailability {
+    from_host_registered(host_registered())
+}
+
+#[cfg(target_os = "linux")]
+fn host_registered() -> Option<bool> {
+    use dbus::blocking::{stdintf::org_freedesktop_dbus::Properties, Connection};
+    use std::time::Duration;
+
+    let connection = Connection::new_session().ok()?;
+    let watcher = connection.with_proxy(
+        WATCHER_NAME,
+        WATCHER_PATH,
+        Duration::from_millis(PROBE_TIMEOUT_MS),
+    );
+    // A watcher nobody owns makes this call fail rather than answer, which is the same verdict.
+    watcher.get(WATCHER_NAME, HOST_REGISTERED).ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{from_host_registered, TrayAvailability};
+
+    #[test]
+    fn only_a_registered_host_is_an_available_tray() {
+        assert_eq!(
+            from_host_registered(Some(true)),
+            TrayAvailability::Available
+        );
+        assert_eq!(
+            from_host_registered(Some(false)),
+            TrayAvailability::Unavailable
+        );
+        assert_eq!(from_host_registered(None), TrayAvailability::Unavailable);
+    }
+
+    #[test]
+    fn hiding_is_only_offered_where_the_icon_would_be_drawn() {
+        assert!(TrayAvailability::Available.hides_to_tray());
+        assert!(!TrayAvailability::Unavailable.hides_to_tray());
+    }
+
+    #[test]
+    fn nothing_is_assumed_on_the_platform_that_needs_a_probe() {
+        assert_eq!(
+            TrayAvailability::assumed().is_available(),
+            !cfg!(target_os = "linux")
+        );
+    }
+}
diff --git a/desktop/src-tauri/src/updater.rs b/desktop/src-tauri/src/updater.rs
new file mode 100644
index 00000000000..456ffe76c5c
--- /dev/null
+++ b/desktop/src-tauri/src/updater.rs
@@ -0,0 +1,144 @@
+use crate::{exit::RestartReadiness, logging, tray};
+use std::sync::Mutex;
+use tauri::{AppHandle, Manager};
+use tauri_plugin_updater::{Update, UpdaterExt};
+
+pub struct PendingUpdate(pub Mutex<Option<Update>>);
+
+/// The manifest key a Linux install must resolve, or None to keep the updater's default
+/// os-arch key (linux-x86_64, windows-x86_64, darwin-*).
+///
+/// A deb install cannot apply the AppImage payload: the updater validates the downloaded
+/// bytes as a real .deb before installing through package-manager elevation, so it must
+/// resolve the deb's own manifest key. The bundle type is patched into the binary at
+/// packaging time, so the answer is embedded per artifact, not detected at runtime. The
+/// AppImage keeps the default key, which is also what installs from releases before the
+/// deb target existed already resolve.
+#[cfg(any(target_os = "linux", test))]
+pub fn linux_updater_target(
+    bundle: Option<tauri_utils::config::BundleType>,
+) -> Option<&'static str> {
+    match bundle {
+        Some(tauri_utils::config::BundleType::Deb) => Some("linux-x86_64-deb"),
+        _ => None,
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn configured_updater_target() -> Option<&'static str> {
+    linux_updater_target(tauri_utils::platform::bundle_type())
+}
+
+#[cfg(not(target_os = "linux"))]
+fn configured_updater_target() -> Option<&'static str> {
+    None
+}
+
+pub async fn check(app: &AppHandle) -> Result<Option<Update>, String> {
+    let mut builder = app.updater_builder();
+    if let Some(target) = configured_updater_target() {
+        builder = builder.target(target);
+    }
+    builder
+        .build()
+        .map_err(|error| error.to_string())?
+        .check()
+        .await
+        .map_err(|error| error.to_string())
+}
+
+pub async fn install(app: &AppHandle, update: Update) -> Result<(), String> {
+    // Download and verify first, and separately from installing. The pinned updater checks the
+    // release signature inside `download`, so these bytes are the ones the key signed; nothing has
+    // been replaced yet, and a failure here costs only the download.
+    let package = update
+        .download(|_, _| {}, || {})
+        .await
+        .map_err(|error| error.to_string())?;
+
+    // Then stop the runtime, and confirm it stopped, *before* anything is replaced. Asking for the
+    // restart after `install` is the shape that does not work: the pinned Windows installer hands off
+    // to the installer process and ends this one, so the call after it is never reached and the
+    // update would replace files under a runtime that is still serving. R2 still holds — this is a
+    // coordinated restart and not a quit — but the coordination has to finish first.
+    let readiness = crate::exit::prepare_restart(app).await;
+    if readiness != RestartReadiness::Ready {
+        return Err(format!(
+            "the update was downloaded but not installed: {}",
+            readiness.describe()
+        ));
+    }
+
+    update.install(package).map_err(|error| error.to_string())?;
+    // Only reached where the installer returns. On Windows it does not.
+    crate::exit::complete_restart(app)
+}
+
+pub fn update_label(version: &str) -> String {
+    format!("Install update v{version}")
+}
+
+pub fn start_background_checks(app: AppHandle) {
+    tauri::async_runtime::spawn(async move {
+        tokio::time::sleep(std::time::Duration::from_secs(30)).await;
+        loop {
+            check_and_show(&app).await;
+            tokio::time::sleep(std::time::Duration::from_secs(6 * 60 * 60)).await;
+        }
+    });
+}
+
+pub async fn check_and_show(app: &AppHandle) {
+    if tray::is_installing(app) {
+        return;
+    }
+    match check(app).await {
+        Ok(Some(update)) => {
+            if tray::is_installing(app) {
+                return;
+            }
+            let version = update.version.clone();
+            if let Ok(mut pending) = app.state::<PendingUpdate>().0.lock() {
+                *pending = Some(update);
+            }
+            tray::show_update_available(app, &version);
+        }
+        Ok(None) => {
+            if let Ok(mut pending) = app.state::<PendingUpdate>().0.lock() {
+                *pending = None;
+            }
+            tray::show_up_to_date(app);
+        }
+        Err(error) => logging::log_once("updater check failed", &error),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{linux_updater_target, update_label};
+    use tauri_utils::config::BundleType;
+
+    #[test]
+    fn formats_update_menu_label() {
+        assert_eq!(update_label("2.62.0"), "Install update v2.62.0");
+    }
+
+    #[test]
+    fn deb_installs_resolve_their_own_updater_key() {
+        assert_eq!(
+            linux_updater_target(Some(BundleType::Deb)),
+            Some("linux-x86_64-deb")
+        );
+    }
+
+    #[test]
+    fn appimage_installs_keep_the_default_updater_key() {
+        assert_eq!(linux_updater_target(Some(BundleType::AppImage)), None);
+    }
+
+    #[test]
+    fn unbundled_builds_keep_the_default_updater_key() {
+        // Dev builds and any format without a patcher entry resolve the default key.
+        assert_eq!(linux_updater_target(None), None);
+    }
+}
diff --git a/desktop/src-tauri/src/widget.rs b/desktop/src-tauri/src/widget.rs
new file mode 100644
index 00000000000..a2e38cfc78e
--- /dev/null
+++ b/desktop/src-tauri/src/widget.rs
@@ -0,0 +1,523 @@
+#[cfg(target_os = "macos")]
+mod macos {
+    use crate::{
+        proxy::{ProxyClient, ProxyError},
+        tray,
+    };
+    use serde::Serialize;
+    use serde_json::{json, Value};
+    use std::{
+        fs,
+        path::PathBuf,
+        time::{SystemTime, UNIX_EPOCH},
+    };
+    use uuid::Uuid;
+
+    #[derive(Debug, Serialize, serde::Deserialize, Clone, PartialEq)]
+    #[serde(rename_all = "camelCase")]
+    struct Today {
+        requests: Option<i64>,
+        total_tokens: Option<i64>,
+        estimated_cost_usd: Option<f64>,
+    }
+
+    #[derive(Debug, Serialize, serde::Deserialize, Clone, PartialEq)]
+    #[serde(rename_all = "camelCase")]
+    struct Quota {
+        provider_label: String,
+        window_label: String,
+        percent: Option<f64>,
+        reset_at: Option<f64>,
+    }
+
+    #[derive(Debug, Serialize, serde::Deserialize, Clone, PartialEq)]
+    #[serde(rename_all = "camelCase")]
+    struct Series {
+        id: String,
+        points: Vec<f64>,
+    }
+
+    #[derive(Debug, Serialize, serde::Deserialize, Clone, PartialEq)]
+    #[serde(rename_all = "camelCase")]
+    struct Chart {
+        start: f64,
+        bucket_seconds: i64,
+        style: String,
+        series: Vec<Series>,
+    }
+
+    #[derive(Debug, Serialize, serde::Deserialize, Clone, PartialEq)]
+    #[serde(rename_all = "camelCase")]
+    struct Snapshot {
+        schema_version: i64,
+        state: String,
+        state_title: String,
+        detail: Option<String>,
+        endpoint_display: String,
+        menu_title: Option<String>,
+        today: Option<Today>,
+        quotas: Vec<Quota>,
+        chart: Option<Chart>,
+        last_updated: Option<f64>,
+        generated_at: f64,
+    }
+
+    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+    enum ErrorKind {
+        Unreachable,
+        Unauthorized,
+        Http,
+        Decode,
+        /// The port answered, but as something other than the runtime this shell is bound to.
+        Foreign,
+    }
+
+    fn state_for_error(
+        kind: ErrorKind,
+        detail: Option<String>,
+    ) -> (&'static str, &'static str, Option<String>) {
+        match kind {
+            ErrorKind::Unreachable => (
+                "unreachable",
+                "Stopped",
+                Some("The proxy is not running.".into()),
+            ),
+            ErrorKind::Unauthorized => (
+                "unauthorized",
+                "Needs API key",
+                Some("This proxy requires an API key.".into()),
+            ),
+            // A runtime this app did not start is a different event from a fault, so it does not
+            // borrow the vocabulary of one. "degraded" would claim the proxy is misbehaving and
+            // "unreachable" would claim nothing is there; a user who started the runtime from npm
+            // or the CLI themselves would read either as a defect in a setup that is working.
+            // The widget has no red for this: `tone` in `app/Sources/OpenCodexWidget/Views.swift`
+            // maps a state it does not know to the neutral secondary colour, which is the right
+            // signal for "serving, just not ours".
+            ErrorKind::Foreign => (
+                "foreign",
+                "External runtime",
+                Some("This port is served by a runtime this app did not start.".into()),
+            ),
+            ErrorKind::Http | ErrorKind::Decode => ("degraded", "Degraded", detail),
+        }
+    }
+
+    fn proxy_error(error: &ProxyError) -> (ErrorKind, Option<String>) {
+        match error {
+            ProxyError::Unreachable => (ErrorKind::Unreachable, None),
+            ProxyError::Unauthorized => (ErrorKind::Unauthorized, None),
+            ProxyError::Http(status) => (ErrorKind::Http, Some(format!("HTTP {status}"))),
+            ProxyError::Decode(error) => (ErrorKind::Decode, Some(error.to_string())),
+            ProxyError::Foreign => (ErrorKind::Foreign, None),
+        }
+    }
+
+    fn number(value: Option<&Value>) -> Option<f64> {
+        value.and_then(Value::as_f64)
+    }
+
+    fn integer(value: Option<&Value>) -> Option<i64> {
+        value.and_then(Value::as_i64)
+    }
+
+    fn reset_at(value: Option<&Value>) -> Option<f64> {
+        let value = number(value)?;
+        Some(if value >= 1_000_000_000_000.0 {
+            value / 1000.0
+        } else {
+            value
+        })
+    }
+
+    fn quotas(value: &Value) -> Vec<Quota> {
+        let Some(reports) = value.get("reports").and_then(Value::as_array) else {
+            return Vec::new();
+        };
+        let mut rows = Vec::new();
+        for report in reports {
+            let provider_label = report
+                .get("label")
+                .or_else(|| report.get("provider"))
+                .and_then(Value::as_str)
+                .unwrap_or("unknown")
+                .to_owned();
+            let Some(quota) = report.get("quota") else {
+                continue;
+            };
+            let mut push = |percent: Option<&Value>, window_label: &str, reset: Option<&Value>| {
+                if percent.is_some() || reset.is_some() {
+                    rows.push(Quota {
+                        provider_label: provider_label.clone(),
+                        window_label: window_label.to_owned(),
+                        percent: number(percent),
+                        reset_at: reset_at(reset),
+                    });
+                }
+            };
+            push(
+                quota.get("fiveHourPercent"),
+                "5h",
+                quota.get("fiveHourResetAt"),
+            );
+            push(
+                quota.get("weeklyPercent"),
+                "week",
+                quota.get("weeklyResetAt"),
+            );
+            push(
+                quota.get("monthlyPercent"),
+                "month",
+                quota.get("monthlyResetAt"),
+            );
+            if let Some(windows) = quota.get("customWindows").and_then(Value::as_array) {
+                for window in windows {
+                    let label = window
+                        .get("label")
+                        .and_then(Value::as_str)
+                        .unwrap_or("window");
+                    push(window.get("percent"), label, window.get("resetAt"));
+                }
+            }
+        }
+        rows
+    }
+
+    fn chart(value: &Value, settings: &Value) -> Option<Chart> {
+        let start = number(value.get("start"))?;
+        let bucket_seconds = integer(value.get("bucketSeconds"))?;
+        let settings = settings.get("settings").unwrap_or(settings);
+        let style = settings
+            .get("chartStyle")
+            .and_then(Value::as_str)
+            .unwrap_or("line")
+            .to_owned();
+        let series = value
+            .get("series")
+            .and_then(Value::as_array)?
+            .iter()
+            .take(6)
+            .filter_map(|item| {
+                Some(Series {
+                    id: item.get("id")?.as_str()?.to_owned(),
+                    points: item
+                        .get("points")?
+                        .as_array()?
+                        .iter()
+                        .filter_map(Value::as_f64)
+                        .collect(),
+                })
+            })
+            .collect();
+        Some(Chart {
+            start,
+            bucket_seconds,
+            style,
+            series,
+        })
+    }
+
+    fn timeline_query(settings: &Value) -> String {
+        let settings = settings.get("settings").unwrap_or(settings);
+        let get = |key: &str, fallback: &str| {
+            settings
+                .get(key)
+                .and_then(Value::as_str)
+                .unwrap_or(fallback)
+                .to_owned()
+        };
+        let hours = settings
+            .get("chartHours")
+            .and_then(Value::as_i64)
+            .unwrap_or(24);
+        let bucket_minutes = settings
+            .get("bucketMinutes")
+            .and_then(Value::as_i64)
+            .unwrap_or(60);
+        let metric = get("tokenMetric", "total");
+        let aggregation = get("aggregation", "sum");
+        let grouping = get("chartGrouping", "model");
+        let mut query = format!(
+            "hours={hours}&bucketMinutes={bucket_minutes}&metric={metric}&aggregation={aggregation}&grouping={grouping}"
+        );
+        if let Some(models) = settings.get("models").and_then(Value::as_array) {
+            let models = models
+                .iter()
+                .filter_map(Value::as_str)
+                .collect::<Vec<_>>()
+                .join(",");
+            if !models.is_empty() {
+                query.push_str("&models=");
+                query.push_str(&models);
+            }
+        }
+        query
+    }
+
+    fn snapshot_path() -> PathBuf {
+        let home = std::env::var_os("HOME")
+            .map(PathBuf::from)
+            .unwrap_or_else(|| PathBuf::from("."));
+        home.join("Library/Containers/com.opencodex.desktop.widget/Data/Library/Application Support/OpenCodex/snapshot.json")
+    }
+
+    fn now_seconds() -> f64 {
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs_f64()
+    }
+
+    fn without_generated_at(snapshot: &Snapshot) -> Snapshot {
+        let mut snapshot = snapshot.clone();
+        snapshot.generated_at = 0.0;
+        snapshot
+    }
+
+    fn write_if_changed(
+        path: &std::path::Path,
+        previous: Option<&Snapshot>,
+        snapshot: &Snapshot,
+    ) -> std::io::Result<bool> {
+        if previous.map(without_generated_at).as_ref() == Some(&without_generated_at(snapshot)) {
+            return Ok(false);
+        }
+        let Some(directory) = path.parent() else {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidInput,
+                "snapshot path has no parent",
+            ));
+        };
+        fs::create_dir_all(directory)?;
+        let bytes = serde_json::to_vec(snapshot).map_err(std::io::Error::other)?;
+        let temporary = directory.join(format!(".snapshot-{}.tmp", Uuid::new_v4()));
+        fs::write(&temporary, bytes)?;
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            fs::set_permissions(&temporary, fs::Permissions::from_mode(0o600))?;
+        }
+        fs::rename(temporary, path)?;
+        Ok(true)
+    }
+
+    fn make_snapshot(
+        proxy: &ProxyClient,
+        settings: &Value,
+        health: &Value,
+        today: Option<&Value>,
+        quota_value: Option<&Value>,
+        timeline_value: Option<&Value>,
+    ) -> Snapshot {
+        let endpoint = proxy.endpoint();
+        let detail = {
+            let parts = [health.get("status"), health.get("protection")]
+                .into_iter()
+                .filter_map(|value| value.and_then(Value::as_str))
+                .filter(|part| !part.is_empty() && *part != "none")
+                .collect::<Vec<_>>();
+            (!parts.is_empty()).then(|| parts.join(" · "))
+        };
+        let today_snapshot = today
+            .and_then(|value| value.get("summary").or(Some(value)))
+            .map(|summary| Today {
+                requests: integer(summary.get("requests")),
+                total_tokens: integer(summary.get("totalTokens")),
+                estimated_cost_usd: number(summary.get("estimatedCostUsd")),
+            });
+        let quotas_value = quota_value.unwrap_or(&Value::Null);
+        let menu_title = tray::render_title(settings, today.unwrap_or(&Value::Null), quotas_value);
+        let chart = timeline_value.and_then(|value| chart(value, settings));
+        Snapshot {
+            schema_version: 1,
+            state: "running".into(),
+            state_title: "Running".into(),
+            detail,
+            endpoint_display: format!("{}:{}", endpoint.host, endpoint.port),
+            menu_title,
+            today: today_snapshot,
+            quotas: quotas(quotas_value),
+            chart,
+            last_updated: timeline_value.map(|_| now_seconds()),
+            generated_at: now_seconds(),
+        }
+    }
+
+    pub async fn write(proxy: ProxyClient) {
+        let health = match proxy.startup_health().await {
+            Ok(value) => value,
+            Err(error) => {
+                let (kind, detail) = proxy_error(&error);
+                let (state, state_title, detail) = state_for_error(kind, detail);
+                let snapshot = Snapshot {
+                    schema_version: 1,
+                    state: state.into(),
+                    state_title: state_title.into(),
+                    detail,
+                    endpoint_display: format!(
+                        "{}:{}",
+                        proxy.endpoint().host,
+                        proxy.endpoint().port
+                    ),
+                    menu_title: None,
+                    today: None,
+                    quotas: Vec::new(),
+                    chart: None,
+                    last_updated: None,
+                    generated_at: now_seconds(),
+                };
+                let path = snapshot_path();
+                let previous = fs::read(&path)
+                    .ok()
+                    .and_then(|bytes| serde_json::from_slice::<Snapshot>(&bytes).ok());
+                if let Err(error) = write_if_changed(&path, previous.as_ref(), &snapshot) {
+                    crate::logging::log_once("widget snapshot write failed", &error.to_string());
+                }
+                crate::logging::log_once("widget snapshot health failed", state);
+                return;
+            }
+        };
+        let settings = proxy
+            .companion_settings()
+            .await
+            .unwrap_or_else(|_| json!({ "settings": {} }));
+        let today = proxy.usage_today().await.ok();
+        let quota_value = proxy.quotas().await.ok();
+        let timeline_value = proxy.timeline(&timeline_query(&settings)).await.ok();
+        let snapshot = make_snapshot(
+            &proxy,
+            &settings,
+            &health,
+            today.as_ref(),
+            quota_value.as_ref(),
+            timeline_value.as_ref(),
+        );
+        let path = snapshot_path();
+        let previous = fs::read(&path)
+            .ok()
+            .and_then(|bytes| serde_json::from_slice::<Snapshot>(&bytes).ok());
+        if let Err(error) = write_if_changed(&path, previous.as_ref(), &snapshot) {
+            crate::logging::log_once("widget snapshot write failed", &error.to_string());
+        }
+    }
+
+    pub fn refresh(proxy: &ProxyClient) {
+        let proxy = proxy.clone();
+        tauri::async_runtime::spawn(async move { write(proxy).await });
+    }
+
+    #[cfg(test)]
+    mod tests {
+        use super::*;
+
+        #[test]
+        fn serialization_uses_swift_field_names() {
+            let snapshot = Snapshot {
+                schema_version: 1,
+                state: "running".into(),
+                state_title: "Running".into(),
+                detail: Some("ok".into()),
+                endpoint_display: "127.0.0.1:10100".into(),
+                menu_title: Some("2K".into()),
+                today: Some(Today {
+                    requests: Some(2),
+                    total_tokens: Some(1234),
+                    estimated_cost_usd: Some(0.12),
+                }),
+                quotas: vec![Quota {
+                    provider_label: "OpenAI".into(),
+                    window_label: "week".into(),
+                    percent: Some(10.0),
+                    reset_at: Some(1.0),
+                }],
+                chart: Some(Chart {
+                    start: 1.0,
+                    bucket_seconds: 3600,
+                    style: "line".into(),
+                    series: vec![Series {
+                        id: "openai/gpt".into(),
+                        points: vec![1.0, 2.0],
+                    }],
+                }),
+                last_updated: Some(2.0),
+                generated_at: 3.0,
+            };
+            assert_eq!(
+                serde_json::to_string(&snapshot).unwrap(),
+                r#"{"schemaVersion":1,"state":"running","stateTitle":"Running","detail":"ok","endpointDisplay":"127.0.0.1:10100","menuTitle":"2K","today":{"requests":2,"totalTokens":1234,"estimatedCostUsd":0.12},"quotas":[{"providerLabel":"OpenAI","windowLabel":"week","percent":10.0,"resetAt":1.0}],"chart":{"start":1.0,"bucketSeconds":3600,"style":"line","series":[{"id":"openai/gpt","points":[1.0,2.0]}]},"lastUpdated":2.0,"generatedAt":3.0}"#
+            );
+        }
+
+        #[test]
+        fn error_state_mapping_covers_every_kind() {
+            assert_eq!(
+                state_for_error(ErrorKind::Unreachable, None).0,
+                "unreachable"
+            );
+            assert_eq!(
+                state_for_error(ErrorKind::Unauthorized, None).0,
+                "unauthorized"
+            );
+            assert_eq!(
+                state_for_error(ErrorKind::Http, Some("HTTP 500".into())).0,
+                "degraded"
+            );
+            assert_eq!(
+                state_for_error(ErrorKind::Decode, Some("bad".into())).0,
+                "degraded"
+            );
+            assert_eq!(state_for_error(ErrorKind::Foreign, None).0, "foreign");
+        }
+
+        #[test]
+        fn a_foreign_runtime_is_not_reported_as_a_failure() {
+            // The mapping is the whole point of the variant. Folding it into either neighbour
+            // tells a user whose own CLI or npm runtime holds the port that something is broken,
+            // and the widget is the one surface where that claim is read without any context.
+            assert_eq!(proxy_error(&ProxyError::Foreign).0, ErrorKind::Foreign);
+            let (state, title, detail) = state_for_error(ErrorKind::Foreign, None);
+            assert_eq!(state, "foreign");
+            assert_eq!(title, "External runtime");
+            assert!(detail.unwrap().contains("did not start"));
+        }
+
+        #[test]
+        fn write_if_changed_ignores_generated_at() {
+            let path = std::env::temp_dir().join(format!("ocx-widget-{}.json", std::process::id()));
+            let snapshot = Snapshot {
+                schema_version: 1,
+                state: "running".into(),
+                state_title: "Running".into(),
+                detail: None,
+                endpoint_display: "127.0.0.1:10100".into(),
+                menu_title: None,
+                today: None,
+                quotas: Vec::new(),
+                chart: None,
+                last_updated: None,
+                generated_at: 1.0,
+            };
+            assert!(write_if_changed(&path, None, &snapshot).unwrap());
+            let mut changed = snapshot.clone();
+            changed.generated_at = 2.0;
+            assert!(!write_if_changed(&path, Some(&snapshot), &changed).unwrap());
+            let _ = fs::remove_file(path);
+        }
+
+        #[test]
+        fn chart_series_are_truncated_to_six() {
+            let series = (0..8)
+                .map(|index| json!({ "id": index.to_string(), "points": [1] }))
+                .collect::<Vec<_>>();
+            let value = json!({ "start": 1, "bucketSeconds": 60, "series": series });
+            let result = chart(&value, &json!({ "settings": { "chartStyle": "line" } })).unwrap();
+            assert_eq!(result.series.len(), 6);
+        }
+    }
+}
+
+#[cfg(target_os = "macos")]
+pub(crate) use macos::refresh;
+
+#[cfg(not(target_os = "macos"))]
+pub(crate) fn refresh(_: &crate::proxy::ProxyClient) {}
diff --git a/desktop/src-tauri/src/window.rs b/desktop/src-tauri/src/window.rs
new file mode 100644
index 00000000000..81969f7189e
--- /dev/null
+++ b/desktop/src-tauri/src/window.rs
@@ -0,0 +1,160 @@
+use crate::{auth::Auth, exit, AppState};
+use tauri::{AppHandle, Manager, Url, WebviewWindow, WindowEvent};
+
+pub fn webview_user_agent() -> String {
+    let platform = if cfg!(target_os = "macos") {
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko)"
+    } else if cfg!(target_os = "windows") {
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko)"
+    } else {
+        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)"
+    };
+    format!("{platform} {}", Auth::user_agent())
+}
+
+/// Decide what closing this window means, at the moment it is closed.
+///
+/// The answer is not known when the window is built: on Linux it depends on a session-bus probe
+/// that the startup sequence runs afterwards. So it is read here rather than captured. With a tray
+/// a close hides and the runtime keeps serving; without one there is nowhere to hide, so D6 makes
+/// the close a quit — and it takes the same graceful drain the tray's Quit does.
+pub fn configure(window: &WebviewWindow) {
+    let window_for_close = window.clone();
+    window.on_window_event(move |event| {
+        if let WindowEvent::CloseRequested { api, .. } = event {
+            api.prevent_close();
+            exit::gesture(window_for_close.app_handle());
+        }
+    });
+}
+
+/// Where this window may navigate.
+///
+/// The loopback endpoint is read from the app rather than captured, because the window now exists
+/// before anything has been resolved. Until it has, an http target is refused outright instead of
+/// being handed to the browser: nothing should be navigating anywhere yet, and opening an
+/// unresolved address in the user's browser is a worse answer than doing nothing.
+pub fn navigation_allowed(app: AppHandle) -> impl Fn(&Url) -> bool {
+    move |url| {
+        if is_app_origin(url) {
+            return true;
+        }
+        if url.scheme() == "about" && url.as_str() == "about:blank" {
+            return true;
+        }
+        let endpoint = app
+            .try_state::<AppState>()
+            .and_then(|state| state.proxy())
+            .map(|proxy| proxy.endpoint());
+        if let Some(endpoint) = endpoint {
+            if url.scheme() == "http" && url.host_str() == Some(endpoint.host) {
+                return url.port_or_known_default() == Some(endpoint.port);
+            }
+            if matches!(url.scheme(), "http" | "https") {
+                let _ = tauri_plugin_opener::open_url(url.as_str(), None::<&str>);
+            }
+        }
+        false
+    }
+}
+
+/// The bundled `frontendDist` origin.
+///
+/// Tauri serves it as `tauri://localhost` on macOS and Linux, and as `http://tauri.localhost` on
+/// Windows, where WebView2 has no custom-scheme support. Without that second spelling the window's
+/// first navigation to its own page on Windows falls through to the branch that hands a URL to the
+/// external browser.
+///
+/// It is that one host and nothing near it. `https` is not the scheme the pinned Tauri serves the
+/// app over, and a port means something else is answering rather than the app — neither localhost
+/// generally, nor a name that merely ends in it, is this origin.
+fn is_app_origin(url: &Url) -> bool {
+    match url.scheme() {
+        "tauri" => true,
+        "http" => url.host_str() == Some("tauri.localhost") && url.port().is_none(),
+        _ => false,
+    }
+}
+
+pub fn show(window: &WebviewWindow) {
+    let _ = window.show();
+    let _ = window.set_focus();
+    apply_tray_policy(window.app_handle(), true);
+}
+
+pub fn hide(window: &WebviewWindow) {
+    let _ = window.hide();
+    apply_tray_policy(window.app_handle(), false);
+}
+
+#[cfg(target_os = "macos")]
+fn apply_tray_policy(app: &AppHandle, visible: bool) {
+    let policy = if visible {
+        tauri::ActivationPolicy::Regular
+    } else {
+        tauri::ActivationPolicy::Accessory
+    };
+    let _ = app.set_dock_visibility(visible);
+    let _ = app.set_activation_policy(policy);
+}
+
+#[cfg(not(target_os = "macos"))]
+fn apply_tray_policy(_app: &AppHandle, _visible: bool) {}
+
+pub fn set_tray_policy(app: &AppHandle, visible: bool) {
+    apply_tray_policy(app, visible);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{is_app_origin, webview_user_agent};
+    use tauri::Url;
+
+    fn url(value: &str) -> Url {
+        Url::parse(value).expect("a url")
+    }
+
+    #[test]
+    fn the_app_origin_is_allowed_by_both_spellings_on_every_platform() {
+        // The custom scheme everywhere, and the http spelling WebView2 needs on Windows. The
+        // second is not gated on the platform: the origin is the app's wherever it is served.
+        assert!(is_app_origin(&url(
+            "tauri://localhost/index.html?port=10100"
+        )));
+        assert!(is_app_origin(&url(
+            "http://tauri.localhost/index.html?port=10100"
+        )));
+    }
+
+    #[test]
+    fn nothing_near_that_origin_is_that_origin() {
+        for value in [
+            // Not the scheme the pinned Tauri serves the app over.
+            "https://tauri.localhost/index.html",
+            // A port means something else is answering.
+            "http://tauri.localhost:8080/",
+            // Neither localhost generally nor a name that merely contains it.
+            "http://localhost/",
+            "http://127.0.0.1/",
+            "http://evil.tauri.localhost/",
+            "http://tauri.localhost.example.com/",
+            "file:///C:/index.html",
+        ] {
+            assert!(!is_app_origin(&url(value)), "{value}");
+        }
+    }
+
+    #[test]
+    fn webview_user_agent_marks_the_desktop_shell() {
+        let user_agent = webview_user_agent();
+        assert!(user_agent.starts_with("Mozilla/5.0 "));
+        assert!(user_agent.contains("OpenCodexDesktop/"));
+        if cfg!(target_os = "macos") {
+            assert!(user_agent.contains("(Macintosh; Intel Mac OS X 10_15_7)"));
+        } else if cfg!(target_os = "windows") {
+            assert!(user_agent.contains("(Windows NT 10.0; Win64; x64)"));
+        } else {
+            assert!(user_agent.contains("(X11; Linux x86_64)"));
+        }
+    }
+}
diff --git a/desktop/src-tauri/tauri.conf.json b/desktop/src-tauri/tauri.conf.json
new file mode 100644
index 00000000000..83b2dc18886
--- /dev/null
+++ b/desktop/src-tauri/tauri.conf.json
@@ -0,0 +1,72 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "OpenCodex",
+  "version": "2.61.0",
+  "identifier": "com.opencodex.desktop",
+  "build": {
+    "frontendDist": "../ui",
+    "devUrl": "http://localhost:1420"
+  },
+  "app": {
+    "withGlobalTauri": true,
+    "security": {
+      "csp": "default-src 'self'; connect-src 'self' http://127.0.0.1:*; style-src 'self' 'unsafe-inline'; script-src 'self'"
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": "all",
+    "createUpdaterArtifacts": true,
+    "externalBin": [
+      "binaries/ocx"
+    ],
+    "resources": {
+      "resources/gui/dist": "gui/dist"
+    },
+    "icon": [
+      "icons/icon.icns",
+      "icons/icon.ico",
+      "icons/icon.png"
+    ],
+    "macOS": {
+      "minimumSystemVersion": "13.0",
+      "files": {
+        "PlugIns/OpenCodexWidget.appex": "widget/OpenCodexWidget.appex"
+      },
+      "dmg": {
+        "appPosition": {
+          "x": 180,
+          "y": 170
+        },
+        "applicationFolderPosition": {
+          "x": 480,
+          "y": 170
+        }
+      }
+    },
+    "windows": {
+      "webviewInstallMode": {
+        "type": "downloadBootstrapper"
+      },
+      "wix": {
+        "language": "en-US"
+      }
+    },
+    "linux": {
+      "deb": {
+        "depends": []
+      },
+      "appimage": {
+        "bundleMediaFramework": false
+      }
+    }
+  },
+  "plugins": {
+    "updater": {
+      "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IEFDNzZCMDg0NkVCRUJGODEKUldTQnY3NXVoTEIyckhRUXJMOXJRUDR0aHQ2L3pLVHVweXFSc1lzS24vWDNiSUJ5MXJIZmpyb2sK",
+      "endpoints": [
+        "https://github.com/lidge-jun/opencodex/releases/latest/download/latest.json"
+      ]
+    }
+  }
+}
diff --git a/desktop/ui/index.html b/desktop/ui/index.html
new file mode 100644
index 00000000000..f42074944ce
--- /dev/null
+++ b/desktop/ui/index.html
@@ -0,0 +1,57 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>OpenCodex</title>
+    <style>
+      :root { color-scheme: light dark; font: 15px system-ui, sans-serif; }
+      body { display: grid; min-height: 100vh; place-items: center; margin: 0; background: #f5f5f7; color: #202124; }
+      main { width: min(38rem, calc(100vw - 3rem)); padding: 2rem; border-radius: 1rem; background: white; box-shadow: 0 8px 30px #0001; }
+      h1 { margin-top: 0; font-size: 1.4rem; }
+      #headline { margin: 0 0 .25rem; font-weight: 600; }
+      #detail { margin: 0; min-height: 1.4rem; color: #666; font-size: .9rem; }
+      #phases { margin: 1.25rem 0 0; padding: 0; list-style: none; display: grid; gap: .4rem; }
+      #phases li { display: flex; gap: .6rem; align-items: baseline; color: #8a8a8e; }
+      #phases li .mark { width: 1rem; text-align: center; }
+      #phases li[data-state="active"] { color: #202124; font-weight: 600; }
+      #phases li[data-state="done"] { color: #4b8b3b; }
+      #phases li[data-state="failed"] { color: #b3261e; font-weight: 600; }
+      #failure { margin-top: 1.25rem; display: grid; gap: .75rem; }
+      #failure[hidden] { display: none; }
+      .actions { display: flex; gap: .6rem; align-items: center; }
+      button { border: 0; border-radius: .5rem; padding: .6rem 1rem; background: #2563eb; color: white; cursor: pointer; font: inherit; }
+      button.secondary { background: #e3e3e8; color: #202124; }
+      button[disabled] { opacity: .5; cursor: default; }
+      #copyState { color: #666; font-size: .85rem; }
+      textarea { width: 100%; box-sizing: border-box; min-height: 9rem; resize: vertical; font: 12px ui-monospace, SFMono-Regular, Menlo, monospace; border-radius: .5rem; border: 1px solid #0002; padding: .6rem; background: #fafafa; color: inherit; }
+      @media (prefers-color-scheme: dark) {
+        body { background: #1c1c1e; color: #f5f5f7; }
+        main { background: #2c2c2e; }
+        #detail, #copyState { color: #bbb; }
+        #phases li[data-state="active"] { color: #f5f5f7; }
+        #phases li[data-state="done"] { color: #8bd17c; }
+        #phases li[data-state="failed"] { color: #ff8a80; }
+        button.secondary { background: #3a3a3c; color: #f5f5f7; }
+        textarea { background: #1c1c1e; border-color: #ffffff22; }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>OpenCodex</h1>
+      <p id="headline">Starting OpenCodex…</p>
+      <p id="detail"></p>
+      <ol id="phases"></ol>
+      <div id="failure" hidden>
+        <div class="actions">
+          <button id="retry" type="button">Retry</button>
+          <button id="copy" class="secondary" type="button">Copy diagnostic</button>
+          <span id="copyState"></span>
+        </div>
+        <textarea id="diagnostic" readonly spellcheck="false"></textarea>
+      </div>
+    </main>
+    <script src="./main.js"></script>
+  </body>
+</html>
diff --git a/desktop/ui/main.js b/desktop/ui/main.js
new file mode 100644
index 00000000000..6431ac08230
--- /dev/null
+++ b/desktop/ui/main.js
@@ -0,0 +1,154 @@
+// The bootstrap page is the startup surface. It does not probe anything itself: the shell owns the
+// sequence, its deadline and its diagnostic, and this page renders what it is told. The phase list
+// is asked for rather than written here, so a state added in the shell appears without a second
+// edit — and one removed cannot leave a row behind.
+//
+// What each row shows comes from the shell too, including the states already finished. Rebuilding
+// that history from events would be wrong: the first states finish in milliseconds, so a page whose
+// listener attached a moment late would show a run in progress with nothing behind it.
+//
+// Nothing here uses alert, confirm or prompt. The embedded webview implements none of the
+// WKUIDelegate panel methods on macOS, so a platform dialog is silently declined and the user sees
+// nothing at all. Every message this page has goes into the page — including its own failures,
+// because a surface that cannot report is the problem this file exists to fix.
+
+const bridge = window.__TAURI__;
+const invoke = bridge && bridge.core && bridge.core.invoke;
+const listen = bridge && bridge.event && bridge.event.listen;
+
+// The shell owns the sequence and its deadline. The page has no deadline of its own: an invoke
+// whose command never answers returns a promise that neither settles nor rejects, and the page
+// then keeps its initial markup forever - the headline still says the run is starting, the
+// checklist is empty, and the only thing on screen is a Retry button with an empty diagnostic.
+// That is indistinguishable from a hung product. Bounding the handshake turns the silence into a
+// failure the page can report and the user can copy.
+const HANDSHAKE_DEADLINE_MS = 5000;
+
+function withDeadline(work, what) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error('the shell did not answer ' + what + ' within ' + HANDSHAKE_DEADLINE_MS + ' ms'));
+    }, HANDSHAKE_DEADLINE_MS);
+    Promise.resolve(work).then(
+      (value) => { clearTimeout(timer); resolve(value); },
+      (error) => { clearTimeout(timer); reject(error); },
+    );
+  });
+}
+
+const headline = document.querySelector("#headline");
+const detail = document.querySelector("#detail");
+const phaseList = document.querySelector("#phases");
+const failure = document.querySelector("#failure");
+const retry = document.querySelector("#retry");
+const copy = document.querySelector("#copy");
+const copyState = document.querySelector("#copyState");
+const diagnostic = document.querySelector("#diagnostic");
+
+const MARKS = { done: "✓", failed: "✕", active: "…", pending: "·" };
+
+let phases = [];
+
+function render(progress) {
+  const completed = new Set((progress && progress.completed) || []);
+  const failedPhase = (progress && progress.failedPhase) || null;
+  const current = progress && progress.phase;
+  phaseList.replaceChildren();
+  for (const phase of phases) {
+    let state = "pending";
+    if (phase.id === failedPhase) {
+      state = "failed";
+    } else if (phase.id === current) {
+      state = "active";
+    } else if (completed.has(phase.id)) {
+      state = "done";
+    }
+    const row = document.createElement("li");
+    row.dataset.state = state;
+    const mark = document.createElement("span");
+    mark.className = "mark";
+    mark.textContent = MARKS[state];
+    const label = document.createElement("span");
+    label.textContent = phase.label;
+    row.append(mark, label);
+    phaseList.append(row);
+  }
+}
+
+function apply(progress) {
+  if (!progress) return;
+  headline.textContent = progress.label;
+  detail.textContent = progress.detail || "";
+  const failed = progress.phase === "failed";
+  failure.hidden = !failed;
+  retry.disabled = !progress.canRetry;
+  if (failed) {
+    diagnostic.value = progress.diagnostic || "";
+    copyState.textContent = "";
+  }
+  render(progress);
+}
+
+function reportPageFailure(message, error) {
+  const cause = error && error.message ? error.message : String(error);
+  headline.textContent = "OpenCodex could not read its own startup state.";
+  detail.textContent = message;
+  failure.hidden = false;
+  retry.disabled = false;
+  diagnostic.value = [message, cause].join("\n");
+}
+
+async function copyDiagnostic() {
+  const text = diagnostic.value;
+  if (!text) return;
+  try {
+    await navigator.clipboard.writeText(text);
+    copyState.textContent = "Copied to the clipboard.";
+    return;
+  } catch {
+    // A webview without clipboard access is the reason the text is on screen in the first place.
+  }
+  diagnostic.focus();
+  diagnostic.select();
+  let copied = false;
+  try {
+    copied = document.execCommand("copy");
+  } catch {
+    copied = false;
+  }
+  copyState.textContent = copied
+    ? "Copied to the clipboard."
+    : "The text above is selected — copy it with your keyboard.";
+}
+
+retry.addEventListener("click", async () => {
+  if (!invoke) return;
+  copyState.textContent = "";
+  retry.disabled = true;
+  try {
+    await invoke("retry_startup");
+  } catch (error) {
+    reportPageFailure("The retry could not be sent to the shell.", error);
+  }
+});
+copy.addEventListener("click", copyDiagnostic);
+
+async function start() {
+  if (!invoke || !listen) {
+    headline.textContent = "This page is the OpenCodex desktop shell's startup surface.";
+    detail.textContent = "Open it from the OpenCodex app.";
+    return;
+  }
+  try {
+    phases = (await withDeadline(invoke("startup_phases"), "startup_phases")).filter((phase) => !phase.terminal);
+    render(null);
+    // The listener goes on before the snapshot is read, so a transition landing between the two is
+    // delivered rather than lost.
+    await withDeadline(listen("startup-phase", (event) => apply(event.payload)), "the startup-phase subscription");
+    apply(await withDeadline(invoke("startup_snapshot"), "startup_snapshot"));
+  } catch (error) {
+    reportPageFailure("The startup surface could not reach the shell.", error);
+  }
+}
+
+start();
diff --git a/devlog/_fin/260725_macos_menubar_app/003_design_read.md b/devlog/_fin/260725_macos_menubar_app/003_design_read.md
index f3ec2d33856..0a6d4802489 100644
--- a/devlog/_fin/260725_macos_menubar_app/003_design_read.md
+++ b/devlog/_fin/260725_macos_menubar_app/003_design_read.md
@@ -113,7 +113,7 @@ column.
 ├──────────────────────────────────────┤
 │ LAST 7 DAYS                          │  range echoed from the response
 │ REQUESTS      TOKENS         COST    │  micro labels, 10px, letterspaced
-│ 1,746         12.4M         $8.21    │  tabular-nums, 13px
+│ 1,746         12M           $8.21    │  tabular-nums, 13px
 │ ▁▂▃▅▂▁▃                              │  7d usage trend from usage.days[]
 ├──────────────────────────────────────┤
 │ OpenAI          ▓▓▓▓▓░░░░░  44%      │  quota rows, one per provider
@@ -170,7 +170,7 @@ Live data reaches `requests: 232507`, `totalTokens: 36536664705`,
 `estimatedCostUsd: 34018.25`. Rules:
 
 - Counts: `1,746` → `12.4K` → `1.2M` (3 significant figures, SI suffix at 10 000).
-- Tokens: always suffixed (`12.4M`, `36.5B`).
+- Tokens: always suffixed with integer values (`12M`, `37B`).
 - Cost: `$8.21` below 1 000, `$34.0K` above.
 - All numerics use `tabular-nums` so digits do not reflow while polling.
 - Timestamps normalize by magnitude: values below `1e12` are seconds, at or above are
diff --git a/devlog/_fin/260725_macos_menubar_app/010_phase1_core.md b/devlog/_fin/260725_macos_menubar_app/010_phase1_core.md
index f6f8c854cbe..1dded9edf28 100644
--- a/devlog/_fin/260725_macos_menubar_app/010_phase1_core.md
+++ b/devlog/_fin/260725_macos_menubar_app/010_phase1_core.md
@@ -399,7 +399,7 @@ seconds and anthropic milliseconds both resolve to sane 2026 dates · `ProxySett
 decodes without a `defaultProvider` field and `ProxyConfigSummary` supplies it.
 
 `FormattingTests`: the `002` magnitudes (`232507`, `36536664705`, `34018.25`) render as
-`232K`, `36.5B`, `$34.0K` · `nil` renders `—` · zero renders `0`, not `—`.
+`232K`, `37B`, `$34.0K` · `nil` renders `—` · zero renders `0`, not `—`.
 
 ## `app/.gitignore`
 
diff --git a/devlog/_fin/260725_macos_menubar_app/020_phase2_ui.md b/devlog/_fin/260725_macos_menubar_app/020_phase2_ui.md
index 28fbf346144..95126dceb3c 100644
--- a/devlog/_fin/260725_macos_menubar_app/020_phase2_ui.md
+++ b/devlog/_fin/260725_macos_menubar_app/020_phase2_ui.md
@@ -184,7 +184,7 @@ shown as selectable text — displayed, never executed (`002` §3).
 
 Three columns from `/api/usage?range=7d`: REQUESTS, TOKENS, COST. Labels in
 `Theme.micro` uppercase with 0.5pt tracking; values in `Theme.numeric`. All values
-through `Format` (`010`), so `36536664705` becomes `36.5B` and `nil` becomes `—`.
+through `Format` (`010`), so `36536664705` becomes `37B` and `nil` becomes `—`.
 
 **The range label is rendered from the response, not the request.** `002` §3 records that
 `parseRange` silently falls back to `30d` for any unrecognized value, so a UI that
diff --git a/devlog/_fin/260725_macos_menubar_app/051_feature_summary.md b/devlog/_fin/260725_macos_menubar_app/051_feature_summary.md
new file mode 100644
index 00000000000..3de9b2b95e0
--- /dev/null
+++ b/devlog/_fin/260725_macos_menubar_app/051_feature_summary.md
@@ -0,0 +1,12 @@
+# 051 — Feature summary
+
+The macOS companion now shares the proxy's canonical usage accounting across the menu bar
+app, widget, and dashboard Usage companion section. The proxy owns the
+`/api/usage/timeline` and `/api/companion/settings` contracts; `ocx companion` provides
+matching read/write controls with `show`, `set`, and `reset` subcommands.
+
+The menu bar app renders a settings-driven title, today metrics, model/account/provider
+sections, and a timeline chart. It writes a privacy-safe snapshot for the WidgetKit
+companion, which supports small, medium, and large families and links back to Usage.
+The default menu bar headline is total tokens; the dashboard can switch it to requests,
+cost, quota, or icon-only display.
diff --git a/devlog/_fin/260921_brand_icon_and_menu_bar_mark/000_plan.md b/devlog/_fin/260921_brand_icon_and_menu_bar_mark/000_plan.md
new file mode 100644
index 00000000000..35d6b14a3be
--- /dev/null
+++ b/devlog/_fin/260921_brand_icon_and_menu_bar_mark/000_plan.md
@@ -0,0 +1,95 @@
+# Brand icon and menu bar mark
+
+The shipped app icon is not the product's mark. `desktop/src-tauri/icons/*` derives from an empty
+rounded-square ring that came in with the Tauri template, and the vector source written for it in
+#5329 reproduced that ring faithfully — the measurement was right and the subject was wrong.
+
+Two consequences, both visible on a Mac today. The artwork covers 21.4% of the 1024px canvas and
+has transparent corners, so macOS 26/27 classifies it as a uniquely shaped icon, strips it onto a
+default grey tile and scales it down; Finder shows a grey square with a small black ring in it.
+And the menu bar carries the same ring, so nothing on screen says which product this is.
+
+The real mark already exists in the repository. `assets/logo-light.png` is the mark on
+transparency at 512px and `gui/public/favicon.png` is its app-icon composition at 128px: a light
+squircle behind a dark six-lobed cloud that holds a `>` and a `_`, flanked by `{` and `}`, inside a
+dashed orbit with a dot at top and bottom. Neither has a vector source, and `gui/src/icons.tsx`
+holds only 24x24 line icons, so there is nothing to reuse — the vector has to be produced.
+
+## Where the geometry comes from
+
+The silhouette is measured, not redrawn. `assets/logo-light.png` is pure black with a shaped alpha
+channel, so the outline is the alpha channel: upsample it 4x to 2048px, threshold at alpha 110,
+trace with potrace, and map the result back into the 512-unit source space. That yields exactly
+nine subpaths — cloud, two braces, four orbit arcs, two dots — and re-rendering them at 512px
+disagrees with the thresholded source in **188 of 262144 pixels (0.072%)**, which is antialiasing
+rather than a different shape.
+
+The prompt glyphs cannot be traced. In the source they are engraved: alpha 217+ against a 206 body,
+with a lit rim along one edge. Composited at 512px that reads as depth; at 128px and below it reads
+as nothing, and an app icon spends most of its life at 32px. Thresholding the emboss produces a
+ragged chevron because the lit edge falls below the threshold asymmetrically.
+
+They are redrawn as flat geometry on the measured centreline instead:
+
+| glyph | measurement (512 source space) | drawn as |
+| --- | --- | --- |
+| `>` | rows 214-238 give the upper arm centreline slope 0.5625; rows 254-278 give the lower arm slope -0.5833; the two meet at (214.6, 244); tips at y 196.5 and 292.5 | polyline `193.4 206.5 -> 214.6 244 -> 193.4 281.5`, stroke 22, round cap and join |
+| `_` | x 253-324.5, y 271-293.5, ends semicircular | rect 71 x 22.5, rx 11.25 at (253.5, 271) |
+
+Checked against the source: the chevron's predicted horizontal cross-section is 25.3px against 25px
+measured, and the underscore's cap curvature lands within one pixel at both ends.
+
+## Shape of the change
+
+The glyphs are a **mask** rather than a lighter fill. Cutting them out of the mark makes the
+backdrop show through, which is the flat reading of an engraved groove, and it is also what gives
+the menu bar template real holes instead of a black blob.
+
+The backdrop is a **full-bleed opaque square**, not a pre-rounded tile. Apple's current app icon
+guidance asks for a square, unmasked, full-bleed 1024px source and applies the rounded-rectangle
+mask and material itself; a baked corner fights that and shows as jagged edges. The 824px inner
+tile with a transparent margin is the pre-Tahoe recipe, and the transparent margin is precisely
+what triggers today's grey fallback.
+
+Files:
+
+- `desktop/src-tauri/icons/icon.svg` — replaced. Full-bleed `#fcfcfc` backdrop, mark in `#2c2c2c`,
+  glyphs cut by `mask#prompt`, mark placed by `translate(2 26) scale(2)` so the orbit centre sits on
+  the canvas centre and the ink keeps the 77% coverage the favicon composition uses.
+- `desktop/src-tauri/icons/tray/icon.svg` — new. Same curves, no backdrop, black fill, orbit and
+  dots dropped because at 22pt a dashed circle resolves into grey specks. viewBox is the ink bounds
+  of what is left plus 6%, so the glyph fills the menu bar height rather than the source margin.
+- `desktop/scripts/generate-icons.ts` — `render()` takes a source, and the run emits
+  `tray/icon.png` at 44px (22pt at @2x) alongside the existing seventeen. Both `icons` and
+  `icons:check` cover it.
+- `tests/ci-workflows/build-desktop-icon-set.test.ts` — two additions. The tray raster has to be the
+  size the generator declares and the generator has to actually render and report it, and the tray
+  source has to carry the app icon's mask verbatim, wire it onto the mark, and draw distinct curves
+  that all appear in `icon.svg`.
+
+  Subset alone was too weak, and a review caught it: every interesting way of breaking the tray
+  removes something, so a strict subset stays a subset. Dropping the mask, deleting the underscore
+  or repeating a brace in place of the cloud each ship a black blob with green CI. Each of those,
+  plus removing the generator's tray render and removing its `produced.push`, was applied and run:
+  all five turn the suite red at 6 pass / 1 fail, and the restored tree is 7 pass / 0 fail.
+
+Nothing in `desktop/src-tauri/src/tray.rs` changes: it already builds the tray with
+`.icon_as_template(true)`, and the asset it includes is the file being replaced.
+
+## Acceptance
+
+1. `cd desktop && bun run icons:check` reports every generated artifact matching the source, tray included.
+2. `tests/ci-workflows/build-desktop-icon-set.test.ts` passes, and its drift guard fails when the
+   tray source is perturbed.
+3. `icon.png` is fully opaque, and `tray/icon.png` is 44x44 with no non-black opaque pixel.
+4. The change lands on `dev`, and a locally built and installed app shows the mark in Finder, the
+   Dock and the menu bar.
+
+## Recorded results
+
+- silhouette trace vs source alpha: 188 / 262144 px (0.072%).
+- `icon.png` opaque coverage: 21.4% before, 100.0% after.
+- `tray/icon.png`: 44x44, 759 pixels with alpha above zero — 498 fully opaque and 261 antialiased
+  — and no pixel with alpha whose colour is anything but black, which is what a template image has
+  to be. Both prompt glyphs are transparent holes rather than white fill.
+- `cd desktop && bun run icons` regenerated 18 artifacts; `bun run icons:check` reported 18 matching. Both are desktop package scripts and fail from the repository root.
diff --git a/devlog/_fin/260921_brand_icon_and_menu_bar_mark/010_favicons.md b/devlog/_fin/260921_brand_icon_and_menu_bar_mark/010_favicons.md
new file mode 100644
index 00000000000..6e09e5c5973
--- /dev/null
+++ b/devlog/_fin/260921_brand_icon_and_menu_bar_mark/010_favicons.md
@@ -0,0 +1,54 @@
+# The dashboard and documentation favicons
+
+The desktop app now renders its icon and its menu bar image from one traced vector. The two
+favicons the product serves are still hand-made rasters with no source, and one of them is broken
+in a way the file itself does not show.
+
+`docs-site/public/favicon.png` is the dark variant of the mark: white on transparency, 192px,
+36225 of 36864 pixels carrying some alpha but every one of them RGB `(255,255,255)`, exactly one
+fully opaque pixel, corner `(255,255,255,3)`. Composited on white it is a white square. A browser
+tab strip is light by default and Starlight names the favicon unconditionally, so the documentation
+site effectively has no favicon in light mode. `favicon.ico` beside it carries the same artwork at
+16, 32 and 48, also with no fully opaque pixel.
+
+`gui/public/favicon.png` is the light composition and looks right at 128px, but it is a bitmap no
+source can regenerate, and it is the shaded artwork rather than the flat mark: its engraved prompt
+all but disappears at 16 and 32. Rendering the vector at 128 differs from it in 68% of pixels. That
+is a visible simplification, not only a deduplication, and it is the same trade the app icon made.
+
+This unit covers the favicons and nothing else. Starlight's `logo-light.png` and `logo-dark.png`
+stay independent 512px rasters — they are the brand artwork the vector was traced from, not
+derived assets. `og.png` also stays, and carries a separate pre-existing defect worth its own
+scope: `docs-site/astro.config.mjs` declares it 1200x630 while the committed file is 1536x1024.
+
+## Shape of the change
+
+- `scripts/lib/icon-render.ts` — new. The renderer, the RGBA re-encode and the ICO packer move here
+  out of `desktop/scripts/generate-icons.ts`, which keeps its size tables and imports them. Two
+  generators sharing one renderer is the point; a second copy of the PNG re-encode would be a
+  second place for the alpha bug to come back.
+- `scripts/brand-favicons.ts` — new. Renders `desktop/src-tauri/icons/icon.svg` into
+  `gui/public/favicon.png` (128), `docs-site/public/favicon.png` (192) and
+  `docs-site/public/favicon.ico` (16, 32, 48) — the names, sizes and formats the two sites already
+  reference, so no page or config changes. `--check` regenerates into scratch and compares bytes,
+  the same contract the desktop set has.
+- `package.json` — `favicons` and `favicons:check`.
+- `tests/ci-workflows/brand-favicons.test.ts` — new, registered in `scripts/test-layout/layout.json`
+  and `tests/fixtures/test-layout-expected.json`. Asserts the declared sizes match what the two
+  sites ask for, that each committed favicon is that size with its alpha channel intact, that the
+  ICO carries exactly the declared sizes as embedded PNGs, and that both favicons read on a light
+  tab.
+
+  That last one is why the test decodes pixels. An opaque corner alone is not enough: a plain white
+  square has an opaque corner and is still invisible. So it requires an opaque light corner **and**
+  at least 10% of the image to be opaque pixels whose luminance differs from that corner by more
+  than 64 — the mark actually being there.
+
+## Acceptance
+
+1. `bun run favicons:check` reports every favicon matching the source.
+2. The new test fails on both ways of being invisible, checked by applying each: the
+   white-on-transparent artwork this replaces gives 3 pass / 1 fail, and a solid `#fcfcfc` square
+   gives 3 pass / 1 fail. The generated favicons give 4 pass / 0 fail.
+3. `bun run privacy:scan`, `bun run structure:check` and the two test-layout guards stay green.
+
diff --git a/devlog/_fin/260921_brand_icon_and_menu_bar_mark/020_closure.md b/devlog/_fin/260921_brand_icon_and_menu_bar_mark/020_closure.md
new file mode 100644
index 00000000000..858cadede98
--- /dev/null
+++ b/devlog/_fin/260921_brand_icon_and_menu_bar_mark/020_closure.md
@@ -0,0 +1,66 @@
+# Outcome
+
+Three changes landed on `dev`, in this order:
+
+| commit | pull request | change |
+| --- | --- | --- |
+| `a2d35a609e` | #5355 | the app icon and the menu bar mark, traced from the brand artwork |
+| `5794348b0d` | #5356 | the alpha channel every generated icon needs |
+| `917d690ecb` | #5361 | the dashboard and documentation favicons, from the same vector |
+
+## Verified on screen
+
+- **Finder and Dock.** Built locally with `bun run build:local`, signed with the Developer ID
+  identity the installed app already carried, installed to `/Applications` and relaunched. Finder
+  shows the mark on the system rounded rectangle: macOS masks the full-bleed square itself, which
+  is what the square, unmasked source is for. The widget extension still registers with
+  `pluginkit` under `com.opencodex.desktop.widget`, so replacing the bundle did not cost it.
+- **Menu bar.** The status item renders the template mark with both prompt glyphs as holes,
+  tinted by macOS, next to the usage label. Both that and the Finder icon are recorded in
+  `assets/pr-screenshots/app-icon-finder-menubar.png`.
+- **Browser tabs.** The two favicons were served over loopback HTTP and opened in a browser. Both
+  read as the mark on a light tile at tab size. This is the claim `010_favicons.md` makes, checked
+  in a tab rather than in a composite. `assets/pr-screenshots/favicon-browser-tab.png` is the tab
+  strip itself, not a rendering of one.
+
+## The defect the build caught
+
+`bun run build:local` failed on the first head with
+`error: proc macro panicked ... icon .../icons/icon.png is not RGBA`. The new backdrop is opaque,
+and librsvg drops the alpha channel when nothing in a render is transparent; `generate_context!`
+rejects a window icon that is not RGBA. Fifteen of the sixteen rasters were affected — only the
+tray image, which has real transparency, kept its alpha.
+
+Nothing in the repository could have seen it. The icon tests read dimensions and container
+structure, and no test or hosted job builds the Tauri bundle. The generator now re-encodes, and
+the colour type of every committed raster is asserted rather than trusted.
+
+## CI at the head
+
+`917d690ecb`, read at the exact SHA. Green: all four test shards, `gates`, `desktop shell`,
+`macos 2/2`, `macos widget + bundle`, `docs site build`, `docker smoke`, `storage policy`,
+`api usage`, all three `npm-global` legs, all three keyring legs, the three service legs.
+Skipped, and named rather than counted: `macos control`, `structure gate`, the Windows shard
+matrix placeholder.
+
+The first attempt had one failure, and it did not belong to this unit: `macos 1/2`, on
+`tests/server/memory-watchdog.test.ts` --
+*serializes only an allowlisted Bun runtime provenance, omitting it otherwise (#848)* -- at 47.4s
+against its own 20s timeout, with 13436 pass, 12 skip, 1 fail on that leg. That test makes eight
+full `/api/system/memory` route calls and its own comment records the route costing roughly
+600ms per read on shared runners, so it is timing fragile by construction. It passed at
+`64b0eca2b0`, which already contained #5355 and #5356, and `917d690ecb` adds only favicon bytes
+and a favicon generator. It also failed at `07e2ac9b41`, before any of this landed, and a focused
+local run finishes in 377ms.
+
+Re-running that job at the same SHA turned it green, and the aggregate `ci` check with it, so
+exact-head CI for `917d690ecb` is green. The flake is real and still there: the fix is to stop the
+test paying for eight route snapshots, not to widen the timeout again. That is separate scope.
+
+## Left deliberately
+
+- `docs-site/src/assets/logo-light.png` and `logo-dark.png` stay as they are. They are the artwork
+  the vector was traced from, not derived assets.
+- `og.png` stays, and carries a pre-existing mismatch worth its own scope: the configuration
+  declares 1200x630 and the committed file is 1536x1024.
+
diff --git a/devlog/_fin/260921_cross_path_contract/000_plan.md b/devlog/_fin/260921_cross_path_contract/000_plan.md
new file mode 100644
index 00000000000..c9ab2d7f078
--- /dev/null
+++ b/devlog/_fin/260921_cross_path_contract/000_plan.md
@@ -0,0 +1,113 @@
+# Cross-path contract gaps before the next release
+
+Status: open. Target branch for every lane: `dev`.
+
+The batch that landed on 2026-09-20 fixed several defects one path at a time. The
+audit that followed found the same shape repeating: a policy is correct where it
+was written and absent one wrapper away, or a guard that protects a real hazard
+also refuses the supported case. This unit closes that class before the release
+rather than adding features.
+
+Each lane is one branch, ordered commits, and one pull request to `dev`. No
+stacked child pull requests, no native stacks. A lane owns its files; where two
+lanes touch the same subsystem the split is written below so the merge is a union
+and not a conflict.
+
+## L1 — one replay refusal on all three HTTP surfaces
+
+`src/lib/upstream-retry.ts` answers an ambiguous connection loss with
+`upstream_reset_replay_refused` and no `Retry-After`, which means "this may
+already have executed, do not send it again". `src/server/chat-native.ts` and
+`src/server/responses/passthrough-error.ts` recognise that. The translated Chat
+wrapper in `src/server/chat-completions.ts` does not: it preserves only the cyber
+policy code and `model_not_found`, assigns `upstreamCode` just when
+`classifyError` produced no code, and then adds a default `Retry-After: 2`. A
+refusal to replay leaves the proxy as an ordinary rate limit that clients retry.
+
+Carry the replay verdict as a property of the result the three wrappers share, so
+no wrapper re-derives it from a status code. Then decide the status deliberately:
+the widely used Python SDK retries 429 by default, so preserving the code while
+dropping `Retry-After` does not by itself stop a resend. The acceptance evidence
+is the number of physical upstream sends observed through a client with retries
+enabled, not a single `fetch`.
+
+## L2 — the Chat translation inbound loses developer position
+
+Outbound keeps a `developer` message where the conversation put it
+(`src/adapters/openai-chat/messages.ts`). Inbound does not:
+`src/chat/inbound.ts` routes both `system` and `developer` into
+`systemParts` and joins them into `body.instructions`, so
+`U1 → A1 → D2 → U2` becomes `instructions: D2` with `U1 → A1 → U2`. Position
+is gone before any adapter sees it, and no outbound fix can restore it.
+
+This is not a rare internal path. Combo, policy, synthetic effort rows and several
+preprocessing routes translate, so the same transcript behaves differently once a
+routing feature is on. The Claude inbound already models this correctly by keeping
+a mid-conversation instruction as a developer input item
+(`src/claude/inbound.ts`, `src/responses/parser.ts`). Reuse that representation
+for the mid-conversation case only; a leading system block keeps its current
+treatment.
+
+## L3 — an explicit developer-role setting is ignored natively
+
+`foldDeveloperRoleToSystem` decides the role on the translated path. The native
+Chat passthrough (`src/adapters/openai-chat/passthrough.ts`) forwards the
+caller's `messages` untouched and never reads it, so an operator who recorded
+"this destination rejects `developer`" still sends `developer` there. Honour the
+explicit setting on both paths and leave the unset default alone: the existing
+native test that preserves caller messages stays green.
+
+## L4 — the paginated-history transition, past "enable succeeded"
+
+The provider-table transition on a paginated `openai` home now completes. The
+remaining risk is the state after it. Acceptance is destination preservation, not
+a successful sync: existing conversations must not resume against the default
+OpenAI endpoint, new conversations must use the injected provider and catalog,
+restore must return operator-owned settings and remove only what this project
+owns, a user-owned root override must not be taken over, and an admission-token
+home must still be refused rather than reported as supported.
+
+## L5 — tool constraints survive response repair
+
+`createGrokResponsesSparseTerminalBlockRewrite` rebuilds a terminal output from
+collected `output_item.done` events and receives a budget but not this request's
+tool selection. The undeclared-tool guard answers a different question — whether a
+name was declared — so a request with `tool_choice: none` or a narrowed allow-list
+can still receive a call the repair put back. Pass the request scope into the
+repair and enforce it there. Keep the failure narrow: one forbidden call must not
+discard the ordinary text that accompanied it. The empty-catalog case belongs to
+the same rule — compatibility is judged on the final request and the final
+response, after every removal, rename and translation.
+
+## L6 — a client integration that writes a store nobody reads
+
+A newer client release reads its provider list from a different file than the one
+this exporter writes, and the legacy import does not run again once the new file
+exists, so an apply that reports success produces no models. Support the store the
+running client actually reads, including catalog refresh and disable, or report
+the write as ineffective. Deleting the new file to re-trigger a migration is not a
+supported remedy. The verification unit is "the client requests the intended
+provider", not "the file was written".
+
+## L7 — one developer-role policy in both documents and the code
+
+`structure/providers/chat-compat.md` states the role is forwarded as itself on
+every destination; `docs-site` states an unset setting sends `system`; the two
+code paths differ again. Whoever fixes this area next picks one of them and
+reintroduces the regression. Make the three agree after L2 and L3 settle, and
+derive the statement from the code where a test can hold it.
+
+## L8 — one resend budget per logical request
+
+The ambiguous-resend gate landed with one operator grant per request. The
+composition still needs evidence: first send, reset, replacement, disconnect after
+`response.created`, then the combo candidate, credential refresh and 429 legs.
+Observe two separate numbers — physical sends, and sends of a turn that may already
+have executed. The neighbouring retry issues are not closed by this lane and stay
+open with their remaining scope recorded.
+
+## Out of scope
+
+A lenient finish for a text-only stream with no terminal event is existing
+compatibility behaviour with its own regression coverage. Turning every EOF into an
+error would be a policy change, not a fix, and is not part of this unit.
diff --git a/devlog/_fin/260921_cross_path_contract/010_lane_boundaries.md b/devlog/_fin/260921_cross_path_contract/010_lane_boundaries.md
new file mode 100644
index 00000000000..ae2d37c9f3d
--- /dev/null
+++ b/devlog/_fin/260921_cross_path_contract/010_lane_boundaries.md
@@ -0,0 +1,70 @@
+# Lane ownership, ordering and acceptance shape
+
+The first audit round of `000_plan.md` returned blocking findings: the lanes were
+described by symptom without an owned-file set, two lanes overlapped on the send
+path, one lane depended on two others without saying so, and two lanes named an
+acceptance unit that no test can observe. This document answers those and is the
+binding half of the unit.
+
+## Owned files
+
+A lane changes files in its own row. A file in another row is read-only for it.
+Anything outside every row is open, but a second lane touching it has to say so in
+its pull request.
+
+| Lane | Owns |
+|---|---|
+| L1 | `src/server/chat-completions.ts` error path, `src/server/chat-native.ts` error path, `src/server/responses/passthrough-error.ts`, the replay-verdict carrier it extracts, and tests for those |
+| L2 | `src/chat/inbound.ts`, `src/responses/parser.ts` where the Chat path needs it, and its own tests |
+| L3 | `src/adapters/openai-chat/passthrough.ts`, `src/adapters/openai-chat/messages.ts` role selection, and its own tests |
+| L4 | `src/codex/history-provider.ts`, `src/codex/inject.ts`, `tests/codex-integration/*` |
+| L5 | `src/server/grok-responses-snapshot-repair.ts`, `src/server/responses-undeclared-tool-guard.ts`, `src/server/responses/passthrough-dispatch.ts` call sites, and its own tests |
+| L6 | `src/clients/config-export/`, `src/integrations/registry.ts` entry for that client, and its own tests |
+| L7 | `structure/providers/chat-compat.md`, `docs-site` provider reference, and the generated binding check |
+| L8 | `src/lib/request-execution-budget.ts`, `src/lib/request-resend-gate.ts`, and send-count tests |
+
+L1 and L8 both live near the send path and are split by question. L1 owns what the
+client is told when a replay is refused — code, status, retry header, and the
+carrier that stops each wrapper re-deriving it. L8 owns how many sends one logical
+request may make and which leg may spend the shared reserve. L8 does not change an
+error body; L1 does not change an allowance.
+
+## Ordering
+
+L7 lands last. It writes down the single developer-role policy, and that policy is
+not settled until L2 fixes where the message sits and L3 fixes which role it
+carries. Until both are on `dev`, L7 keeps its branch rebased and its pull request
+open. Every other lane is independent and merges in whatever order its evidence
+arrives.
+
+## Acceptance that a test can hold
+
+Static reading is how a lane reviews itself; hosted CI on the exact head is what
+decides. A lane whose acceptance sentence names something no job can observe has
+to restate it:
+
+- L1 and L8 count sends against a recorded fetch, so the number is an assertion and
+  not an inference. L1 additionally asserts the response the client receives.
+- L4 drives a temporary home with fixtures: enable, create, resume, restore. It
+  asserts the destination recorded for an existing conversation and for a new one,
+  and it asserts the refusal that an admission-token home still receives. The
+  refusal path already has coverage; the transition and the post-transition
+  destinations are the new part.
+- L6 cannot prove what a third-party client does at runtime. Its assertion is that
+  the file the current client release reads carries the intended provider after
+  enable and refresh, and carries nothing after disable — with the client's own
+  published schema quoted in the pull request as the reason that file is the one
+  that matters. If the lane cannot establish the schema, it reports the write as
+  ineffective instead, which is the honest half of the original instruction.
+- L5 asserts on the block rewrite directly: `tool_choice: none`, a narrowed
+  allow-list, an empty catalog after normalisation, and a forbidden call arriving
+  beside ordinary text, which must survive.
+- L7 asserts that the documented default is derived from the code, so a default
+  change fails a check rather than only a review.
+
+## Baseline
+
+The lanes are cut from `dev` after the September 20 batch, so the paginated
+transition and the per-request resend gate are already present. A lane that finds
+its premise already satisfied says so in its pull request and narrows to the part
+that is not, rather than reimplementing what landed.
diff --git a/devlog/_fin/260921_cross_path_contract/090_outcome.md b/devlog/_fin/260921_cross_path_contract/090_outcome.md
new file mode 100644
index 00000000000..250d3754a85
--- /dev/null
+++ b/devlog/_fin/260921_cross_path_contract/090_outcome.md
@@ -0,0 +1,43 @@
+# Outcome
+
+All eight lanes are on `dev`. The unit closes here; what each lane actually
+changed is below, with the parts that were narrowed or left open named rather
+than implied.
+
+| Lane | Landed as | What it changed |
+|---|---|---|
+| L1 | `556b670251` | The ambiguous-resend refusal now carries the same code and the same retry policy on the translated Chat wrapper, the native Chat route and Responses, from one shared verdict instead of three re-derivations from a status code |
+| L2 | `0ab648b4e3` | A mid-conversation instruction keeps its slot through the Chat translation inbound instead of being folded into `instructions`; a leading system block is unchanged |
+| L3 | `6e0e912ebd` | A recorded `foldDeveloperRoleToSystem` decides the role on the native Chat route as well; the unset default and the caller-message preservation test are untouched |
+| L4 | `a6e8df4ec1` | The paginated-history transition is judged by conversation destination — enable, new conversation, resume, restore — rather than by a successful sync, and an admission-token home is still refused |
+| L5 | `b20acc79d2` | The request's tool selection is enforced after a sparse-terminal repair, so a forbidden call cannot re-enter the terminal output, and ordinary text beside it survives |
+| L6 | `5d3f5db84a` | The integration writes the provider store the client actually reads, with enable, refresh and disable symmetric, and reports an ineffective write instead of success when the store's schema is not one it knows |
+| L7 | `34332bb785` | One developer-role policy across the contract document, the configuration reference and its translations, derived from the adapter so a changed default fails a check |
+| L8 | `3a0718c81c` | One resend allowance per logical request across the composed recovery legs, with the physical send count and the possibly-executed send count observed separately |
+
+## What this unit did not close
+
+`#5348` is closed because its acceptance is on `dev`. The neighbouring retry
+issues about a WebSocket failure stage and single-key 429 handling are not
+resolved by L8 and stay open with their remaining scope recorded on the issues
+themselves.
+
+## What the audit round changed
+
+The first reviewer pass returned blocking findings and two mistaken ones. The
+mistaken pair read a stale checkout and reported L4's refusal and L8's gate as
+still absent; both had landed the day before, so those lanes narrowed to the
+part that was missing instead of reimplementing what was there. The real
+findings — no owned-file set, L1 and L8 overlapping on the send path, L7
+depending on L2 and L3 without an order, and two acceptance sentences no job
+could observe — are answered in `010_lane_boundaries.md` and were followed.
+
+## Friction worth remembering
+
+Two lanes conflicted on `scripts/test-layout/layout.json` and
+`tests/fixtures/test-layout-expected.json` because each appended its own
+registration line. The resolution is always the union; the file is a registry,
+not a narrative. One lane's own tests failed for the two familiar reasons: a
+test asserting a field name the type does not carry, and a fixture that set an
+unbound fingerprint beside `canApply`, which the parser refuses by contract.
+Both were fixed by deriving from the source rather than restating it.
diff --git a/devlog/_fin/260921_cross_path_contract/100_verification.md b/devlog/_fin/260921_cross_path_contract/100_verification.md
new file mode 100644
index 00000000000..535cefe5026
--- /dev/null
+++ b/devlog/_fin/260921_cross_path_contract/100_verification.md
@@ -0,0 +1,48 @@
+# Verification on the landed tip
+
+The eight lanes were re-read on `dev` after they landed, from source rather
+than from commit messages, to check that each acceptance is actually present.
+Six hold as written. Three carry a boundary that the plan did not state, and
+they are written down here because each of them is the kind of thing a later
+reader would otherwise discover as a surprise.
+
+**The replay refusal is identical on all three surfaces.** The translated Chat
+wrapper, the native Chat route and the Responses error path each preserve
+`upstream_reset_replay_refused`, drop `Retry-After`, and send
+`x-should-retry: false`. That last header is what makes the intent legible to a
+client whose default is to retry a 429.
+
+**The Chat inbound keeps a mid-conversation instruction in place, with one
+ordering rule.** Leading system text still becomes `instructions`. A developer
+message that arrives inside an open tool-call batch is held until the batch
+closes rather than being spliced between a call and its result, because a
+transcript that interleaves them is not one any destination accepts. Outside a
+batch the message stays exactly where it arrived.
+
+**The native Chat route honours an explicit setting only.** `true` rewrites the
+developer role to system; `false` and unset return the caller's messages
+untouched, which keeps the passthrough contract that route exists for.
+
+**The repair enforces the request's tool selection on what it reconstructs.**
+The rebuilt terminal output excludes a forbidden call and keeps the ordinary
+text that arrived beside it. Raw `output_item.done` blocks are not rewritten by
+the repair — policing the raw stream belongs to the undeclared-tool guard, and
+splitting it that way keeps one owner per question.
+
+**The client store is shared by enable, refresh and disable.** An unknown schema
+is reported rather than merged into. When this project's own block is still in
+the legacy file, refresh refuses and disable cleans that file first: the
+alternative is a block left in one file while another is written, which is the
+state that made the original report hard to diagnose.
+
+**The resend grant is one shared ledger entry.** Derived and combo budgets
+inherit it rather than opening their own, so composing recovery legs cannot
+multiply the allowance. The ceiling itself stays operator-configurable; what is
+fixed is that there is one of it per logical request.
+
+## Issue dispositions
+
+`#5348` is closed: its acceptance is on `dev`. `#4191` and `#5180` stay open
+with their remaining scope recorded on the issues — a dead mid-turn transport
+still has no fallback, and a provider 429 on a single key still has no cooldown
+policy. Neither is what a per-request resend budget decides.
diff --git a/devlog/_fin/260921_remaining_seams/000_plan.md b/devlog/_fin/260921_remaining_seams/000_plan.md
new file mode 100644
index 00000000000..84aa1d2a45e
--- /dev/null
+++ b/devlog/_fin/260921_remaining_seams/000_plan.md
@@ -0,0 +1,104 @@
+# The seams the first batch left open
+
+Status: open. Target branch for every lane: `dev`.
+
+The cross-path unit fixed each contract where it was written. Re-reading the
+integrated tree found four places where those fixed policies stop one layer
+short: an endpoint the refusal never reached, a name that changes between the
+check and the thing checked, a match that accepts more than it was given, and a
+pair of builders that read different halves of the same provider setting.
+
+Each lane is one branch, ordered commits, and one pull request to `dev`.
+
+## Owned files
+
+| Lane | Owns |
+|---|---|
+| N1 | `src/server/claude-messages.ts` error path and its tests |
+| N2 | `src/server/responses-request-tool-scope.ts`, the scope call site in `src/server/responses/passthrough-delivery.ts`, `src/responses/muse-tool-name-alias.ts` where identity is carried, and the composition test |
+| N3 | `src/adapters/openai-chat/passthrough.ts`, the shared wire policy it and `src/adapters/openai-chat.ts` both call, and its tests |
+| N4 | `src/integrations/merge.ts` selector parsing and its tests |
+
+N2 owns the scope module outright; N1 and N3 do not touch it.
+
+## N1 — the refusal stops at the Claude Messages wrapper
+
+`src/server/chat-completions.ts`, `src/server/chat-native.ts` and
+`src/server/responses/passthrough-error.ts` now agree: an ambiguous connection
+loss answers with `upstream_reset_replay_refused`, no `Retry-After`, and
+`x-should-retry: false`. `src/server/claude-messages.ts` rebuilds the error
+envelope itself. It keeps only the message string, runs the generic
+`resolveClientRetryAfter`, and emits an Anthropic error with `Content-Type` and
+`Retry-After` — so the refusal reaches the caller as an ordinary retryable
+rate limit. Anthropic's own client reads `x-should-retry` before the status
+code, so the header is the part that actually stops the resend.
+
+Read the shared verdict here rather than re-deriving it from the message text,
+and carry the code, the header and the suppressed `Retry-After` through. Two
+behaviours must survive: the transient-5xx to 529 mapping the Claude client
+depends on for backoff, and an ordinary provider 429, which keeps the retry
+policy it has today. The acceptance is the header and code observed at
+`/v1/messages`, not the internal Responses result.
+
+## N2 — identity has to survive the rename
+
+A long client tool name is sent upstream under a short alias, and
+`tool_choice` is rewritten to that alias with it. On the way back the payload
+rewrites restore the client name first, and only then does the snapshot repair
+check the call against the scope built from the outbound body, which still
+spells the selector as the alias. The restored name is not the alias, so an
+allowed call is removed from the reconstructed terminal output and the turn ends
+incomplete.
+
+The same module accepts too much in the other direction. A call is matched by
+any of its spellings — bare name, `namespace__name`, `namespace.name` — against
+a set holding the selector's spellings, so `alpha.lookup` and `beta.lookup`
+both offer bare `lookup` and match each other. The selection set is a set of
+strings, so a `custom` and a `function` tool of the same name are not separated
+either; the fix is to distinguish a verified conversion from a coincidence of
+names, not to refuse every kind mismatch.
+
+Carry the correspondence between the original identity, the wire alias and the
+restored identity from the request, and have the scope read that correspondence.
+`src/responses/namespace-tool-compat.ts` already reasons about selector kinds
+and dotted-alias ambiguity; reuse it rather than growing a second, looser name
+set. The regression test has to run the real order — a tool name past the length
+limit, a named or allowed-tools selector, alias on the way out, restore on the
+way back, sparse terminal reconstruction — and end with the original name and
+call id intact. Keep the negative case: a tool the request did not select is
+still refused after restoration.
+
+## N3 — two builders, one provider setting
+
+The translated builder turns `reasoningWireFormat: "gateway-object"` with an
+effort of `none` into the gateway's object form, and omits the effort entirely
+for a tool-bearing request when the model is listed in
+`omitReasoningEffortWithToolsModels`. The native Chat passthrough reads neither,
+so the same provider and model behave differently depending on whether a routing
+feature sent the request through translation.
+
+Apply the explicit settings through one small policy both builders call, after
+the provider is resolved. Do not route native requests through translation to
+get it: the native path exists to preserve Chat-only fields such as `n`, audio
+and logprobs, and losing those is a worse regression than the one being fixed.
+An unset setting keeps today's native behaviour. The test compares the final
+request body captured on both paths for the same input, not the status code.
+
+## N4 — a selector path must not change meaning
+
+The integration merge grammar gained a conjunction form, `[field=value,field=value]`,
+because one field is not always an identity. The single-criterion form allows a
+comma inside the value, so a path already written into an ownership record — for
+example one whose value itself contains `,` and `=` — can parse as a conjunction
+under the new rule and select a different element.
+
+No record in that shape has been found, so this is a migration hazard rather
+than a reported loss. Close it deliberately: version the grammar, structure the
+selector, or define an escape, and cover it with a test that reads a record
+written under the older rule and asserts it still names the same element.
+
+## Out of scope
+
+The paginated-history work and the client provider store landed and are not
+reopened here. The two retry issues left open after the first batch keep their
+recorded scope; neither is a lane in this unit.
diff --git a/devlog/_fin/260921_remaining_seams/090_outcome.md b/devlog/_fin/260921_remaining_seams/090_outcome.md
new file mode 100644
index 00000000000..6ecdae83453
--- /dev/null
+++ b/devlog/_fin/260921_remaining_seams/090_outcome.md
@@ -0,0 +1,38 @@
+# Outcome
+
+All four lanes are on `dev`, and the seams they were opened for are closed.
+
+| Lane | Landed as | What it changed |
+|---|---|---|
+| N1 | `2cc11b780a` | The routed Claude Messages error path now carries the replay-refusal code, `x-should-retry: false` and no `Retry-After`, so a refusal no longer reaches that endpoint as an ordinary retryable rate limit. The transient-5xx to 529 mapping the client relies on for backoff and the policy for a genuine provider 429 are unchanged |
+| N2 | `ebaf78a46c` | The scope reconstructs each exact outbound identity through the namespace and wire aliases before judging a call, so an allowed call restored from its alias survives sparse-terminal reconstruction. Authorization keys carry kind, namespace and name, so a shared bare name no longer grants another namespace or another kind |
+| N3 | `03ab5bfb11` | `applyExplicitChatReasoningWirePolicy` owns the gateway-object form and the tool-bearing effort omission, and both the translated and native builders call it. It is a no-op when neither setting is recorded, and the native path still copies its preserved Chat-only fields verbatim |
+| N4 | `bd4822bcea` | A conjunction selector now needs an explicit marker, so a legacy single-criterion value containing a comma keeps its old meaning. The whole recorded path is validated before traversal, and an unreadable selector stays attached to the file its record names as unsafe rather than moving the operation elsewhere |
+
+## Found while waiting
+
+A manual full-matrix run on one lane's branch exposed a Windows-only defect that
+pull-request CI never ran: the desktop release-asset test took a basename with
+`path.split("/")`, which is not a separator on Windows, so it compared whole
+`C:\…` paths against asset names and five shards failed. Fixed in
+`e2453085b9` by asking the platform for the last segment. The release matrix
+would have hit it.
+
+## Verification
+
+Each lane merged on its own exact head with every requested job green. The four
+landed seams were then re-read on the integrated tip and all five acceptance
+statements hold at source level.
+
+Two CI conditions shaped the pace and are worth recognising next time. Duplicate
+runs for one head appear regularly and one of them is cancelled by concurrency;
+a cancellation is not evidence in either direction, and the remedy is to re-run
+the failed jobs of the real matrix rather than to read the rollup. Hosted macOS
+capacity was saturated for much of this batch, with single jobs queued for over
+an hour, which is why the last two merges trailed the rest.
+
+## Not in this unit
+
+The two retry issues left open after the first batch keep their recorded scope:
+a mid-turn transport death still has no fallback, and a provider 429 on a single
+key still has no cooldown policy. Neither is decided by anything landed here.
diff --git a/devlog/_plan/260920_desktop_app_stabilization/000_local_build.md b/devlog/_plan/260920_desktop_app_stabilization/000_local_build.md
new file mode 100644
index 00000000000..db1792aa6f1
--- /dev/null
+++ b/devlog/_plan/260920_desktop_app_stabilization/000_local_build.md
@@ -0,0 +1,52 @@
+# Desktop app stabilization — local build and conflict handling
+
+Status: OPEN. Opened against `dev` after the desktop stack landed as #5318 and the Claude Desktop
+chain as #5319. This unit records what the first real local build found and what the app does when
+it meets something already running.
+
+## The release profile could not build the app at all
+
+`cargo build --release` stopped at `ctor`, a transitive dependency of `tauri-utils`:
+
+```
+error[E0463]: can't find crate for `ctor_proc_macro`
+   --> ctor-0.8.0/src/lib.rs:244:9
+```
+
+The same graph compiles in the dev profile. The difference is `[profile.release] strip = "symbols"`,
+which cargo applies to build scripts and proc macros as well as to the crate being built. A proc
+macro is a host dylib that rustc loads by symbol, so stripping it leaves a file rustc cannot read,
+and the error names the macro rather than the profile that removed its symbols.
+
+`[profile.release.build-override] strip = false` restores it. The fix is one line plus the reason,
+because the next person to read `can't find crate` will otherwise go looking at the dependency.
+
+This did not surface earlier because nothing had built the desktop app in release outside CI, and
+CI's toolchain tolerated the stripped dylib. It is reproducible here on rustc 1.95.0.
+
+## Two installations at once
+
+The widget snapshot has two writers that target the same path:
+
+- `app/Sources/MenuBarCore/WidgetSnapshot.swift` builds it from
+  `~/Library/Containers/com.opencodex.desktop.widget/Data/Library/Application Support/OpenCodex/snapshot.json`
+- `desktop/src-tauri/src/widget.rs:246` writes the same file from Rust
+
+Each deduplicates with its own in-process `lastWritten`, so two live writers do not settle: each
+sees the other's file as changed, rewrites it, and calls `reloadTimelines`. The current build no
+longer ships a standalone menu bar executable — `app/Package.swift` declares only the widget appex
+and its test harness — so this is reachable only for a user who still has an earlier standalone
+build installed. `tauri_plugin_single_instance` guards a second copy of the same bundle and cannot
+see a different one.
+
+## Proxy ownership
+
+`spawned_by_us` in `desktop/src-tauri/src/lib.rs` records whether the app started the proxy, and
+`tray.rs` enables **Stop proxy** from it. It is consumed with `swap(false)`, so the behaviour after
+a stop-and-restart cycle needs checking rather than assuming.
+
+## Execution note
+
+This unit builds and installs locally at the maintainer's explicit request, which is a deliberate
+exception to the no-local-build rule the surrounding batch worked under. Test suites are still not
+run here.
diff --git a/devlog/_plan/260920_desktop_app_stabilization/010_roadmap.md b/devlog/_plan/260920_desktop_app_stabilization/010_roadmap.md
new file mode 100644
index 00000000000..af51c49d63e
--- /dev/null
+++ b/devlog/_plan/260920_desktop_app_stabilization/010_roadmap.md
@@ -0,0 +1,69 @@
+# Roadmap — six items, four work phases
+
+Status: LOCKED at wp1. Each later phase consumes one decade doc below and revalidates it at its
+own P. The evidence in [000_local_build.md](000_local_build.md) is the ground truth; this file
+turns it into an order of work.
+
+## What the local build and run actually showed
+
+Nothing about the usage feature was missing. `gui/dist` was five days old, so the bundle the
+service served predated #5196 and could not contain the companion panel. `AGENTS.md` already says
+the dashboard is served from `gui/dist` and lists `bun run build:gui`, so rebuilding after a
+fast-forward was the existing procedure and skipping it was the mistake. After the rebuild the page
+renders 74,974 requests, 18.66B tokens, 99% coverage, and a **menu bar and widget** section reading
+"desktop app connected · just now".
+
+That reframes the work: five of the six items are real defects, and the sixth is the guard that
+stops this particular mistake from being silent.
+
+## Order and why
+
+| Phase | Items | Why here |
+| --- | --- | --- |
+| wp2 | release profile, stale dist, updater-key exit | Nothing else can be built or verified until the release profile compiles; the dist guard belongs with it because both are "the build lied about its state". |
+| wp3 | Claude Desktop first-party reachability | Independent of the build, and already verified by hand, so it lands on its own evidence. |
+| wp4 | SVG app icons, widget gallery verdict | Both need a signed-or-explained bundle, so they come after the build is trustworthy. |
+
+## 020 — release profile, stale dist, updater key
+
+`[profile.release] strip = "symbols"` is applied by cargo to build scripts and proc macros as well
+as to the crate being built. A proc macro is a host dylib rustc loads by symbol, so stripping it
+produces `can't find crate for ctor_proc_macro` — an error that names the macro and never mentions
+the profile. `[profile.release.build-override] strip = false` is the fix, already committed with
+its reason.
+
+The stale-dist guard reports rather than repairs. The dashboard is a served artifact, so the honest
+signal is "the bundle you are looking at is older than the source that produced it", surfaced where
+someone will read it. Rebuilding automatically at startup would make a serving process do a build,
+which is the wrong trade for a proxy.
+
+The updater-key exit is smaller: a local build that produced both bundles should not end on a
+failure line about a signing key it was never given.
+
+## 030 — Claude Desktop first-party reachability
+
+`resolveClaudeDesktopMode` returns `gateway` when a gateway apply marker exists, and an explicit
+`desktopMode` wins over everything. Both rules are right on their own: neither should flip a
+working install silently. Together they mean the help text calls first-party "(default)" while an
+existing user can never arrive there without discovering `--first-party` unaided.
+
+The fix is not to change the resolution. It is to make the choice visible at the moment an apply
+happens, so a gateway apply says what it chose, that first-party exists, and how to switch.
+
+## 040 — SVG app icons and the widget verdict
+
+Icons today are a raster set with no vector source, so every size is an independent artifact that
+can drift. One SVG source with a generation step makes the sizes derived rather than restated —
+the same principle the test-layout registries follow.
+
+The widget question is answered with evidence, not hope. The bundle carries
+`PlugIns/OpenCodexWidget.appex` and the app is ad-hoc signed
+(`Identifier=opencodex_desktop-b89067d97e1c189c`, `flags=0x20002(adhoc,linker-signed)`), so the
+phase records whether the widget appears in the gallery under that signing and, if it does not,
+what specifically rejects it.
+
+## Constraints carried through every phase
+
+Stacked PRs, all pushes `--no-verify`, CI tracked after the fact rather than waited on. No local
+test suite. Builds and real launches are the verification, because this unit exists precisely
+because a build that was never run locally was assumed to work.
diff --git a/devlog/_plan/260920_desktop_app_stabilization/011_acceptance.md b/devlog/_plan/260920_desktop_app_stabilization/011_acceptance.md
new file mode 100644
index 00000000000..e25669f18ff
--- /dev/null
+++ b/devlog/_plan/260920_desktop_app_stabilization/011_acceptance.md
@@ -0,0 +1,49 @@
+# Acceptance evidence per phase
+
+The roadmap says what each phase does. This says what closes it, in terms of evidence that a
+passing command or a rendered page does not by itself provide.
+
+## wp2 — release profile, stale dist, updater key
+
+**Release profile.** `cargo build --release` completes for the desktop crate. The regression is not
+a test that runs cargo; it is an assertion that the release profile carries a build-override which
+does not strip, because the failure mode is a profile setting and the symptom appears in an
+unrelated crate. A test that only built something would pass on a machine whose rustc tolerates a
+stripped proc-macro dylib, which is exactly how this reached `dev`.
+
+**Stale dist.** The check compares the newest source timestamp under `gui/src` against the built
+bundle and reports when the bundle is older. It closes when a deliberately stale bundle produces
+the report and a fresh one does not. Reporting is the contract: the proxy must not start a build.
+
+**Updater key.** A local bundle build that produced its artifacts ends by naming them, and the
+missing updater key is stated as a skipped signing step rather than a failure. It closes when the
+command's exit status reflects whether the bundles exist.
+
+## wp3 — Claude Desktop first-party reachability
+
+Closes when an apply that resolves to gateway says so, names first-party as the alternative, and
+gives the exact command that switches. The resolution rules stay as they are: neither an explicit
+`desktopMode` nor an existing apply marker may be overridden silently, because a working install
+must not flip underneath its user.
+
+The evidence is the apply output on a machine that already carries a gateway marker — this one.
+A unit test asserting the string is not sufficient on its own, because the defect was that the
+help text and the resolved behaviour disagreed, and only running the real path shows which wins.
+
+## wp4 — SVG icons and the widget verdict
+
+**Icons.** One SVG source exists and every raster size is generated from it by a committed script.
+It closes when regenerating produces byte-identical output for unchanged input, so the sizes are
+derived rather than restated.
+
+**Widget.** The verdict is recorded either way. If the widget appears in the gallery under ad-hoc
+signing, that is the finding. If it does not, the phase records what rejects it — the specific
+system log line or the signing requirement — rather than reporting an absence. An unverified
+"should work" closes nothing.
+
+## What none of these accept
+
+A green pull request is not evidence for any item here, because every one of them was invisible to
+CI. The release profile failed only on a toolchain CI does not use, the stale bundle is a runtime
+artifact CI rebuilds, the mode disagreement needs an existing install, and the widget needs a real
+login session. Each phase therefore carries a local run alongside its hosted check.
diff --git a/devlog/_plan/260920_desktop_app_stabilization/020_build_state_guards.md b/devlog/_plan/260920_desktop_app_stabilization/020_build_state_guards.md
new file mode 100644
index 00000000000..fe67b3411a8
--- /dev/null
+++ b/devlog/_plan/260920_desktop_app_stabilization/020_build_state_guards.md
@@ -0,0 +1,59 @@
+# wp2 — the build telling the truth about its own state
+
+Two defects and one rough edge, all of the same shape: the build produced a state nobody could see
+from its output.
+
+## 1. The release profile could not compile the app (landed)
+
+`cargo build --release` stopped at `ctor` with `can't find crate for ctor_proc_macro`. The dev
+profile compiled the identical graph. `[profile.release] strip = "symbols"` is applied by cargo to
+build scripts and proc macros as well as to the crate under build, and a proc macro is a host dylib
+rustc loads by symbol, so stripping it leaves a file rustc cannot read. The error names the macro
+and never mentions the profile that removed its symbols.
+
+`[profile.release.build-override] strip = false` in `desktop/src-tauri/Cargo.toml`, with the reason
+in a comment because the next reader of that error will otherwise go looking at the dependency.
+Verified by `cargo build --release -p ctor` failing before and passing after, and by the full
+`tauri build` reaching both bundles afterwards.
+
+## 2. A stale dashboard bundle was invisible (landed)
+
+`gui/dist` was five days old, so the served page predated #5196 and could not contain the usage
+companion panel. Nothing failed — the proxy answered and the page loaded, and the feature simply was
+not in the bundle, which reads as the feature being broken.
+
+`src/server/gui-freshness.ts` compares the newest mtime under `gui/src` with the served bundle and
+`ocx status` prints the rebuild command beside the dashboard URL. It reports and never rebuilds: a
+proxy compiling a frontend at startup trades silent staleness for a slow, surprising start.
+
+Unknown is not stale, because a packaged install ships no `gui/src` and a missing bundle is a
+separate condition. `node_modules` is skipped so a dependency install cannot make sources look
+newer than they are. Four regressions in `tests/server/server-gui-bundle-freshness.test.ts` hold those
+cases, and the live check was confirmed by touching a source file and watching the warning appear
+and then disappear after a rebuild.
+
+## 3. A local build ends on a failure after succeeding (this phase)
+
+`createUpdaterArtifacts` is true and `plugins.updater.pubkey` is set in `tauri.conf.json`, so Tauri
+always builds the updater archive and then refuses to finish without `TAURI_SIGNING_PRIVATE_KEY`:
+
+```
+Finished 2 bundles at: .../OpenCodex.app, .../OpenCodex_2.61.0_aarch64.dmg
+A public key has been found, but no private key. Make sure to set TAURI_SIGNING_PRIVATE_KEY
+Error failed to build app
+```
+
+Both bundles exist at that point. The command still exits non-zero, so a developer building locally
+sees a failure for a signing step they were never meant to perform, and a script wrapping the build
+cannot distinguish this from a real failure.
+
+The release path must keep failing here: an unsigned updater artifact shipped to users is worse
+than a failed release. So the fix is not to relax the check but to give the local build a path that
+does not ask for the artifact at all — an explicit script that builds the app and dmg without
+updater artifacts, documented beside the existing release instructions.
+
+### Acceptance
+
+A local build command produces `OpenCodex.app` and the dmg and exits zero without a signing key.
+The release instructions still describe the signed path, and nothing weakens the requirement that a
+published updater artifact is signed.
diff --git a/devlog/_plan/260920_desktop_app_stabilization/030_icons_and_widget.md b/devlog/_plan/260920_desktop_app_stabilization/030_icons_and_widget.md
new file mode 100644
index 00000000000..6ea275bebe6
--- /dev/null
+++ b/devlog/_plan/260920_desktop_app_stabilization/030_icons_and_widget.md
@@ -0,0 +1,114 @@
+# wp4 — one vector source for the icons, and a verdict on the widget
+
+## Why the icon set needed a source
+
+`desktop/src-tauri/icons/` carried eighteen raster files and no vector. Every size was an
+independent artifact: nothing tied `Square107x107Logo.png` to `icon.png`, nothing could tell
+whether one of them had been hand-edited, and adding a platform size meant drawing it again. The
+`.icns` and `.ico` containers hid the problem further, because a wrong member inside them is not
+visible in a diff at all.
+
+The fix is a single `icon.svg` plus `desktop/scripts/generate-icons.ts`, exposed as
+`bun run icons` and `bun run icons:check`. Fifteen PNGs render through `rsvg-convert`, the
+`.icns` is assembled by `iconutil` from its ten members, and the `.ico` is written directly with
+six PNG-embedded entries (16, 32, 48, 64, 128, 256). `--check` regenerates into a temporary
+directory and compares byte for byte, so a hand-edited PNG fails instead of silently disagreeing
+with the source.
+
+## The geometry was measured, not redrawn
+
+A redrawn mark would have been a different icon wearing the same name. The shape in `icon.png`
+was measured instead: it spans 58..453 on both axes, the stroke is 48 wide, and the outer corner
+turns at radius 135. A centred stroke therefore sits at `x=82 y=82 w=348 h=348` with
+`stroke-width=48`, and the corner radius was swept to find the closest match. `rx=127` reproduces
+the original to within **430 of 262144 pixels at 512×512 — 0.164%**, which is antialiasing along
+the curve rather than a changed silhouette.
+
+The mark stays pure black on transparency. Both macOS and Windows composite it over their own
+backgrounds, so a baked background would appear as a card on one of the two.
+
+## The widget question
+
+`OpenCodexWidget.appex` is bundled, and the acceptance note requires a verdict either way rather
+than an absence.
+
+**The extension registers, and that part is settled.** `pluginkit` lists it from the installed
+application with the parent bundle resolved and no disabled or ignored marker:
+
+```
+com.opencodex.desktop.widget(2.61.0)
+            SDK = com.apple.widgetkit-extension
+  Parent Bundle = /Applications/OpenCodex.app
+    Parent Name = OpenCodex
+       Platform = macOS
+```
+
+That record is structurally identical to a system widget queried the same way, so the earlier
+working hypothesis — that ad-hoc signing keeps the extension from being adopted at all — is wrong
+and is recorded here as wrong. Registration is not the obstacle.
+
+**And it does not appear in the gallery.** The gallery was opened on this machine and checked:
+OpenCodex is not among the offered widgets. No `OpenCodexWidget` process has ever run here
+either, so nothing has asked the extension for a timeline. Registration and adoption are two
+different things, and only the first of them holds.
+
+**What the signing state actually costs.** The host bundle carries the linker-signed placeholder:
+
+```
+host app   Identifier = opencodex_desktop-b89067d97e1c189c
+                flags = 0x20002(adhoc,linker-signed)
+           Info.plist = not bound
+      Sealed Resources = none
+appex      Identifier = com.opencodex.desktop.widget
+                flags = 0x2(adhoc)
+```
+
+The host's `CFBundleIdentifier` is `com.opencodex.desktop`, but its *signed* identity is the
+placeholder, its `Info.plist` is not bound into the signature, and it seals no resources. Locally
+that is tolerated because the machine built the bundle itself. A distributed copy has no sealed
+host for the system to validate the extension's containment against, and nothing binds the
+declared identifier to the signed one.
+
+**The verdict, then:** the extension is registered and the gallery does not offer it. The host
+bundle is the thing that fails a requirement — its signed identity is not the identity it
+declares, and it seals nothing — so nothing downstream can establish that this extension belongs
+to `com.opencodex.desktop`. Until the release pipeline signs the host with a Developer ID
+identity, the widget ships but cannot be added. That is the finding; it is not worked around here,
+and no part of the icon work depends on it.
+
+## What the icon check does and does not cover
+
+`bun run icons:check` compares all seventeen generated artifacts — fifteen PNGs, the `.ico` and
+the `.icns` — byte for byte against a fresh render. It needs `rsvg-convert` and `iconutil`, and
+when `iconutil` is missing it now says the `.icns` was not compared and fails, rather than
+reporting a pass over a file it never looked at.
+
+That check does not run in CI, and claiming otherwise would be the easy lie here. The renderer is
+not pinned, so two machines with different librsvg builds produce different bytes with nothing
+wrong; asserting byte identity on a hosted runner would be asserting the runner's renderer
+version. What CI runs instead is `tests/ci-workflows/build-desktop-icon-set.test.ts`, which needs
+no renderer at all and reads its expectations out of the generator: every declared size committed
+at exactly that size, the `.ico` directory carrying exactly the packed sizes with each payload a
+real PNG of its declared dimension, the `.icns` walking cleanly end to end with one image member
+per declared entry, and nothing hand-added beside the generated set. It was driven red on a
+resized raster and on a stray file before being trusted.
+
+So the split is: shape is enforced everywhere, byte identity is enforced wherever the toolchain
+exists.
+
+## Files
+
+- `desktop/src-tauri/icons/icon.svg` — new, the single source.
+- `desktop/scripts/generate-icons.ts` — new, renderer and `--check` verifier.
+- `desktop/package.json` — `icons` and `icons:check` scripts.
+- Seventeen regenerated raster artifacts under `desktop/src-tauri/icons/`.
+- `tests/ci-workflows/build-desktop-icon-set.test.ts` — new, the renderer-free structural guard,
+  registered in `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`.
+
+## Acceptance
+
+`bun run icons:check` passes on the committed tree over all seventeen artifacts,
+`build-desktop-icon-set.test.ts` passes and has been shown to fail on a wrong-sized raster and on
+a stray file, `bun run build:local` produces a bundle whose `Contents/Resources/icon.icns` is the
+generated one, and the widget verdict is an observation of the gallery rather than an inference
+from registration.
diff --git a/devlog/_plan/260920_desktop_app_stabilization/040_widget_never_offered.md b/devlog/_plan/260920_desktop_app_stabilization/040_widget_never_offered.md
new file mode 100644
index 00000000000..062fbfa4d27
--- /dev/null
+++ b/devlog/_plan/260920_desktop_app_stabilization/040_widget_never_offered.md
@@ -0,0 +1,215 @@
+# wp5 — the widget registered, and offered nothing
+
+## The symptom, and why it was not a signing problem
+
+The extension installs, `pluginkit` lists it beside the system widgets, and the gallery does not
+show it. The obvious reading was signing: a locally built host is ad-hoc signed, so of course the
+system will not adopt its extension. That reading was wrong, and following it would have produced
+a signing change that fixed nothing, because the released build is signed and notarized and the
+widget is missing there too.
+
+The actual defect is in the binary. `app/Package.swift` forced the executable's entry point:
+
+```swift
+.unsafeFlags(["-Xlinker", "-e", "-Xlinker", "_NSExtensionMain"]),
+```
+
+and `app/Sources/OpenCodexWidget/main.swift` held nothing but a comment explaining that the entry
+was handled by that flag. So `OpenCodexWidgetBundle` — which `Views.swift` defines correctly,
+with a display name, a description and three supported families — was never referenced by
+anything, and no code ever handed it to the extension host.
+
+Read off the shipped bundle:
+
+```
+LC_MAIN entryoff -> _NSExtensionMain
+nm: SnapshotProvider present, OpenCodexWidgetBundle absent
+Info.plist: NSExtensionPointIdentifier = com.apple.widgetkit-extension
+            NSExtensionPrincipalClass   = (absent)
+```
+
+That combination is exactly consistent with the symptom. `pluginkit` registers from the
+Info.plist, which is complete, so registration succeeds. `NSExtensionMain` then looks for an
+`NSExtensionPrincipalClass`, which a SwiftUI widget does not declare because Xcode's `@main` on
+the `WidgetBundle` is what connects it instead. Nothing errors. The gallery simply has no
+configuration to offer.
+
+## The fix, and the wrong turn on the way to it
+
+The first attempt was to delete the linker override and call the bundle from `main.swift`. That
+made the bundle's symbols appear in the binary and did not work either — it replaced a silent
+failure with a loud one. Every launch died:
+
+```
+EXC_BREAKPOINT (SIGTRAP)
+  ExtensionFoundation  closure #1 in ... _EXRunningExtension._shared
+  ExtensionFoundation  MainActor.assumeIsolated
+  ExtensionFoundation  _EXExtension.bootstrap(with:)
+  WidgetKit
+  OpenCodexWidget      main
+chronod: [com.opencodex.desktop::com.opencodex.desktop.widget] query failed - will try lazy
+         reload later
+```
+
+Seventeen crash reports accumulated in `~/Library/Logs/DiagnosticReports` while the gallery stayed
+empty, because `chronod` asks the extension for its descriptors and the extension never survives
+long enough to answer.
+
+**The extension needs both halves of what Xcode does, and each is useless alone.** `@main` on the
+`WidgetBundle` is what keeps it in the binary; `-e _NSExtensionMain` is what makes the process
+start as an extension rather than as a program. The original code had the second without the
+first, this branch briefly had the first without the second, and only both together produce a
+widget the system will talk to. With both in place the crash reports stop at zero and `chronod`
+processes the extension normally.
+
+`tests/clients/desktop-widget-entry.test.ts` asserts both, plus that no `main.swift` has come back
+to compete with `@main`, and that the bundle carries a widget with a display name rather than an
+empty body — the same failure by a third route.
+
+The deployment target moved to macOS 14 at the same time, which drops the per-declaration
+`@available(macOS 14, *)` guards and puts the binary's `minos` at 14.0, matching every working
+widget on the machine this was measured on.
+
+## The sandbox is not optional
+
+While narrowing this down, the extension was rebuilt without `com.apple.security.app-sandbox` to
+test whether the sandbox was implicated. It is required, and the system says so plainly:
+
+```
+pkd: Ignoring mis-configured plugin at [.../OpenCodexWidget.appex]: plug-ins must be sandboxed
+```
+
+An unsandboxed extension is not rejected at launch — it is never registered at all, so it vanishes
+from `pluginkit` entirely. That also settles the snapshot path: the host writes into
+`~/Library/Containers/com.opencodex.desktop.widget/Data/...` precisely because the extension reads
+its own container, and that arrangement has to stay.
+
+## What the public record says about this failure
+
+The `_EXRunningExtension` crash is not unique to this repository, and finding the precedent
+changed how much of the fix is guesswork. A forensic report on macOS 26.5 with Swift 6.3.2
+describes the same trap from the same cause — a widget extension assembled from a SwiftPM
+`.executableTarget` and wrapped into an `.appex` by hand — and records that neither Info.plist
+shape avoids it, because SwiftPM has no app-extension target and therefore never applies the
+entry-point setup Xcode's WidgetKit template provides. That project's resolution was to stop
+using SwiftPM for the extension and build a real Xcode app-extension target instead.
+
+Two other projects keep SwiftPM and supply the missing pieces by hand, which is the route taken
+here: the linker entry (`-Xlinker -e -Xlinker _NSExtensionMain`) and the compiler's
+extension-only mode (`-application-extension`, which is what Xcode spells
+`APPLICATION_EXTENSION_API_ONLY`). Both are now set, and the extension launches and answers
+`chronod` without a crash report.
+
+Three things the same record settles that were open questions here:
+
+- **Ad-hoc signing does not prevent gallery appearance.** Developer ID and notarization matter for
+  Gatekeeper, not for gallery mechanics. The containing app does have to be launched once after
+  installation, which is what makes the first-run behaviour in this branch load-bearing for more
+  than the menu bar.
+- **App Groups do not work under ad-hoc signing**, and the documented fallback is exactly what
+  this repository already does — the host writes into the extension's own container.
+- **`CFBundleVersion` must match between host and extension** or WidgetKit rejects timeline
+  reloads. Verified on the installed bundle: both read 2.61.0.
+
+If the gallery still refuses this extension after the entry point and the extension-only build,
+the remaining known cause is the Xcode app-extension target itself, and that is a larger change
+than this unit: it means adding an Xcode project for the widget and building it with
+`xcodebuild` rather than `swift build`.
+
+## The signing defect underneath it
+
+Fixing the entry point does not make a *released* widget adoptable on someone else's machine,
+because the release pipeline would not sign it.
+
+`.github/workflows/release.yml` ran `build-widget.sh` with no `env:` block. `MACOS_SIGN_IDENTITY`
+was set one step later, on the Tauri build, which never reads it. So the script took its
+`codesign --force --sign -` branch, and the bundler does not re-sign anything under `PlugIns/` —
+its nested-code walker handles `.framework`, `.xpc` and `.app`, not `.appex`.
+
+**This has not harmed a release yet, and the reason matters.** No release has ever published a
+macOS application: the last three carry no desktop assets at all, and the signing secrets did not
+exist until after the most recent one was cut. `MACOS_SIGN_IDENTITY` reads a secret that was not
+there, so the real-signing branch has never executed and the Developer ID path in the Tauri step
+has never executed either. The bug is a mine rather than a crater — the next release is the first
+one that would step on it. Saying otherwise would be inventing a history this repository does not
+have.
+
+**Signing one path is also not enough.** A bundler that did not place a file does not sign it, and
+picking binaries by file extension misses the ones that have none. The durable form of the check
+is to find Mach-O files by their magic bytes and require every one of them to carry the release
+identity, rather than naming the paths that are expected to exist.
+
+Three changes:
+
+- The certificate is imported into a temporary keychain in a step **before** the widget build, and
+  the keychain is deleted in an `always()` step so it cannot outlive a failed job.
+- The widget build receives `MACOS_SIGN_IDENTITY`, and `build-widget.sh` now signs with
+  `--options runtime` as well as `--timestamp`, both of which notarization requires.
+- A step after the widget build asserts the result rather than printing it: strict verification,
+  the configured team identifier, the runtime flag, and a secure timestamp. Without a configured
+  team it says so and skips, so a fork's build still works and still cannot pretend to be signed.
+
+This half cannot be proven here. It needs maintainer-held credentials, and the proof is a
+notarized artifact installed on a machine that did not build it, launched once, with the gallery
+then checked. That is recorded as the outstanding verification rather than claimed.
+
+## The menu bar had the same shape of problem
+
+Start at Login was purely opt-in. Nothing enabled it on first run, so an install left the user
+with a menu bar item only for as long as the app happened to be running — and a menu bar app that
+is not running has no menu bar item. After a reboot the app was simply absent.
+
+`first_run::apply_start_at_login_default` enables it once per installation, keyed on a marker in
+the app config directory, and runs before `tray::install` so the tray checkbox reads the state it
+leaves behind. The marker is written before the login item is touched and is never removed, so a
+user who turns the setting off keeps it off. Writing afterwards would let a failed enable retry
+every launch and eventually flip the setting back under someone who had deliberately disabled it.
+
+The marker distinguishes a fresh install from a user who opted out, but it cannot distinguish
+either from an install that predates the marker. The desktop shell and the widget both landed the
+same day this was written and no release tag contains them, so there is no such population; if
+that changes, this needs a migration rather than a marker.
+
+## What was verified here
+
+Rebuilt, installed to `/Applications`, and launched:
+
+```
+LC_MAIN entryoff 5656 -> _main                    (was _NSExtensionMain)
+nm: _$s15OpenCodexWidget0abC6BundleV4bodyQrvpQOMQ  present
+pluginkit: com.opencodex.desktop.widget re-registered, parent bundle resolved
+~/Library/Application Support/com.opencodex.desktop/start-at-login-claimed  written
+~/Library/LaunchAgents/OpenCodex.plist                                      created
+```
+
+So the entry point is connected and the login item is registered, both on a real install rather
+than in a test double.
+
+## Verdict: it appears
+
+The gallery was opened on this machine after the fix and OpenCodex is in it, between OKX and
+PASS, with all three declared families rendering real data rather than placeholders:
+
+```
+com.opencodex.desktop::com.opencodex.desktop.widget:OpenCodexWidget:systemSmall
+com.opencodex.desktop::com.opencodex.desktop.widget:OpenCodexWidget:systemMedium
+com.opencodex.desktop::com.opencodex.desktop.widget:OpenCodexWidget:systemLarge
+  "OpenCodex — Proxy status, today's usage, and quota at a glance."
+```
+
+Small shows the token count for the day, medium adds requests, cost and the account quota rows,
+large adds the 24-hour per-model timeline. The list icon is the mark generated from `icon.svg`.
+
+That settles the whole question the acceptance note left open, and it settles it the right way
+round: the extension was never rejected by signing or by the sandbox. It had no widget in it, and
+then it had one that could not start. Both are fixed, and the fix is a SwiftPM configuration
+rather than the Xcode app-extension target the public record recommends — so the cheaper route
+does work, provided all three of `@main`, the `_NSExtensionMain` entry and
+`-application-extension` are present.
+
+## Acceptance
+
+The entry-point half is closed by the gallery observation above. The signing half closes when a
+release build's extension reports the team identifier, the runtime flag and a timestamp, and a
+clean install on a machine that did not build it offers the widget. That second half needs a real
+release and is recorded as outstanding.
diff --git a/devlog/_plan/260920_desktop_app_stabilization/050_landing.md b/devlog/_plan/260920_desktop_app_stabilization/050_landing.md
new file mode 100644
index 00000000000..4e6135b9d70
--- /dev/null
+++ b/devlog/_plan/260920_desktop_app_stabilization/050_landing.md
@@ -0,0 +1,66 @@
+# wp5 — landing the stack
+
+## Shape
+
+Four pull requests, each based on the one below it, all ultimately targeting `dev`:
+
+| PR | branch | what it carries |
+|---|---|---|
+| #5327 | `codex/260920-app-stabilization` | release profile, stale-dist report, `build:local`, the lockfile and test-layout repairs |
+| #5328 | `codex/260920-claude-desktop-mode-visibility` | the first-party reachability message |
+| #5329 | `codex/260920-app-icons` | one SVG source, the generator, the renderer-free CI guard |
+| #5339 | `codex/260920-widget-entry` | the widget entry point, the login-item default, release signing |
+
+They merge bottom-up. After each one lands, the next is retargeted to `dev` and its exact head is
+read again, because a squash merge rewrites the parent and the child's base disappears.
+
+## Two repairs in here are not ours
+
+`dev` was already red when this stack was cut, in two independent places, and both were fixed
+here because every branch cut from `dev` inherits them.
+
+`tests/providers/stepfun-provider.test.ts` landed with no entry in either inventory and no regex
+seed that resolves its name, so the membership oracle failed on `dev` and on everything branched
+from it. Registering it under `providers` restores the gate for everyone.
+
+`macos widget + bundle` failed with *A public key has been found, but no private key*. The job is
+an unsigned build by design, so the key is correctly absent — but the committed config sets
+`bundle.createUpdaterArtifacts` and `plugins.updater.pubkey`, so `tauri build` writes the updater
+archive and then refuses to finish. That half is #5338's, which turns the artifact off for that one
+invocation; this stack does not duplicate it.
+
+Fixing the build revealed the rest of the job, which had never run. Its first assertion looked for
+`Contents/MacOS/OpenCodex` — `productName` — while the bundle carries `opencodex-desktop`, the
+crate name. That half landed separately as #5351, and better than the version written here: it
+reads `CFBundleExecutable` out of the bundle instead of restating the name, so the check follows
+the config rather than drifting from it. This stack's copy was dropped in favour of it.
+
+What remains here is the assertion with no equivalent: that the WidgetBundle is actually linked
+into the extension. The appex builds, signs and registers identically with the bundle dropped by
+the linker, so nothing else in this job would have noticed the defect that shipped.
+
+Three of this stack's incidental repairs turned out to be running in parallel with the
+maintainer's own: the StepFun layout registration (#5335), the widget job's updater override
+(#5338), and this executable assertion (#5351). Each was dropped here once the other landed. The
+pattern is worth noting for the next batch — a repair found while passing through is worth
+checking against open pull requests before it is written.
+
+## What closes this
+
+Each merge reads the exact head's check runs rather than a rollup, distinguishes a job the event
+requested from one it skipped, and treats a missing, skipped, or cancelled job as not a pass. The
+last merge is followed by reading `dev`'s own push run, because five of the eight defects found in
+this unit were invisible until two changes met.
+
+## Deliberately not changed here
+
+Review asked for the public macOS install guidance to move with the release path, since
+`README.md`, `guides/desktop-app.md` and `guides/macos-menu-bar.md` all tell the reader the app is
+ad-hoc signed and not notarized, while this stack makes a real release refuse to run without a
+Developer ID and the full notarization credential set.
+
+Those pages are accurate today and will stop being accurate at the next release, not at this
+merge. No release has ever published a macOS application, so rewriting them now would describe an
+artifact nobody can download and would leave the Gatekeeper walkthrough — still correct for a
+locally built app — reading as though it were obsolete. The pages move with the first notarized
+artifact, which is also when someone can check the instructions against a real download.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/000_plan.md b/devlog/_plan/260920_meaning_preservation_batch/000_plan.md
new file mode 100644
index 00000000000..5003dc1a5a1
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/000_plan.md
@@ -0,0 +1,73 @@
+# Meaning preservation and request-scoped safety batch
+
+Status: OPEN. Opened against `main` 2.60.0 (`7c625fc9755c9824653ab944190e243091a2c85c`) and the
+current `dev` head. This unit covers the first six items of the post-2.60.0 assessment: the two
+safety fixes and the four meaning-preservation defects. Scope beyond those six is explicitly out.
+
+## Why these six
+
+The assessment scored meaning preservation lowest of the six axes. The shared failure mode is that
+a request arrives carrying an explicit constraint — which tools may be called, how a tool is
+declared, an attached document, where an instruction sits in the conversation — and the proxy
+returns a normal HTTP success after silently dropping it. A test that only asserts a successful
+tool call or a 200 response cannot see any of them.
+
+The governing rule for every item in this unit:
+
+> On a supported path, preserve it. On an unsupported path, refuse it or apply the conversion
+> policy the operator chose. Never drop it quietly and return as if the request was honored.
+
+## Delivery topology
+
+Each lane delivers **one branch with ordered commits and one pull request** against `dev`. No
+GitHub native stack and no chain of child pull requests. Where an existing contributor pull
+request already covers part of a lane's scope, the lane carries that work into its own branch with
+a `Co-authored-by` trailer naming the original author, and the superseded pull request is closed by
+the coordinator only after the lane lands. Carrying without the trailer is not acceptable:
+`missing_coauthor_credit` in `.github/scripts/pr-carry-attribution.cjs` exists because
+`CREDITS.md` already lists 27 landings that lost their author.
+
+## Lanes
+
+### Lane A — meaning preservation on the request path
+
+| Item | Contract to restore |
+| --- | --- |
+| #5211 | Caller-specified `allowed_tools` and `parallel_tool_calls: false` survive the Chat Completions path from inbound parse to the actual outbound request. |
+| #5210 | Tool declaration `strict` and `allowed_callers` reach destinations that support them; an unsupported destination refuses rather than silently widening the declaration. |
+| #5212 | Inline document bytes survive the inbound parse into the internal representation and outbound, so a title-only forward is never reported as a success. |
+| #5213 | A `developer` message keeps its chronological position. Role conversion to `system` is a separate, explicitly recorded decision with its own acceptance, not a side effect of placement. |
+
+#5237 is a correct narrow fix for the #5213 position problem and is not the whole of role
+preservation. Lane A carries it with attribution and keeps position and role as two distinct
+acceptance conditions.
+
+### Lane B — request-scoped transport and managed-write safety
+
+| Item | Contract to restore |
+| --- | --- |
+| #5087 | DNS pinning and transport selection are decided by whether a proxy actually applies to *this request*, not by whether one is configured. Scheme mismatch, `NO_PROXY` and DNS failure must not produce an unintended unpinned direct connection. |
+| #5241 | A managed configuration write never follows a terminal symlink to another file, including under `apply`, `refresh`, `disable` and `restore` races. |
+
+Both existing pull requests are authored by the same contributor and are carried with attribution.
+
+## Regression discipline
+
+Behaviour changes in `src/` need focused regressions next to the existing tests for that subsystem.
+Before any push, check the union-defect classes `AGENTS.md` records, because exact-head CI cannot
+see a defect that exists only in the union of two branches:
+
+- the file-size ratchet only moves downward, so a new case goes in a sibling file registered in
+  both `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`;
+- anything exhaustive over a union — locale catalogs, `satisfies Record<Union, ...>`, hand-written
+  rosters, counts in generated documentation — must be derived rather than restated.
+
+The 2.60.0 release was blocked by exactly this class: #5239 tightened Fernet validation while an
+older case in another domain directory still minted its fixture the loose way.
+
+## Execution constraints
+
+No local suites, individual tests, typecheck, build, install or live `ocx` execution. Verification
+is static source review plus exact-head hosted CI. Branch pushes use `--no-verify`. Only the
+coordinator merges and closes issues. Public artifacts stay English and name no other repository or
+model.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/010_lane_a.md b/devlog/_plan/260920_meaning_preservation_batch/010_lane_a.md
new file mode 100644
index 00000000000..a0892345d86
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/010_lane_a.md
@@ -0,0 +1,100 @@
+# Lane A — meaning preservation on the request path
+
+Status: OPEN. Branch `codex/260920-lane-a-meaning-preservation`, cut from `origin/dev`
+`0613aaec17`. One branch, five ordered commits, one pull request against `dev`.
+
+## What each commit restores
+
+### #5211 — tool choice policy on the Chat Completions path
+
+Two constraints reached the parser and were dropped on the way out, both under a normal 200.
+
+A `tool_choice` of type `allowed_tools` is a record, is not `type: "function"`, and carries no
+`function` member, so it fell past every branch of `toolChoiceToResponses` and `body.tool_choice`
+was never assigned. Chat nests the subset under `allowed_tools` and names each entry under a
+member keyed by its own type; the Responses shape `mapToolChoice` reads carries `mode` and
+`tools` on the choice itself with a flat `name`. Both levels are now flattened. An entry that
+cannot be named is refused rather than skipped, because skipping one widens the subset.
+
+`parallel_tool_calls` had three provider states and two branches, in two places. The unset state
+is the default for every provider that never configured the knob, and it dropped the caller's own
+explicit `false` — on the translated path and, from a second copy of the same branch, on the
+native Chat passthrough. The decision now lives in `src/adapters/openai-chat/parallel-tool-calls.ts`,
+which both builders read. An explicit `true` still omits the key, matching the configured opt-out.
+
+The passthrough half was found by adversarial review, not by the original report.
+
+### #5210 — tool declaration fields on the outbound adapters
+
+`strict` was kept deliberately by the Messages inbound and forwarded by the OpenAI Chat adapter,
+and dropped by Anthropic — the target that defines it. It is now emitted when it is explicitly
+`true`. An unstated `strict` stays absent, because the inbound records it as `false` and a
+`false` on the wire cannot be told apart from silence.
+
+`allowed_callers` had no carrier at all. It now rides `OcxTool.allowedCallers` from the Messages
+inbound, through the Responses tool schema — where an undeclared key is stripped, which is why it
+never reached `buildTools` — to the Anthropic wire. The OpenAI Chat and Gemini builders have no
+counterpart and refuse with a 400 rather than rebuild the declaration without the fence. The
+unrestricted `["direct"]` default is not a restriction.
+
+Gemini's `functionCallingConfig.mode: "VALIDATED"` was plumbed to the wire compiler but only
+reachable by matching a model name. A caller-declared strict tool now selects it in place of the
+absent-choice default; `NONE`, `ANY` and a forced-name choice are never overwritten.
+
+### #5213 — developer message position, then role
+
+Delivered as two commits because they are two acceptance conditions.
+
+Position carries #5237 by Yum-wu with a `Co-authored-by` trailer. The upstream branch had the
+right idea and a broken patch (a stray `];` and an assertion that put the deferred reminder
+before the tool result), so the change was reimplemented and the attribution kept. One
+destination already had chronological placement, keyed to a model id and a registry entry; that
+is a property of prompt-prefix caching rather than of that destination, so it is now universal
+and the model/registry test is gone.
+
+Role is separate. `developer` is part of the Chat Completions role set and is now forwarded as
+sent. A destination that genuinely rejects it sets `foldDeveloperRoleToSystem`, which converts
+the role in place and never moves the message, so the placement contract holds on both paths.
+
+### #5212 — inline document bytes
+
+Both inbound parsers reduced an attachment to its name before any adapter ran.
+`OcxContentPart` gains a document member carrying the media type and the base64 payload;
+Anthropic emits the document block, OpenAI Chat the file part, Gemini `inline_data`.
+
+Widening that union is the hazard, so the part also carries the marker every text-only consumer
+already falls back to, which keeps a wire with no document representation byte-identical to
+before. Six consumers needed more than the fallback: `ollama-native` and the Cursor tool-result
+decoder would have read a nonexistent `imageUrl`, and the Kiro, Devin, Cursor and coding-agent
+text serializers would have produced an empty turn. All were found by adversarial review.
+
+The untranslated-media refusal is narrowed only where a converter actually builds the part:
+user content on the Chat projection, user and developer messages on the Responses one. A file in
+a tool output, a system message or an assistant message is still refused. The scanner and the
+decoder share one predicate, so a request cannot be exempted in one and reduced to a marker in
+the other.
+
+## Known remaining gap
+
+Tool-result documents keep the #939 marker. The Responses tool-output vocabulary has no file
+block and every adapter's tool-result path flattens to text, so carrying bytes there is a
+separate change rather than a half-done one.
+
+## Union-defect check before push
+
+- File-size ratchet: `src/adapters/openai-chat.ts` was the only capped file in the touch set
+  (cap 822). The `parallel_tool_calls` decision moved to a sibling module and the file is 811
+  lines. No cap was raised.
+- `PROVIDER_CONFIG_FIELD_POLICY` in `src/server/auth-cors.ts` is
+  `satisfies Record<keyof OcxProviderConfig, ...>`, so `foldDeveloperRoleToSystem` is classified
+  there and in `providerConfigSchema`.
+- Every new test file is registered in both `scripts/test-layout/layout.json` and
+  `tests/fixtures/test-layout-expected.json`, which the layout guard asserts are equal.
+- No count is restated: the provider reference tables gained a row rather than a number.
+
+## Verification
+
+Static source review plus exact-head hosted CI. Local suites, individual tests, typecheck,
+build, install and live `ocx` execution were NOT RUN, per the lane constraints. Adversarial
+source review ran on every commit and produced the passthrough, Kiro/Devin/Cursor/coding-agent,
+role-aware-refusal and base64-predicate findings listed above.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/010_phase2.md b/devlog/_plan/260920_meaning_preservation_batch/010_phase2.md
new file mode 100644
index 00000000000..a6a6a2ff041
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/010_phase2.md
@@ -0,0 +1,84 @@
+# Phase 2 — the ten consolidation bundles
+
+Status: OPEN. Phase 1 (items 1-6) runs in lanes A and B under [000_plan.md](000_plan.md). This file
+opens items 7-16 of the post-2.60.0 assessment. These are **not ten new pull requests**. Each bundle
+is a unit of existing issues and pull requests to reuse, with only the shared part reviewed
+together.
+
+## Delivery topology is unchanged
+
+One branch, ordered commits, one pull request to `dev` per lane. No native stack, no child pull
+request chain. Carried contributor work needs a `Co-authored-by` trailer in a branch commit;
+superseded pull requests are closed by the coordinator only after the lane lands.
+
+## Why these groupings and not one bundle per lane
+
+Bundles 7 and 14 both want the same substrate. Item 7 divides a failure into pre-header,
+headers-only, protocol prelude, semantic output, side effect and terminal, and decides resend
+permission per stage. Item 14 wants a logical request to attempt to physical send to terminal
+record with one cause dictionary. Two lanes defining that separately would typecheck on each branch
+and contradict each other in the merge — the exact class that blocked 2.60.0. They stay in one lane.
+
+Bundles 8 and 9 are the same question asked twice: an observation attributed to an account or
+credential generation must not survive its replacement. A refusal learned from the previous account
+and a warm cache binding dropped on a threshold hint are the same attribution defect at different
+layers.
+
+Bundle 13 consumes the request-scoped route decision that lane B is building for #5087. Starting it
+before lane B lands would fork that authority, so it is scheduled after.
+
+## Lanes
+
+| Lane | Bundles | Existing items to reuse |
+| --- | --- | --- |
+| C | 7 retry stage table, 14 one event model | #4942, #4989, #5245, #2366, #3748, #3983, #5063; issues #4191, #5180 |
+| D | 8 account and credential generation, 9 cache affinity and diagnostics | #5214, #5145, #5229, #5209, #4793; issues #3375, #5178, #3433, #3765 |
+| E | 10 Devin output budget, 11 adapter queue memory, 12 per-key permission | #5189, #5182; issues #5190, #5049 |
+| F (after B) | 13 per-provider egress, 15 CodeBuddy and native wire | #3901, #5148, #5147, #5188; issues #2894, #5146, #5097, #5096 |
+| G (after B) | 16 onboarding, update and screen consolidation | #5016, #4560, #5068; issues #2811, #5215, #5216 |
+
+## Ownership boundaries between concurrent lanes
+
+These exist because the lanes share a checkout-independent surface and would otherwise collide.
+
+- Lane C owns send accounting: `sendCount`, request-wide send budget and the stage and cause
+  vocabulary. Lanes D and E consume it and do not redefine it.
+- Lane D owns #4793 and every per-model cache view. Lane C derives cache projections from the
+  recorder without editing that surface.
+- Lane E owns the adapter event queue budget and the Devin and coding-agent limits. It does not
+  touch retry classification.
+- A collision that cannot be resolved inside these boundaries goes to the coordinator rather than
+  being settled unilaterally in one branch.
+
+## Acceptance that is easy to fake and must not be
+
+Each bundle has a completion condition that a passing request does not demonstrate.
+
+- 7: an uncertain resend after output or a side effect is never automatically permitted; 429, quota,
+  policy refusal and ciphertext refusal stay distinguishable; the provider's stated reason and the
+  actual send count agree, with no duplicated parent and child counter.
+- 8: a refusal or capability observation from a replaced account does not transfer; a cancelled
+  request's late refresh does not overwrite another request's binding; false, unknown and absent
+  stay distinct.
+- 9: passing a threshold alone does not drop a warm binding, while real exhaustion does; input
+  change, account change and transformation change are distinguishable; a prefix fingerprint never
+  becomes a public or durable correlation key.
+- 10: with the caller omitting a limit, the configured effective output cap reaches the wire, and an
+  explicit small cap survives; the history ceiling keeps its own meaning.
+- 11: slow consumers, one large event, accumulated coalescing and a cancel race all stay bounded
+  with no unreleased counter, and a normal long stream is not capped by total length.
+- 12: an alias, combo child, fallback or compact route cannot reach a forbidden model or provider;
+  filtering `/models` is not completion; an inference key never gains management authority.
+
+## Release shape
+
+The first stabilization release carries items 1-6 plus only the small, reproduced fixes from 8, 10
+and 11. Items 7, 9, 12, 13 and 14 form the second group. Items 15 and 16 are the optional extension
+and do not precede the fidelity work. A new large control plane, a full manager rewrite and a
+multi-tenant conversion stay out of this stabilization and are not closed as unwanted.
+
+## Execution constraints
+
+Unchanged from phase 1: no local suites, individual tests, typecheck, build, install or live `ocx`
+execution; verification is static source review plus exact-head hosted CI; pushes use
+`--no-verify`; only the coordinator merges and closes issues.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/020_incident_5261.md b/devlog/_plan/260920_meaning_preservation_batch/020_incident_5261.md
new file mode 100644
index 00000000000..400c8c79a4f
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/020_incident_5261.md
@@ -0,0 +1,48 @@
+# Incident lane — Codex sign-in lockout after an applied integration (#5261)
+
+Status: OPEN, dispatched out of band and ahead of the phase 2 bundles. This is a user-reported
+incident, not a roadmap item.
+
+## What was reported
+
+A Windows 11 user on 2.59.0 configured the Codex integration, repeatedly failed to add an account
+pool, then could not call any model from Codex. After restarting, Codex would no longer sign in at
+all: the client showed only "Unable to load sign-in requirements" and a Retry button. The reporter's
+own analysis is that every Codex request was being routed to the local proxy on port 10100 and hung
+there.
+
+## Why this outranks a model-routing bug
+
+The damaging part is not the failed inference. It is that the user is locked out of Codex sign-in
+while the integration stays applied. A reboot does not clear an applied integration, so the lockout
+survives it, and the failure surface offers no recovery the user can act on — the only visible
+control is Retry against the endpoint that is failing. A user in that state cannot reach the
+product that would let them undo the change.
+
+## What the lane must establish from source, not assume
+
+1. What the Codex integration apply path actually writes, and whether its scope covers only
+   inference or also the authentication and sign-in bootstrap.
+2. What happens to those requests when the proxy is absent or hung: a bounded timeout, a fail-open
+   path, or an indefinite wait.
+3. Whether Windows can reach a state where the integration stays applied while the service is not
+   running, including after a reboot.
+4. Whether a recovery path exists that does not require the proxy to be running, and whether a user
+   in the failure state can discover it.
+5. The account-pool add failure that triggered the sequence, recorded precisely rather than assumed
+   to share a cause.
+6. Whether anything already on `dev` since 2.59.0 changes this path.
+
+## Fix standard
+
+Having the integration applied must not be able to lock a user out of Codex sign-in. Either the
+authentication and sign-in bootstrap stays off the proxy path, or an unavailable proxy produces a
+detectable failure and a discoverable recovery. Whichever holds, it is fixed by a regression that
+simulates the dead-proxy state.
+
+## Execution constraint specific to this lane
+
+The incident is a configuration change that locked a user out. The lane therefore may not run the
+proxy, start or restart the service, or modify any credential or configuration file on the working
+machine; doing so would reproduce the damage locally. Verification is static source review plus
+exact-head hosted CI.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/020_lane_c.md b/devlog/_plan/260920_meaning_preservation_batch/020_lane_c.md
new file mode 100644
index 00000000000..a6c9b2edaa5
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/020_lane_c.md
@@ -0,0 +1,121 @@
+# Lane C — retry stage table (7) and one event model (14)
+
+Status: OPEN. Branch `codex/260920-lane-c-retry-event-model`, cut from `dev` at
+`b9483b3b510f9a8d99d465282517f7bf91678de3`. One branch, ordered commits, one pull request to
+`dev`, per [010_phase2.md](010_phase2.md).
+
+## What this lane fixes first
+
+Bundles 7 and 14 want the same substrate, so the branch defines it before touching anything that
+consumes it. `src/lib/request-failure-model.ts` is now the single statement of three things:
+
+- **Stage** — how far a failed exchange got, ordered by what the DOWNSTREAM CLIENT observed:
+  `pre-header`, `headers-only`, `protocol-prelude`, `semantic-output`, `side-effect`, `terminal`.
+  Ordering by client observation rather than by upstream progress is deliberate: the question the
+  table answers is whether a resend can duplicate something the caller already saw.
+- **Cause** — one closed dictionary, with `rate-limit`, `quota-exhausted`, `policy-refusal` and
+  `ciphertext-refusal` as four separate members because their remedies are four different actions.
+  `parameter-rejected` is separate from `policy-refusal` for the same reason: the same content
+  succeeds once the parameter changes, and `payload-too-large` is separate from `payload-rejected`
+  because a smaller rebuild succeeds where no repair helps the other.
+- **Resend permission** — derived from three small per-member facts, not written out as a
+  stage-by-cause matrix. A 6×14 matrix is a restatement that has to be re-derived by hand whenever
+  a member is added, and the cell nobody revisited is how two individually correct branches merge
+  into a wrong table. That is the class that blocked 2.60.0.
+
+A stage is how far the observable progression got, not which events happened to arrive. A turn that
+settled carrying no output — an empty completion, a 4xx error body — did not reach `terminal`; it
+stalled at `protocol-prelude`, because the caller saw no answer. `terminal` means the answer was
+delivered, which is why it is both last and refused. Commitment is a named per-stage fact rather
+than a rank comparison, so a stage added later cannot default into permission.
+
+`refused-ambiguous` forbids an AUTOMATIC resend. It does not forbid a narrowly scoped, explicitly
+opted-in recovery that a maintainer reasoned about and bounded. That distinction is what separates
+a sanctioned single-shot rebuild from a retry loop that fires because a counter had room, and it is
+why this table can be honest about the recoveries the proxy already performs.
+
+Funding follows the disposition rather than the permission, for the same reason. The opt-in reset
+replay, the bounded empty-completion rebuild and the transient 5xx ladder are all refused
+automatically and all really send, so all three still name the allowance they draw on. Keying
+funding on permission would leave exactly those paths unfunded, which is how a per-layer counter
+comes back.
+
+Two classifications were corrected during review after being checked against what the code actually
+does rather than against what the recovery kind is called. `transient-5xx` covers a status set that
+mixes a 503 the origin declined with a 500 it may already have run, so it classifies as
+`upstream-fault` and the table never claims the resend was provably safe. `console-go-upload-retry`
+replays a byte-identical body that the gateway accepts seconds later, so nothing about the payload
+was wrong and it classifies as `upstream-declined`.
+
+## No second store
+
+The durable shapes stay `PersistedUsageAttempt`, `PersistedRequestSpend` and
+`PersistedUsageEntry` in `src/usage/log.ts`, joined by `addFinalRequestLog()`. That join is already
+the one place a logical request id, its attempts, their physical `sendCount` and the terminal
+outcome meet, so this lane derives from it rather than growing a parallel history. The new module
+declares no record type and holds no state; both of its imports are types and are erased at
+runtime, so it stays a leaf.
+
+## Restatements removed
+
+Two live instances of the union-defect class, both found while fixing the substrate:
+
+- `AttemptRecoveryKind` was written twice — as a union and as the read-back whitelist
+  `normalizedAttempt` filters against. A member added only to the union compiles, is written to
+  disk, and is dropped on the next read, so the row loses the field that says why it recovered.
+  Both vocabularies are now frozen rosters with the types derived from them.
+- `recoveryClass()` in `src/server/request-metrics.ts` ended in `default: return "other"`, so a
+  recovery kind added later compiled cleanly and vanished into an unactionable bucket. It is now
+  total over the shared cause dictionary; a missing member is a typecheck failure.
+
+## Ownership
+
+This lane owns `sendCount`, the request-wide send budget, and the stage and cause vocabulary.
+Lanes D and E consume them and do not redefine them. #4793 and every per-model cache view belong to
+lane D; this branch edits neither and derives nothing from them.
+
+## Dispositions
+
+### Carried
+
+| Item | Disposition |
+| --- | --- |
+| #5245 (cmdy) | **Carried, narrowed.** Only an embedded `invalid_request_error` / `invalid_encrypted_content` is admitted through the gateway wrapper. The original reruns the whole opaque classifier on the embedded payload, which would also admit the code-less unverifiable-ciphertext wording, the #4469 caller mismatch and the two xAI decoder strings — identities accepted on evidence about how one specific upstream words its own rejection, which a gateway in between is not. A gateway envelope is now decided ONLY by its embedded payload: the pre-existing anchored-wording checks run on the whole message, and a gateway quotes the upstream's message inside its own, so a relayed caller mismatch would otherwise have satisfied the #4469 identity and gained a resend the strict check exists to withhold. Attribution is in the branch commit. |
+| #4191 | **Addressed in part.** The WebSocket failure classifier now has a tested projection onto the shared stage and cause, so its four outcomes are stated in the same words as every other surface and the shared table independently reaches the transport's own no-replay-after-send verdict. The projection is not yet threaded into the durable record, and the SSE fallback the issue also asks for is a transport change; neither is in this branch. |
+| #5180 | **Addressed in part.** `rate-limit` and `quota-exhausted` are separate causes with different resend decisions and different metric label values. The shared cooldown and `Retry-After` handling the issue also asks for are routing behaviour and are not in this branch. |
+
+### Deferred, with reasons
+
+| Item | Disposition |
+| --- | --- |
+| #4942 (FredAmartey) | **Deferred to a follow-up on this substrate.** The pre-header ambiguous-reset stage and its default refusal are now expressed in the shared table, which is what the PR's `replaySafe`/`replayResets` pair was duplicating. The PR itself is a 28-file transport change touching provider config, key failover and passthrough dispatch, and `dev` has moved under it around `request-execution-budget.ts` and `physical-send.ts`. Landing that reworked and unrun in a branch whose verification is static review would be a worse trade than deferring it. |
+| #4989 | **Deferred to the same follow-up.** Its protocol-prelude state gate (`responseCreated && !outputCommitted && !terminal`) is exactly the `protocol-prelude` row of the shared table and is the correct model. It overlaps #4942 in `src/lib/upstream-retry.ts` and `passthrough-dispatch.ts`, and the two must not each buy an independent replacement send for one logical request, so they belong in one reworked change rather than two. |
+| #2366 (chilung-cgu) | **Deferred.** Its `StreamTimeline`, `FailureSide` and seven-stage `FailureStage` are good source material and store nothing in parallel, but they are a second stage vocabulary. Reconciling them with the one landed here is a rewrite of the PR, not a carry, and it is better done once the substrate is on `dev`. |
+| #3748 (yansigit) | **Deferred as implemented.** It adds an authoritative SQLite failure ledger beside the usage ledger, which is the parallel store this lane exists to avoid. The derived equivalent is to group recorder terminals by a versioned fingerprint of closed cause plus provider and model class. Its API also accepts a free-text `signature`, and regex redaction cannot prove content was removed. |
+| #3983 (yansigit) | **Deferred.** Content-free and durable-store-free, but it emits through a second path independent of request recording. The derived form routes the same structural observations through the recorder and formats the debug ring from them. |
+| #5063 (Vocllum) | **Deferred.** Sound retention work on the canonical ledger, and orthogonal to the stage and event model. It also changes GUI surface, which this branch cannot evidence. |
+| GUI recovery-kind roster | **Deferred, and it is a real defect.** `gui/src/pages/Logs.tsx` declares its own `AttemptRecoveryKind` with nine of the durable thirteen members, so `key-401`, `oauth-account-429`, `opaque-blob-rejection` and `reasoning-effort-downgrade` have no localized label. Fixing it needs new strings across ten locale catalogs and a screenshot of the changed dialog, which a branch that may not build or run the GUI cannot produce. It should be one follow-up that derives the GUI union from the durable roster instead of restating it. |
+
+## Verification
+
+Static source review plus exact-head hosted CI, per the batch execution constraints.
+
+Checked statically on this branch:
+
+- every assertion in the two new test files was re-derived by hand from the declared tables, and
+  the only recovery kinds whose Prometheus class changes are `opaque-blob-rejection`
+  (`payload` to `ciphertext`) and `console-go-upload-retry` (`payload` to `transient`), both
+  corrections rather than side effects;
+- every `satisfies Record<Union, ...>` added here is total over its roster, and every value it
+  produces is a declared member of the target vocabulary;
+- `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json` agree
+  key-for-key, and both new test files sit in the domain they are registered to;
+- no file this branch touches has a `tests/fixtures/file-size-baseline.json` cap, and the new test
+  cases went into a sibling file rather than into `responses-opaque-blob-recovery.test.ts`, which
+  sits 148 lines under the new-file threshold;
+- `src/server/index.ts` is untouched; it has one line of headroom against its cap.
+
+NOT RUN on this branch, by instruction: `bun run test`, any individual `bun test` file,
+`bun run typecheck`, `bun run build:gui`, `bun install`, `bun run structure:check`,
+`bun run privacy:scan`, and any live `ocx` execution. None of these may be recorded as passing.
+Hosted CI at the exact head is the only execution evidence for this branch.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/020_lane_g.md b/devlog/_plan/260920_meaning_preservation_batch/020_lane_g.md
new file mode 100644
index 00000000000..1d38c8531ef
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/020_lane_g.md
@@ -0,0 +1,120 @@
+# Lane G — onboarding, update and screen improvements as one flow
+
+Status: OPEN. Branch `codex/260920-lane-g-onboarding-update`, cut from `origin/dev`
+`043aa435ff`. One branch, ordered commits, one pull request against `dev`.
+
+Roadmap item 16 asks for connect → confirm → change → check state → recover as a single user
+flow, built on the server-owned preview that landed in #5185 and #5197. Six targets were named:
+#5016, #4560, #5068, #2811, #5215 and #5216.
+
+## The finding that shapes the flow
+
+The dashboard is served by the proxy. `startServer` binds the listener and that same listener
+serves `gui/dist`, so when the proxy stops there is no surface left to render a recovery panel.
+The state #5261 was reported in — injected routing pointing Codex's own built-in provider at a
+dead loopback port — is therefore a state the dashboard cannot be part of getting out of.
+
+That is not a reason to leave the failure state undesigned. It moves where the design has to
+land:
+
+- **Recovery belongs to the surfaces that survive the proxy.** #5267 already placed it there:
+  `ocx status` names `ocx restore` when the proxy is down and the routing is ours, the routing
+  marker in `config.toml` now reads `(undo: ocx restore)`, and the troubleshooting page covers
+  the manual edit for someone without the CLI.
+- **The dashboard's job is disclosure before the fact.** It is the only surface present at the
+  moment the integration is applied, and it is the one that will be gone if the proxy later
+  stops. Naming the offline undo path at apply time is what turns a lockout into an
+  inconvenience.
+
+## What each target needed, and what this lane did
+
+### #5216 — compaction panel (delivered)
+
+Two strings described behaviour the code does not have. The panel decided combo-ness by testing
+a `combo/` prefix, so a combo reached through an alias was described as an ordinary provider and
+none of its targets were named. It now asks what the selection resolves to, keyed by the public
+model id the server already computes, read through `parseComboList` — the same reader the combo
+workspace uses, so the selector rule is not written down twice.
+
+The warning claimed a covered compaction goes to every target including failover targets.
+`core-combo.ts` dispatches one target per loop iteration, returns as soon as one responds, and
+advances only after a retryable failure. An operator reading the old text would budget fan-out
+cost and latency for something that never happens.
+
+### #5215 — hand-copied registry values (delivered)
+
+Thirteen presets restate a byte ceiling and a row ceiling in eight guides, checked by nobody.
+Each value is now read from that preset's `modelDiscovery`.
+
+Two details worth keeping: sections are located by brand name plus the presence of a `KiB`/`MiB`
+token rather than by a translated phrase, because a restated anchor is the same hand-copied value
+the guard exists to remove; and the byte ceiling is compared as an exact token set, so a stale
+number left beside the current one fails instead of passing on a substring.
+
+The guard immediately earned its keep. `structure/ops/docs-and-release.md` asserted in prose that
+the guides carry the same limits. That was false when it was written: the Korean guide had no
+Featherless section, so it documented twelve of the thirteen limited presets. The section is
+added and the prose is replaced by a description of what is actually asserted.
+
+### #4560 and #5068 — the two workspace pull requests (analysed, not merged)
+
+The instruction was to review the actual difference and consolidate only duplicated screens. They
+are not the same feature and must not be treated as one.
+
+- 46 files and 39 files, intersecting in 31. Only **nine** of those 31 are byte-identical.
+- **#4560** is the UI foundation: responsive grid, dual collapsible rails, unified filter,
+  Cockpit Tools import, the quota-analysis regression suite and its layout registrations.
+- **#5068** is the pool follow-up: generic pool enablement and strategy persistence, strategy
+  preview, per-account quota refresh, remaining-token estimates calibrated from request logs,
+  plan badges, switch notifications, modal focus trapping.
+
+Three findings decide the sequencing, and none of them is "they overlap":
+
+1. **#5068 removes behaviour #4560 keeps.** Its `ProviderAccountCard.tsx` drops the Grok coupon
+   badge and the `ProviderAccountQuota` fallback. Landing #5068 after #4560 would silently
+   revert them.
+2. **#5068 changes an email-masking decision.** `account-quota-analysis.ts` adds `rawEmail` and
+   prefers an unmasked value, where #4560 deliberately uses the management API's projected
+   email. That is a privacy boundary, not a display preference, and it needs explicit review
+   against the `emailMaskingEnabled` policy before either version lands.
+3. **#5068 cannot land as it stands.** It folds the collapsed-sidebar CSS into
+   `gui/src/styles.css`, which carries a committed cap of 2,958 lines; its head is 3,186. The
+   ratchet only moves downward, so the remedy is the move #4560 already makes — a sibling
+   `sidebar-collapsed.css` — not a new number.
+
+Both are 28 commits behind `dev` and conflict on all ten locale catalogs through #5197, and
+#4560 additionally conflicts on the two test-layout registries. Neither is a rebase this lane
+could carry without absorbing the privacy decision above, so the differential is recorded here
+for the coordinator to sequence rather than half-landed.
+
+### #5016 and #2811 — the Codex CLI update manager (not started here)
+
+#5016 is phase 2 of #2811 and is an open contributor pull request carrying its own plan/apply
+engine. Phase 3 is the dashboard integration. Both are left to their own lane: carrying an
+unlanded engine and building its surface in the same branch would put the authorization boundary
+#5016 is built around under review twice.
+
+## Remaining scope, stated rather than closed
+
+The one src/ defect this lane identified and did not fix: `codexStatus` in
+`src/server/management/native-integration-routes.ts` derives `state` from
+`config.clientIntegrations?.codex` alone. It reports desired configuration, not what is
+currently applied — it does not read `config.toml`, the routing kind, or the catalog pointer,
+all of which `src/codex/injected-marker.ts` already exposes predicates for. So the dashboard
+cannot answer "what is applied right now", which is half of the completion condition, and it
+names no undo path at apply time, which is the disclosure the #5261 state needs.
+
+The bounded shape of that fix: report the applied routing state from the file rather than from
+intent, carry the undo command beside it, and render both on the Codex tab. It is a change to a
+DTO that every native client shares plus ten locale catalogs, so it is its own commit set rather
+than an addendum to a documentation lane.
+
+## Verification
+
+Static source review plus exact-head hosted CI. Local suites, individual tests, typecheck,
+build, install and live `ocx` execution were NOT RUN.
+
+Both delivered changes were simulated statically against the real files before commit rather
+than assumed: the discovery-limit guard was run as a Python transcription of its own logic over
+all eight guides, which is how the Korean gap surfaced and how the byte and row values were
+confirmed to already agree with the registry everywhere else.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/020_lane_h_codex_signin_lockout.md b/devlog/_plan/260920_meaning_preservation_batch/020_lane_h_codex_signin_lockout.md
new file mode 100644
index 00000000000..fb06afae186
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/020_lane_h_codex_signin_lockout.md
@@ -0,0 +1,89 @@
+# Lane H — Codex sign-in lockout behind a stopped proxy (#5261)
+
+Status: OPEN. Base is `origin/dev` at `b9483b3b51`. One branch, ordered commits, one pull
+request to `dev`, matching the topology in [010_phase2.md](010_phase2.md).
+
+This lane is not a consolidation bundle. It is incident response to a user report, and it
+was scheduled ahead of the phase 2 lanes because the reported failure ends with the user
+unable to sign in to Codex at all.
+
+## What was reported
+
+A Windows 11 user on 2.59.0 configured opencodex, repeatedly failed to add accounts to the
+pool, then found Codex could no longer call models. After a restart Codex would not sign in,
+showing only a retry. Three screenshots on the issue show the cause on their machine: the
+root override in `~/.codex/config.toml` pointing at `http://127.0.0.1:10100/v1` with the
+proxy process gone, and a `model_catalog_json` naming a catalog file that no longer existed.
+
+## What the source says
+
+Four independent reads of `dev` agreed on the following. No proxy was started and no config
+was touched to establish any of it.
+
+1. The default loopback injection does not add a provider. It sets the codex-rs root key
+   `openai_base_url`, which redirects Codex's own built-in `openai` provider
+   (`src/codex/inject.ts:102`), plus `experimental_realtime_ws_base_url` and
+   `model_catalog_json`. It is written with an atomic replace into `$CODEX_HOME/config.toml`
+   (`src/codex/inject.ts:591`), so it survives a reboot.
+2. No auth, token or sign-in endpoint is separately redirected at the proxy. The redirect is
+   the built-in provider's base URL, and Codex has no second endpoint to fall back to.
+3. There is no liveness precondition on the write (`src/codex/inject.ts:190`) and no
+   fail-open path back to the real upstream anywhere in the runtime.
+4. Applying the integration does not install a service; that is a separate
+   `ocx service install` (`src/cli/init.ts:226`, `src/cli/init.ts:255`). The Windows
+   scheduled task carries a logon trigger and no boot trigger
+   (`src/service/windows-taskxml.ts:225`). Injection present with nothing listening is
+   therefore an ordinary post-reboot state, not a corruption.
+5. The shim runs `ocx ensure` with output discarded and `|| true`, then launches the real
+   Codex regardless (`src/codex/shim-templates.ts:134`), so a failed auto-start is silent.
+   It is also CLI-only (`src/codex/autostart-health.ts`), so it never covered the reporter,
+   who was in the Codex app.
+6. Recovery already existed and already worked offline: `ocx restore` needs no proxy, no
+   management API and no network (`src/cli/dispatch.ts:198`). It was simply not discoverable.
+   `ocx status` on a dead proxy offered only ways to restart it (`src/cli/index.ts:1586`),
+   the injected config named no command, and no troubleshooting page covered the state.
+
+## The account-pool failures are a second cause
+
+They began the session but are not the lockout. The pool is served by the management API, so
+both `ocx account login openai` and the dashboard roster need a live proxy
+(`src/cli/runtime-api.ts:68`). The browser flow additionally needs the fixed callback port
+1455, which cannot move (`src/oauth/callback-server.ts:137`), and the Windows browser launch
+swallows its own failure (`src/lib/open-url.ts:20`). The dashboard keeps the last good rows
+after a failed refresh (`gui/src/hooks/useCodexAccountPool.ts:325`), which is why a new
+account can be absent while older ones still show. Documented, not changed, in this lane.
+
+## What this lane changes
+
+The direction taken is the second of the two the incident allows. Excluding sign-in from the
+proxy path is not expressible: `openai_base_url` is one key for one built-in provider, and
+when the proxy is down no scoping helps. So the failure is made detectable and the recovery
+discoverable.
+
+1. Routing markers name their own undo: `# Auto-injected by opencodex (undo: ocx restore)`.
+   Ownership is matched as a substring everywhere, so older markers keep working, and an
+   in-place rewrite refreshes the line so existing installs gain it on the next start.
+2. `ocx status` on a dead proxy over routing we own now says sign-in fails too, and names
+   the command that does not need the proxy back.
+3. A troubleshooting page for the state, including the manual edit and the warning against
+   dropping the catalog pointer alone.
+4. Regression tests that reconstruct the reported config and run recovery with nothing
+   listening.
+
+## What it does not close
+
+- The shim still discards `ocx ensure` failures, and remains CLI-only, so the Codex app is
+  still not covered by auto-start at all.
+- Nothing revalidates `model_catalog_json` after injection. The inject-time chooser refuses a
+  missing owned catalog (`src/codex/inject/config-toml.ts:597`), but a file removed later
+  leaves a pointer that makes Codex fail to load its config.
+- Windows autostart has no boot trigger, so the post-reboot gap is unchanged.
+
+Each is a separate change with its own risk, and none of them is what locks the user out on
+its own. The issue stays open for them.
+
+## Verification
+
+Static source review and exact-head hosted CI only. No local suite, typecheck, build, install,
+service action or `ocx` invocation was used to establish any claim above, because the incident
+itself is a configuration change that locked a user out.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/030_lane_b_transport_write_safety.md b/devlog/_plan/260920_meaning_preservation_batch/030_lane_b_transport_write_safety.md
new file mode 100644
index 00000000000..c992b81e129
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/030_lane_b_transport_write_safety.md
@@ -0,0 +1,66 @@
+# Lane B — request-scoped transport and managed-write safety
+
+Status: PR #5264 open against `dev` at exact head `235525b52a`, hosted CI
+in flight. One branch, two ordered commits plus this progress record, per the
+batch topology.
+
+## Scope
+
+- #5087 — DNS pinning and transport selection now follow whether a proxy
+  actually applies to the request, not whether one is configured.
+- #5241 — a managed configuration write never follows a terminal symlink to
+  another file, including apply/refresh/disable/restore and their races.
+
+Both items carry the existing contributor pull requests by luvs01 with a
+`Co-authored-by` trailer on each branch commit. The original pull requests
+stay open for the coordinator.
+
+## Branch
+
+`codex/260920-lane-b-transport-write-safety`. Commits in order:
+
+1. `fix(transport): decide DNS pinning by whether the proxy applies to the request`
+2. `fix(integrations): reject symlinked managed write targets`
+
+## Review findings on current dev (beyond the carried diffs)
+
+- #5087's carried model counted a non-SOCKS `ALL_PROXY` for `http:` targets on
+  POSIX only. The repository's own provider-outbound e2e drives that exact
+  request through the proxy and runs green on the Windows shard too, so the
+  platform gate was dropped: `ALL_PROXY` counts for `http:` on every CI
+  platform. A present-but-unusable scheme-matched variable now fails closed
+  instead of falling through to `ALL_PROXY`.
+- The Mihomo IPv6 fake-IP gate keeps its stricter documented condition
+  (scheme-matched variable or SOCKS5 `ALL_PROXY`, non-SOCKS `ALL_PROXY`
+  never counts) via a dedicated `schemeMatchedProxyFor`, so the documented
+  and tested #3462 behaviour is byte-identical. Moving it to the new snapshot
+  would have contradicted the provider docs in every shipped locale.
+- The carried #5087 diff had no regression for the DNS-failure degradation
+  branch. Added both directions: a mismatched proxy surfaces the DNS error
+  instead of degrading to an unpinned fetch; a scheme-matched proxy keeps the
+  degradation.
+- #5241's carried diff re-exported the new primitive from `src/config.ts`,
+  which sits exactly at its file-size ratchet cap. The re-export was dropped;
+  the only consumer imports the leaf directly.
+- #5241's carried tests covered apply (at rest and swap-during-write) and the
+  Cline pair boundary. Added disable and restore refusing a symlinked target
+  with the linked file byte-identical. Refresh shares the apply observation
+  and write path, so it inherits the same refusals.
+
+## Decision-function reach (#5087)
+
+Every `providerOutboundGet/Post` caller — provider discovery, the
+model-catalog gather modules, quota probes, ollama show, and the management
+model-refresh routes — funnels through the single changed decision. The main
+inference dispatch (`providerFetch`) and OAuth token exchange
+(`src/oauth/*`, bare global fetch) do not use the DNS-pinned transport today
+and are unchanged.
+
+## Verification
+
+- Local suites, focused tests, typecheck, builds and live runs: NOT RUN (lane
+  rule). Verification is static source review plus exact-head hosted CI.
+- Union-defect sweep: no capped file touched (`src/config.ts` left
+  byte-identical), no new test files (layout inventories unchanged), nothing
+  exhaustive over a union restated (locale catalogs, rosters and generated
+  counts untouched).
diff --git a/devlog/_plan/260920_meaning_preservation_batch/030_lane_c2.md b/devlog/_plan/260920_meaning_preservation_batch/030_lane_c2.md
new file mode 100644
index 00000000000..c07447cf53f
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/030_lane_c2.md
@@ -0,0 +1,220 @@
+# Lane C2 — telemetry projections on the landed vocabulary
+
+Status: OPEN. Branch `codex/260920-lane-c2-telemetry-projections`, cut from `dev` at
+`043aa435ff8f86095f55cbe08f74d45b9858da59`, which is where lane C's stage, cause and resend
+vocabulary landed ([020_lane_c.md](020_lane_c.md)). One branch, ordered commits, one pull request
+to `dev`.
+
+## What this lane fixes
+
+The completion condition for bundle 14 is that the UI, the durable log and Prometheus agree on
+logical and physical counts and on terminal classification. They did not, and the disagreement was
+not subtle:
+
+- Three surfaces classified a terminal three different ways. The durable row carried
+  `terminalStatus` and `closeReason`; the exporter kept its own private `classifyResult`; the
+  dashboard read the numeric HTTP status and nothing else. A turn cut short by
+  `max_output_tokens` is durably `status: 200, terminalStatus: "incomplete"`, which the exporter
+  reported as `incomplete` and the dashboard rendered as a green 200. The metric said incident and
+  the operator saw success, for the same request.
+- The dashboard showed no physical send count at all. `sendCount` and `spend` were never rendered,
+  so an attempt that sent three times appeared as one row with nothing to say otherwise.
+- The dashboard's recovery-kind union had drifted to nine of the durable thirteen, so `key-401`,
+  `oauth-account-429`, `opaque-blob-rejection` and `reasoning-effort-downgrade` all reached the
+  operator as "Unknown recovery reason" — four real causes rendered as the absence of one.
+
+The fix is one classifier in `src/usage/request-outcome.ts` that the exporter imports, the
+management payload already carries, and the dashboard calls. Agreement is structural rather than a
+rule someone maintains. The data was never missing: `requestLogDto` spreads the whole durable
+entry, so the page only had to declare the fields and stop reinventing the precedence.
+
+The exporter's result label set **is** the shared vocabulary rather than a copy of it. Restating
+those four strings is what let the two drift while both looked correct.
+
+### The dashboard may only reach a contract leaf
+
+Adversarial review caught this before the first push and it is worth recording, because the
+mistake is invisible from the backend side. The dashboard is a separate TypeScript project with
+`erasableSyntaxOnly`, and a **type-only** import still pulls the imported file's entire import
+graph into that project. Importing the recovery roster from `src/usage/log.ts` therefore dragged
+`node:fs`, `node:crypto` and the config barrel into the browser build, where a parameter property
+in `src/config/atomic-write.ts` does not compile. "It is only a type import" is not a defence.
+
+So the names a browser legitimately needs now live in `src/usage/telemetry-contract.ts`, which has
+no imports at all and must keep none. `src/usage/log.ts` re-exports them so every existing importer
+keeps its path, and `src/lib/request-failure-model.ts` stopped depending on the ledger module as a
+side effect. Three cases hold the boundary: the page must not name `src/usage/log`, the contract
+must have no imports, and the outcome module must reach nothing but the contract.
+
+The same review caught the send total disagreeing in the other direction. An earlier draft reported
+`max(sends, reserved)`, on the reasoning that a budget charge with no attempt row behind it is
+still a send that left. That is true, and it still made the dashboard say four where the exporter,
+summing the same attempts the recorder summed, said three. Two defensible formulas are two answers;
+the surfaces now read the recorded totals and recompute nothing, and a case asserts the exporter's
+`opencodex_physical_sends_total` equals what the dashboard shows.
+
+## Dispositions, updated
+
+### Who is credited, and why only one
+
+Attribution follows what was actually taken, not what was read. Only #2366's work is carried here,
+so only its author carries a `Co-authored-by` trailer, and that trailer sits in a branch commit so
+it survives the squash. The other three were analysed in depth and their designs informed the
+deferral reasons below, but no line of their work is in this branch; crediting them would claim a
+landing that did not happen and would make the contributor graph say something false.
+
+A note on the gate, because getting this right took two attempts. `pr-carry-attribution.cjs` looks
+for a carry verb and reads the pull request numbers in the eighty characters after it. A first
+draft of the description read "#2366's rehydration half is carried and ... ; #3748 is blocked",
+which put #3748 inside that window and asked for a trailer naming an author whose work is
+deliberately absent. Rewording split the sentences — but it also moved #2366 out of every window,
+so the check went green by having nothing left to check. A gate that passes because the trigger was
+removed is not evidence. The provenance sentence now names #2366 after the verb, in the commit
+itself, so the check resolves the author and matches the trailer instead of skipping.
+
+### #2366 (chilung-cgu) — partially carried
+
+**Carried:** the rehydration and UI-projection half. The durable terminal facts now reach an
+operator instead of stopping at the API boundary.
+
+**Not carried, and why:** `FailureSide` and the seven-member `FailureStage` are a second
+attribution vocabulary beside the one that just landed, and defining two is the exact class that
+blocked 2.60.0. The PR also widens `transportPhase` and `terminalSource` from their existing closed
+unions to arbitrary strings, which would let bounded upstream-controlled text into the durable row;
+those validators stay. Copying the request-relative timeline into an attempt at finalization is
+simply wrong — request-relative elapsed values do not become attempt-relative by being copied.
+
+**Next step, specified:** persist `failureStage?: RequestFailureStage` and
+`failureCause?: RequestFailureCause` on `PersistedUsageAttempt`, projected onto the entry, with
+`resendPermission` computed at read time and never persisted. That is the smallest durable record
+that makes a failure attributable, and it is the prerequisite for #3748 below. It is not in this
+branch because it is new classification logic on the finalization path, and a branch whose only
+verification is static review plus hosted CI should not add a new derivation and the surface that
+consumes it in the same change.
+
+### #3748 (yansigit) — still deferred, reason updated
+
+The earlier reason was the parallel SQLite store. That still holds, but the blocking reason today is
+narrower and more useful: **the recorder does not yet record why a request finally failed.**
+`causeForRecoveryKind` answers why a *recovery* was attempted, which is a different question — a
+request that failed without any recovery, or that recovered and then failed for another reason,
+has no cause to group by. A derived failure ledger therefore cannot compute a grouping key today
+without reading `errorCode` or `upstreamError`, which are open strings.
+
+The design is otherwise settled and should be built once the field above exists: group failed rows
+scanned through the existing `scanUsageLedgerCooperatively` by a versioned fingerprint over closed
+vocabularies only — cause, status class, inbound protocol, terminal status, close reason, transport
+phase, terminal source — with fixed tuple positions so a missing field cannot collide structurally.
+No provider, no model, no account label, no free-text signature. First-seen, last-seen and count
+fall out of the scan; no second timestamp list is retained.
+
+Two parts of the original are not derivable from request history at all: the mutable
+`monitoring/dispatched/fixed/ignored` remediation status and its free-text notes. Those are
+operator state, not event history, and need their own owner rather than being presented as a
+derived ledger.
+
+### #3983 (yansigit) — still deferred as an emission path, reason updated
+
+The earlier reason was "a second emission path". The updated reason is stronger: the path is not
+ephemeral. `emitDebugLine` writes the in-process ring **and** stderr, and stderr is redirected to
+the service log under both launchd and systemd, so an installed service gets a durable per-event
+record with its own retention, sequencing, request identity and masking — beside the ledger and
+sourced from something other than it.
+
+Two further facts: four of its eighteen files no longer apply, including
+`run-turn-execution.ts` where carrying it literally would regress the current send-budget
+accounting; and its per-content HMAC is a process-global random key, so equality of every prompt,
+tool name and error message is correlatable for the process lifetime.
+
+**The useful half, specified:** a bounded normalized summary on the attempt — adapter events,
+actually relayed events, semantic bytes, side-effect events, terminal events — counted where the
+event is delivered rather than where it is read. That keeps the signals worth having (missing
+terminal, adapter-to-relay loss, empty output, partial output size) and inherits the ledger's
+normalization, masking and retention instead of inventing its own.
+
+### #5063 (Vocllum) — still deferred, reason updated
+
+The earlier reason was "a separate product slice with GUI surface". The updated reason is a
+correctness one found while reviewing it against current `dev`:
+
+- Retention captures the file size, copies a retained suffix to a temp file and renames. A row
+  appended by **another process** between the size snapshot and the rename is silently dropped.
+  The PR's own "concurrent re-entrancy" test performs two sequential calls and says it cannot test
+  true concurrency.
+- Both the temp-file fsync and the parent-directory fsync failures are swallowed, and replacement
+  proceeds anyway. There is no revision, inode or digest comparison immediately before the rename.
+- It hand-rolls the copy rather than using `src/config/atomic-write.ts`.
+- It does not clear the 2,000-entry request-log ring, so rows deleted from disk stay visible
+  through `/api/logs` until eviction or restart.
+- `src/server/index.ts` is 892 lines against a 893-line cap, so the startup wiring cannot land as
+  written without offsetting a line elsewhere.
+
+Retention on the canonical ledger is the right architecture and its derived-index invalidation is
+correct in shape. It needs a ledger-owner serialization and revision contract first.
+
+### The dashboard roster defect — fixed here
+
+Recorded in [020_lane_c.md](020_lane_c.md) as deferred because it needed strings across ten
+catalogs and a screenshot. It is fixed in this branch because the agreement condition required
+touching this page anyway. The union is now derived from the durable roster and a `satisfies`
+clause makes the next added kind a typecheck failure rather than a silent fallback.
+
+**This trips the `missing_ui_screenshot` gate.** That gate fires on changed paths under `gui/`,
+not on words in the description, and this lane may not build or run the GUI, so it cannot produce
+the screenshot itself. A maintainer comment or the `gui-screenshot-waived` label is the documented
+resolution; the visible change is four attempt rows that said "Unknown recovery reason" now naming
+their cause, plus an outcome row and a send count in the detail dialog.
+
+## Retention and masking, stated in one place
+
+The instruction was to unify rather than add a fifth policy. The honest form of that today is to
+record what already exists and bind projections to it, because every bound below is already
+enforced and none of them needs a new owner:
+
+| Surface | Bound |
+| --- | --- |
+| Usage ledger rows (scanner) | 1 MiB per row, 1 MiB read chunks, 64 KiB boundary digest |
+| Startup request-log hydration | 64 MiB read ceiling |
+| Management usage snapshot | 64 MiB, 500,000 rows |
+| Usage metadata strings | sanitized, capped at 64 characters |
+| Upstream error text | `redactSecretString`, capped at 500 characters |
+| Conversation correlation | rejects over 4,096 characters, persists a 32-hex digest |
+| Debug ring | 2,000 lines, 16 KiB per line, 64 subscribers |
+| Request-log ring | 2,000 entries plus app-owned-memory eviction |
+| Routing history | rebuildable projection; pages capped, records over 1 MiB omitted |
+| Email masking | masked unless `privacy.maskEmails: false` |
+
+The policy this lane adopts: **masking happens at capture and projection boundaries, retention
+deletes canonical rows, and every derived surface inherits both.** A projection does not get its
+own TTL, its own row cap or its own redaction pass. The failure projection specified above obeys
+this by construction — it holds only aggregates and a scanner checkpoint, and discards them when
+the source is replaced.
+
+## Issues
+
+#4191 and #5180 stay open and are not closed here. What narrowed: the dashboard now reports the
+terminal classification and the send count the durable row always carried, so an operator can tell
+an incomplete turn from a successful one without reading the ledger. What remains unchanged: the
+WebSocket-to-SSE fallback for #4191, and the shared cooldown and `Retry-After` handling for #5180.
+
+## Verification
+
+Static source review plus exact-head hosted CI.
+
+NOT RUN on this branch, by instruction: `bun run test`, any individual `bun test` file,
+`bun run typecheck`, `bun run build:gui`, `bun run lint:gui`, `bun install`,
+`bun run structure:check`, `bun run privacy:scan`, and any live `ocx` execution. None of these may
+be recorded as passing.
+
+Checked statically on this branch:
+
+- all eleven new label keys are present in all ten catalogs, and the catalog edits are purely
+  additive (+11 lines, 0 removed, per file);
+- the ten catalogs are explicitly exempt from the file-size ratchet, for the reason the exemption
+  list gives: they grow by one line per UI string across every locale at once;
+- no ratchet-capped file is touched by this branch;
+- `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json` agree key for
+  key, and the new test's regex seed resolves to the same domain it is registered to, which is the
+  oracle that failed lane C on its first push;
+- no test restates a source constant: the outcome vocabulary, the recovery roster and the label
+  keys are all read from the modules that declare them.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/030_lane_h2_lockout_dead_ends.md b/devlog/_plan/260920_meaning_preservation_batch/030_lane_h2_lockout_dead_ends.md
new file mode 100644
index 00000000000..d1c6f7c1d94
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/030_lane_h2_lockout_dead_ends.md
@@ -0,0 +1,90 @@
+# Lane H2 — the remaining Codex lockout dead ends (#5261)
+
+Status: OPEN. Base is `origin/dev` at `043aa435ff`, after lane H landed as `9880c3cad2`.
+One branch, ordered commits, one pull request to `dev`.
+
+Lane H removed the dead end a locked-out user hits: injected routing now names its own undo,
+a dead proxy is told to say so, and there is a troubleshooting page. This lane takes the four
+paths INTO that state which lane H listed as not closed.
+
+## Why these four belong together
+
+None of them locks anyone out alone. Each one removes a signal, and the incident is what
+happens when all of them are missing at once: a proxy that stopped, an autostart that failed
+silently, a reboot that restarted nothing, a catalog pointer left naming a deleted file, and an
+account flow that looked like it was working. Every individual step had an explanation; the
+user had no way to reach any of them.
+
+## 1. The shim hid autostart failure, and could prevent Codex launching
+
+The wrapper ran `ocx ensure` with both streams discarded and `|| true`, then launched Codex
+regardless (`src/codex/shim-templates.ts:139`). A failed start was invisible.
+
+Ensure's own streams stay discarded rather than being let through. It prints progress and
+warnings on exit-zero runs too, so a wrapper that leaked them would put noise in front of every
+ordinary launch, which is how a diagnostic gets ignored. The exit status is the signal.
+
+PowerShell had the opposite defect in the same place: a throwing `ensure` escaped a `try/finally`
+with no `catch`, so Codex never launched at all. The autostart helper was producing the exact
+lockout it exists to prevent, and the previous test asserted that propagation as correct
+behaviour. It now catches, reports, and hands over.
+
+Not closed: the Unix revision marker moved to 3 so installed Unix shims regenerate, but Windows
+shims carry no revision marker and are excluded from obsolete-shim refresh
+(`src/codex/shim.ts:892`). Existing Windows wrappers keep the old text until reinstalled. Giving
+Windows a refresh path is its own change.
+
+## 2. The catalog pointer — my lane H note was wrong
+
+Lane H recorded that nothing revalidates `model_catalog_json` after injection. That is not true.
+The chooser refuses a missing owned path and the caller strips the stale line
+(`src/codex/inject.ts:327`), with end-to-end coverage already in place.
+
+The real gap is narrower and worse: that repair only reaches someone who runs opencodex again,
+and the difficulty of this state is that Codex is the thing that stopped working, so nothing
+prompts them to. A `model_catalog_json` naming a file that is gone does not degrade Codex, it
+stops Codex loading its configuration at all — the same blank wall as dead routing, from a
+different cause. So this lane adds detection, not repair, and `ocx status` now names the file
+and both ways out.
+
+## 3. Reboot: stated, not faked
+
+Applying the integration does not install a service, and the Windows scheduled task a separate
+install would create is logon-triggered (`src/service/windows-taskxml.ts:225`). Setup ended on a
+success line without ever saying routing outlives the proxy.
+
+A BootTrigger is deliberately NOT the fix. The task runs as the interactive user
+(`LogonType: InteractiveToken`), so before logon there is no session for it to run in; the
+trigger would read like a fix and change nothing. Genuine pre-logon start means a different
+principal and a different service backend, which is larger than this lane and is left open
+rather than half-done. What was cheap and true on every platform is saying the dependency
+exists, reusing the health model `ocx status` and `ocx doctor` already report.
+
+## 4. Account pool: a silence, not an error
+
+The URL launcher swallowed its own failure and returned nothing, so the Codex login route
+answered identically whether a browser opened, failed, or was skipped. The CLI printed the URL
+and polled, and a user whose machine could not launch a browser watched something that looked
+like it was working.
+
+Launch failure is now reported and never fatal — the URL is still worth opening by hand and the
+flow stays live. The CLI names the fixed callback port 1455, because ChatGPT supplies the
+redirect URI and the flow cannot move to a free port, so `--device` is the way around it.
+
+Not closed: the dashboard keeps last-good rows after a failed refresh
+(`gui/src/hooks/useCodexAccountPool.ts:325`), which is why a newly added account can be absent
+while older rows still show. That is a GUI change, and the pull-request gate requires a
+screenshot of a UI change, which cannot be produced under this lane's no-build constraint. It
+is left for a lane that can build the GUI.
+
+## Verification
+
+Static source review and exact-head hosted CI only. NOT RUN, by lane constraint: local suite,
+individual tests, typecheck, build, install, `ocx` execution, service start or restart, and any
+change to credentials or configuration on the machine. The incident being fixed is a
+configuration change that locked a user out.
+
+Checked before push: the file-size ratchet (no tracked file over cap; `codex-shim.test.ts`
+sits close to its cap, so the new shim tests went to a sibling file registered in both
+layout maps), and the restated-constant class that broke two lanes in this batch — the shim
+test's private literal copies of the marker constants now come from the source module.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/050_lane_d_account_cache_generation.md b/devlog/_plan/260920_meaning_preservation_batch/050_lane_d_account_cache_generation.md
new file mode 100644
index 00000000000..e4eac30867c
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/050_lane_d_account_cache_generation.md
@@ -0,0 +1,226 @@
+# Lane D — account/credential-generation evidence and cache affinity
+
+Status: branch pushed for hosted CI. One branch, ordered commits, one PR
+against `dev`, per the batch topology.
+
+## Scope
+
+Bundle 8 — an observation attributed to an account or credential generation
+must not survive its replacement:
+
+- #5214 (carried) — entitlement refreshes fenced behind native-main admission.
+- #5145 (carried) — learned reasoning-effort refusals scoped to the credential
+  identity, snapshot v2, legacy destination-wide rows ignored.
+- #5229 (carried) — Cursor live wire-spelling and Max-Mode evidence keyed by
+  destination+credential scope.
+- Lane addition: Cursor and Devin live *rosters* (the cached model list
+  itself, not just the derived evidence) are now bound to an irreversible
+  credential fingerprint, including the stale fallback and the failure
+  cooldown's suppression.
+- Lane addition: a cancelled data-plane request's late entitlement refresh no
+  longer commits — the /v1/models signal reaches the native-main token
+  refresh, which re-checks it before the auth.json write.
+
+Bundle 9 — a threshold hint is not exhaustion, and cache-loss causes must be
+distinguishable:
+
+- #5209 (carried) — shared cache-affinity bindings retire on genuine 100%
+  exhaustion, not on the proactive auto-switch threshold.
+- #4793 (carried) — per-model cache metrics on the Usage page (lane D owns
+  this surface).
+- Lane addition: opt-in privacy-bounded cache diagnostic (#5178), one record
+  per finalized request in `cache-debug.jsonl`, so client prefix change,
+  account change and proxy transformation change are distinguishable without
+  retaining content or a durable correlation key.
+
+All four luvs01 pull requests and xdober's #4793 are carried with
+`Co-authored-by` trailers on the branch commits. The original pull requests
+stay open for the coordinator.
+
+## Branch
+
+`codex/260920-lane-d-account-cache-generation`, cut from `origin/dev`
+(`b9483b3b51`). Commits in order:
+
+1. `fix(codex): preserve cache affinity across model detours` (carries #5209)
+2. `fix(reasoning): scope learned reasoning-effort refusals to credential identity` (carries #5145)
+3. `fix(cursor): isolate live roster and Max Mode evidence by account` (carries #5229)
+4. `fix(codex): fence entitlement credential refreshes behind admission` (carries #5214)
+5. `feat(usage): show cache metrics by model` (carries #4793)
+6. `test(codex): move cache-affinity detour cases to a sibling under the file-size cap`
+7. `fix(codex): bind Cursor and Devin live rosters to the observing credential`
+8. `fix(codex): fence cancelled entitlement refreshes behind caller cancellation`
+9. `feat(usage): opt-in privacy-bounded cache diagnostic (#5178)`
+
+## Review findings on current dev (beyond the carried diffs)
+
+- #5229 scoped the Cursor spelling/Max-Mode maps but not the roster cache
+  itself: `provider-models.ts` read and wrote the Cursor and Devin live model
+  lists by provider name alone, and the failure cooldown let one credential's
+  error suppress another's discovery. Qoder already had the correct pattern
+  (`authorityIdentity`); the lane extended it.
+- The entitlement admission fence (#5214) covered lifecycle drains but not
+  caller cancellation: `/v1/models` never passed `req.signal`, and the
+  native-main refresh committed its late result without re-checking it. The
+  roster-cache publication needed no change — it is already fenced by
+  credential identity plus mutation epoch, which is the right boundary for a
+  shared flight.
+- False/unknown/absent is covered on the entitlement path
+  (`model-entitlements.ts` keeps a `confirmed` bit separate from the model
+  set, and the public state is tri-state) and is pinned by existing tests in
+  `codex-model-entitlements.test.ts`. For usage telemetry the distinction
+  rides the existing provenance enum: a measured zero is `observed`, a
+  defaulted zero from a normalized wire is `synthesized`, and an absent
+  counter is `unknown` — an earlier revision of this branch changed
+  extraction to keep all-zero frames alive, and review rejected it because it
+  reclassified spend settlement for placeholder frames.
+- Deliberately NOT generation-scoped: quota/rate-limit avoidance
+  (`health-store.ts`, `subagent-model-fallback.ts`). Those observations
+  describe the subscription, not the token generation; scoping them to a
+  credential refresh would re-hammer a known-drained account. The 401/403
+  quarantine is already generation-fenced. Model static policy and live
+  health were not mixed in either direction.
+
+## Ownership boundaries respected
+
+- Lane C owns send accounting (`sendCount`, request-wide send budget, stage
+  and cause vocabulary). This lane consumes `loggedUsage`, provenance and
+  the affinity enums and does not redefine any of them.
+- Lane D owns #4793 and the per-model cache view; the diagnostic reuses the
+  usage ledger's account label (salted, process-local) instead of inventing a
+  new identifier.
+
+## Adversarial review (pre-CI) and its dispositions
+
+- HIGH, fixed: the carried entitlement-admission test kept its tests-root
+  import paths after the domain move; all imports now resolve.
+- HIGH, fixed: the diagnostic's block splitter aliased an array-valued
+  `instructions` field and would have mutated the live request body; it now
+  copies, pinned by a mutation regression test.
+- MEDIUM, rejected with reason: persisted same-process equality tags were
+  called a correlation key. The issue being closed explicitly requests
+  process-scoped salted equality tags so two requests can be compared; the
+  key dies with the process, the file is owner-only, and retention is bounded
+  at 100 records. That is the requested design, not a breach of it.
+- MEDIUM, accepted: the all-zero usage extraction change altered spend
+  settlement semantics for placeholder frames; reverted. The measured-zero
+  versus absent distinction needs no extraction change for any frame that
+  reports tokens.
+- Also fixed: a trailing blank line flagged by `git diff --check`.
+
+## Exact-head CI at 55b512d2 and its dispositions
+
+Run 35492856534 failed `gates`, `test 1/4`, `test 4/4` and `macos 1/2`. Three
+distinct causes, none of them a flake:
+
+- `gates` reported five typecheck errors. Two were mine and trivial:
+  `cache-diagnostic.ts` narrowed `draft.promptCacheKey` through optional
+  chaining and then read it again unguarded. Fixed by binding the inbound key
+  once.
+- The other three were the interesting ones, and they are the union class this
+  batch keeps hitting. `catalog/effort.ts` and `catalog/build-entries.ts` cast
+  a partially populated ladder to `Array<{ effort?: string }>` and then push a
+  canonical `CODEX_REASONING_LEVELS` rung into it, which also carries
+  `description`. That has always been a type error; it was invisible because
+  `reasoning-effort.ts` → `providers/reasoning-metadata.ts` →
+  `providers/key-store.ts` → the `../config` barrel formed an import cycle,
+  and inside it the rung type degraded so the excess-property check never ran.
+  Carried #5145 breaks that cycle on purpose — its new `api-key-resolve.ts` is
+  a leaf module written so reasoning-metadata can import it without the barrel
+  — so the latent error surfaced on this branch first. Neither file is in this
+  lane's scope and neither is touched by its diff; the fix is the remedy
+  `AGENTS.md` prescribes for a restated shape: `reasoning-effort.ts` now
+  exports `CodexReasoningLevel`, and the three casts derive
+  `Array<Partial<CodexReasoningLevel>>` from it instead of restating a
+  narrower literal. Any lane that breaks this cycle would have hit the same
+  wall.
+- `test 4/4` (`production adapter contract rejects omitted translator budgets
+  at typecheck`) spawns tsc over the project and asserts the valid fixture
+  exits zero. It was downstream of the same five errors and needs no change of
+  its own.
+- `test 1/4` (`Cursor catalog discovery cooldown > second refresh during
+  cooldown does not re-invoke discovery`) was a real regression from this
+  lane. Scoping only the roster reads to the credential left the failure
+  cooldown provider-wide, so the branch had to require a credential-scoped
+  stale entry before honouring it — and a discovery that fails before caching
+  anything has no stale entry, which reopened the timeout storm #54 closed.
+  The fix moves the scope to where the observation actually belongs: a
+  discovery failure now records the credential that observed it, and
+  `isModelsFetchCoolingDown` suppresses only that credential. A failure
+  recorded without an identity stays credential-agnostic and suppresses
+  everyone, so plain-endpoint providers and the existing Qoder branch keep
+  their current behaviour unchanged. This is the same thesis as the rest of the
+  bundle: one account's 401 or 404 is not evidence about another account's
+  catalog. `cursor-roster-account-scope.test.ts` already pins both halves.
+- `macos 1/2` carried the same shard failures as the Linux shards.
+
+The branch is now aligned on `dev` at `447ac22ca6` (lanes B and E landed).
+Lane E's `run-turn-queue.ts` and `admission-model-scope.ts` do not overlap
+this lane's surface; the merge was clean.
+
+Run 35496444256 at `6bd074e0` confirmed both fixes: `test 1/4` and `test 4/4`
+passed, along with every other shard, both macOS shards, `structure gate`,
+`docker smoke`, `docs site build`, `api usage`, `storage policy`, keyring on
+all three platforms and `npm-global` on all three. Only `gates` still failed,
+on three GUI assertions, all of them the same restated-literal class and all
+introduced by the carried #4793 columns:
+
+- `usage-custom-range` listed the models-table headers as English literals and
+  omitted the `API list-price` column the page already renders, so the case
+  could not pass on any tree carrying both. The expectation now maps the
+  ordered column keys through the `en` catalog, which is where that copy lives.
+- The French accidental-English guard and the zh-TW stale-placeholder guard
+  both flagged `usage.unavailable`, whose value is an em dash. Adding one more
+  allowlist entry would have been literal-for-literal, so both checks now
+  derive the rule from the value: with placeholders removed, a string carrying
+  no letters has nothing to translate and is identical in every locale by
+  construction. Keys that do carry letters, `uptime.hour` among them, stay
+  allowlisted and still fail if they go untranslated.
+
+## Verification
+
+### The macOS sideband failure was shard composition, not the relay
+
+`macos 2/2` then failed twice on `sideband GET /v1/live/{callId} relays the exact frame
+ceiling bidirectionally`, and it is worth being precise about why, because retrying it would
+not have helped and neither would touching its deadline.
+
+The case relays a 50 MiB WebSocket frame end to end against a hard 15s deadline. It is not in
+`SERIAL_FULL_SUITE_FILES`, so it runs inside `bun test --shard=N/2` sharing one process with
+the rest of that half. On `dev` at `043aa435f` it lands in shard 1 and its echo leg alone
+takes **7.4s of the 15s budget**. This branch adds three test files in unrelated directories,
+Bun repartitioned the halves, `tests/server/server-live.test.ts` moved to shard 2, and the
+echo leg went past 15s on both attempts while the peer never received the frame
+(`recv=13 progress=5 moving=no`). Nothing in this lane's diff touches the sideband relay, the
+live route or WebSocket handling, and the delta between the run that passed every shard and
+the run that failed this one is three GUI test files and a devlog page.
+
+So the test has been passing by accident: its result was a property of which half it drew.
+The remedy is the mechanism the repository already has for this exact category —
+`SERIAL_FULL_SUITE_FILES`, described in its own guard as quarantining *load-sensitive* files
+into one-worker lanes. Adding `server/server-live.test.ts` there keeps the 15s deadline, keeps
+the assertion, and keeps macOS in the matrix; it only stops the case from sharing a process.
+It also takes the landmine out of the path of the next lane that adds a test file anywhere in
+the tree. If the coordinator would rather own that change centrally, it is one line in
+[scripts/test.ts](../../../scripts/test.ts) and can be lifted out of this branch.
+
+Per batch rules, no local suites, individual tests, typecheck, build,
+install or live `ocx` execution. Verification is static source review plus
+exact-head hosted CI.
+
+- NOT RUN: `bun run test`, focused `bun test`, `bun run typecheck`,
+  `bun run lint:gui`, `bun run build:gui`, `bun run privacy:scan`,
+  `bun run structure:check` (all forbidden locally; hosted CI decides).
+- Static checks performed: file-size ratchet evaluated against
+  `tests/fixtures/file-size-baseline.json` (the carried routing test would
+  have grown 83 lines over its cap — moved to a registered sibling; all new
+  files are far below the 2000-line threshold); both layout registries carry
+  every new test file and parse as JSON; the ten GUI locale catalogs gained
+  identical keys (no hand-restated roster or count); the diagnostic module's
+  imports were walked for a `src/lab/` reach (none) and `responses/core.ts`
+  gains no runtime import of it.
+- Focused regression tests added next to the existing subsystem tests:
+  roster credential binding (Cursor, Devin), cancelled-refresh fencing
+  (admission + main-account refresh), measured-zero survival (usage
+  passthrough), and the diagnostic itself (privacy, fingerprints, alias
+  rebinding, retention, tag independence from affinity-debug).
diff --git a/devlog/_plan/260920_meaning_preservation_batch/050_lane_e.md b/devlog/_plan/260920_meaning_preservation_batch/050_lane_e.md
new file mode 100644
index 00000000000..154a0a639e9
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/050_lane_e.md
@@ -0,0 +1,128 @@
+# Lane E — output budgets, queue memory, per-key policy
+
+Status: OPEN. Branch `codex/260920-lane-e-budgets-key-policy` against `dev`, one pull request.
+Covers phase 2 bundles 10, 11 and 12 from [010_phase2.md](010_phase2.md).
+
+## What each bundle turned out to be
+
+### 10 — Devin output budget and the history ceiling
+
+Two defects, not one. The adapter forwarded only a caller-supplied
+`max_output_tokens`, and Codex never sends one, so every `devin/*` turn was capped at
+the cloud-direct encoder's 8192 fallback however the provider was configured. The
+escape hatch was closed too: no OAuth preset declares `defaultMaxOutputTokens` or
+`modelMaxOutputTokens`, so the delete-when-preset-undefined branch in
+`applyOAuthPresetCatalog` was the only branch either field ever took and a
+hand-edited value was gone before the next startup finished. Both had to move, or
+wiring the adapter alone would have been unreachable in practice.
+
+The resolver reads the caller's explicit value, then the configured per-model cap,
+then the provider default, then nothing — leaving the encoder fallback. It never
+reads `contextWindow` or `modelContextWindows`: CompletionConfiguration #2 is the
+output cap and #3 is the context window, and collapsing them would ask Cognition to
+generate a whole window of output.
+
+The history ceiling is the other half and stays a separate quantity. #5189 is
+carried with attribution: it derives the coding-agent projected-history bound from
+the declared context window in characters. That bounds replayed history memory;
+nothing there decides how long a reply may run.
+
+No retry change was needed. Source review of `stated-reset-retry.ts` and
+`upstream-retry.ts` confirms an upstream `incomplete / max_output_tokens` is a
+successful streaming response that has already emitted events, so it matches none
+of the replay conditions. The repeated identical attempts in #5190 are the client's.
+
+### 11 — adapter event queue memory
+
+PR #5182 had the right idea and the wrong number. Its 1 MiB aggregate default
+aborts a legitimate turn: a synchronous producer fills the queue before its
+consumer is scheduled, and the image loop does exactly that with over a million
+one-character deltas that coalesce into roughly 1.2 MB of retained text. Its own CI
+proved it, which is why it sits at `CHANGES_REQUESTED`.
+
+The work is carried with attribution and reshaped around two budgets rather than
+one, because a stalled consumer and a malformed event are different failures and an
+operator reading the terminal error should learn which happened. Accounting is now
+exact by construction: each queued item records what it was charged, so a merge
+pays only for appended text, a refused event is priced before anything is retained
+and never charged, and the terminal record explaining a refusal is admitted past
+the budget it reports but still charged and released. `retainedCodeUnits()` exposes
+the counter so the regressions assert it reaches zero rather than inferring it from
+an abort that happened to fire.
+
+Retention is measured by a bounded walk of own enumerable properties rather than a
+per-variant table. A table would be exhaustive over `AdapterEvent`, which is the
+union class `AGENTS.md` records: a member added on another branch would silently
+stop being counted.
+
+### 12 — per-admission-key model and provider scope
+
+The security question is where the check goes, not what it compares. A scope
+evaluated against the client's string authorizes one destination and reaches
+another, because alias resolution, policy and combo selection, subagent fallback
+and compaction override all rewrite that string. So the scope names destinations
+and is applied to the resolved route.
+
+On the Responses path every route produced by the request — direct name, alias,
+policy, combo child, shadow-intercept target and both subagent-fallback re-routes —
+passes through one capture point, which is where the check sits. Chat and Messages
+translate into that path; their native lanes and the compaction route send without
+re-entering it, so each applies the same predicate itself. `/v1/models` filters by
+the same predicate, and that filter is explicitly not the boundary.
+
+A malformed scope drops the key rather than degrading to `undefined` like every
+other field on the record, because degrading a permission field reads as "allowed
+everything".
+
+Out of scope and deliberately not started: Redis, a full multi-tenant conversion,
+and any budget or RPM/TPM system.
+
+#### What the scope does not cover, stated rather than implied
+
+An adversarial review of the branch found authenticated data-plane endpoints that
+spend provider quota without resolving a model through the router, so the scope
+does not reach them:
+
+- `/v1/images/generations` and `/v1/images/edits`,
+- `/v1/audio/transcriptions` and its streaming form,
+- `/v1/live`, `/v1/realtime/calls` and the standalone realtime sockets,
+- the non-account-qualified branch of `/v1/alpha/search`, which forwards the caller's
+  model to a search sidecar without routing it.
+
+The account-qualified search branch does route a model and is checked. The rest
+need a destination definition this lane does not own — an image or audio endpoint
+has a fixed-purpose model rather than a routed one — and inventing one here would
+be the multi-tenant expansion this batch rules out. They are recorded so the
+contract is not read as broader than it is.
+
+The review also found that resolving an OpenAI virtual model rewrites
+`route.modelId` to the wire id after the initial check. That one was a real hole in
+the stated contract and is fixed: the settled route is re-checked after
+normalization, so the id that is billed is the id that was authorized.
+
+## Verification
+
+Static source review plus exact-head hosted CI. No local suite, individual test,
+typecheck, build, install or live `ocx` execution was run — those are NOT RUN, not
+passing.
+
+Union-defect classes checked before pushing. No file in the touched set carries a
+`file-size-baseline.json` cap; the largest, `src/oauth/index.ts` and
+`src/server/index/serve-options.ts`, stay under the 2000-line new-file threshold.
+The two new test files are registered in both `scripts/test-layout/layout.json` and
+`tests/fixtures/test-layout-expected.json`. Nothing here restates a count or
+enumerates a union.
+
+## Ownership
+
+Lane E owns the adapter event queue budget and the Devin and coding-agent limits.
+Retry classification — `sendCount`, the send budget, the stage and cause vocabulary —
+is lane C's and is untouched.
+
+## Carried work
+
+- #5182 (luvs01) — adapter event queue backlog budget.
+- #5189 (mdwsk88) — coding-agent projected-history ceiling.
+
+Both carry a `Co-authored-by` trailer in the branch commit. Neither original pull
+request is closed here; the coordinator handles that after this lane lands.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/060_lane_f.md b/devlog/_plan/260920_meaning_preservation_batch/060_lane_f.md
new file mode 100644
index 00000000000..e51bbedfc47
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/060_lane_f.md
@@ -0,0 +1,246 @@
+# Lane F — per-provider egress, and the CodeBuddy/native-wire disposition
+
+Status: OPEN. PR #5289 against `dev` at exact head `40fe2ee7d8`, hosted CI green across the
+whole matrix. One branch, ordered commits, one pull request. Covers phase 2 bundles 13 and 15
+from [010_phase2.md](010_phase2.md).
+
+Lane F was scheduled after lane B because bundle 13 consumes the request-scoped route decision
+that lane B built for #5087. That landed as #5264 (`8e1fdea1`), so this lane reads
+`effectiveProxyFor` as the authority for the global decision and does not restate it.
+
+## 13 — per-provider egress
+
+### What the bundle actually was
+
+Issue #2894 asks for two things and only one of them was missing. Global SOCKS5 already ships:
+`socks5ProxyFromEnv`, `socks5Fetch` and the `configureSocks5Fetch` wrapper handle it, and
+`applyProxyEnv` mirrors a configured value into `ALL_PROXY`. Rebuilding that was never in
+scope. What was missing is the two-level model: a per-provider override with direct / inherit /
+custom, so one upstream can exit through a regional proxy while another stays direct.
+
+### The decision function
+
+`src/lib/provider-egress.ts` resolves one route for one destination. It deliberately mirrors
+#5087's shape: the question is never "is a proxy configured" but "does a proxy apply to THIS
+request". Four states — inherit, direct, http(s) proxy, socks5 proxy — with
+`providers.<name>.noProxy` applied to whichever route resolved, which is what lets a provider
+exempt one destination from an inherited global proxy without owning a proxy of its own.
+
+Two divergences from the issue's sketch, both deliberate:
+
+- **An empty string is rejected, not read as DIRECT.** The issue lists `""` as a third spelling
+  of direct. A dashboard field the operator merely cleared would then silently switch a provider
+  from inheriting the global proxy to refusing it. The error names both real alternatives.
+- **A malformed value throws rather than degrading.** Falling back to the global proxy sends a
+  credential out a route nobody chose; falling back to direct leaves a restricted network with
+  no exit. Both read as success at the call site, which is the defect class this batch exists
+  to remove.
+
+### How direct egress is expressed, and why that needed settling
+
+This was the one genuine unknown. #3901 refused the direct state outright with the message
+"direct has no safe request-scoped transport on this runtime". That is correct about the
+mechanism it rejected and wrong as a general claim.
+
+Bun's documented `proxy: false` connects directly regardless of `HTTP_PROXY`, `HTTPS_PROXY`,
+`ALL_PROXY` **and** `NO_PROXY`. The same documentation states that `undefined`, `null` and
+`""` all mean "no option given" and fall through to the environment, so none of them can
+express direct egress — which is why the resolver emits the literal `false` and never an empty
+string.
+
+`configuredOutboundFetch` had to learn the same distinction. It derived its SOCKS route with
+`typeof explicitProxy === "string" ? … : socks5ProxyFromEnv()`, so a `false` fell into the
+environment branch and a request pinned to direct egress would have been sent through the global
+SOCKS proxy. It would have returned 200 by the wrong exit, which no status-code assertion can
+see. That is now a regression.
+
+One path needs nothing from the runtime at all: on `providerOutboundRequest`, direct egress is
+the DNS-pinned transport, which connects through `node:http` to an address this process
+resolved and never reads the proxy environment. Discovery and quota therefore have direct
+egress by construction rather than by flag.
+
+### Reach, stated as coverage rather than implied
+
+Honoured: the main inference dispatch (`providerFetch`), every
+`providerOutboundGet`/`providerOutboundPost` caller (provider discovery, the model-catalog
+gather, the management provider test, the Ollama show probe), and the seventeen API-key quota
+probes in `vendor-probes-key.ts`.
+
+Refused rather than dropped: a caller-supplied `provider.fetch` executor owns its own routing,
+so an explicit route throws instead of running the executor by a contradicting route. The
+WebSocket upstream picks its proxy from the process environment when it dials, so an explicit
+route serves those turns over HTTP/SSE and says so once per provider.
+
+**Not covered, and this is the honest limit of the change:** OAuth token exchange and refresh
+under `src/oauth/`, the OAuth-backed quota probes in `vendor-probes-oauth.ts`, and the API-key
+validation probes in `key-providers.ts`. All three reach fixed vendor endpoints from modules
+that hold no provider config, and `validateApiKey` receives a derived `KeyLoginProvider` whose
+caller builds the real provider record only afterwards. Threading provider config through those
+call sites is a caller-contract change across roughly a dozen OAuth modules and is not attempted
+here. The consequence is stated plainly in the provider guide and the transport inventory: a
+provider pinned to its own proxy or to direct still refreshes credentials by the process-wide
+route. #2894 therefore stays open for that half.
+
+Also uncovered and recorded: Cursor's default HTTP/2 transport, the coding-agent subprocess
+providers whose scoped child environment omits proxy variables, and the Compatibility Lab pinned
+sender.
+
+### Overlap with the #5049 router-bypass list
+
+Lane E recorded authenticated data-plane endpoints that spend provider quota without resolving a
+model through the router. Every one of them is also outside this lane's egress reach, for the
+same structural reason — no routed provider at the send — and the overlap is complete:
+`/v1/images/generations`, `/v1/images/edits`, `/v1/audio/transcriptions` and its streaming
+form, `/v1/live`, `/v1/realtime/calls`, the standalone realtime sockets, and the
+non-account-qualified branch of `/v1/alpha/search`.
+
+### Credential handling
+
+A proxy URL routinely embeds `user:password@`. `proxy` is classified credential-bearing
+alongside `apiKey`, so it never reaches the dashboard DTO and the editor may not write it;
+`ocx config set` and the config file remain the way to set it. Log output keeps scheme, host
+and port only. Nothing derived from the credential is emitted — the carried
+`providerEgressRouteKey` FNV-1a digest over the full proxy URL was dropped rather than carried,
+because a 32-bit digest over a known host is a guessable stand-in for the secret and a durable
+correlation key for the account behind it, and it had no consumer.
+
+### A finding recorded rather than acted on
+
+Bun's documentation states it uses `ALL_PROXY` for `http:` and `https:` alike when the
+scheme-specific variable is unset. `effectiveProxyFor` counts a non-SOCKS `ALL_PROXY` only for
+`http:` targets. The divergence fails toward keeping the DNS-pinned transport, which is the safe
+direction, and lane B reasoned about and tested that boundary explicitly. Changing it is lane
+B's surface, not this one, so it is recorded here rather than altered.
+
+### Carried work
+
+#3901 (jingzxy) — per-provider HTTP proxy overrides. Carried with a `Co-authored-by` trailer on
+both code commits. The branch was 289 `dev` commits behind and its `provider-outbound.ts` hunks
+were written against the pre-#5264 `outboundProxyConfigured` shape, so the work was carried onto
+the landed decision rather than replayed. Its management cases would also have pushed
+`tests/server/management-provider-validation.test.ts` from 5,498 to 5,612 lines against a 5,506
+cap; those cases live in a registered sibling file instead. The original pull request stays open
+for the coordinator.
+
+## 15 — CodeBuddy tool bridge and native wire: disposition
+
+Item 15 is delivered as a disposition, not an implementation. All three pull requests were
+audited against current `dev` and none is carryable as it stands. Recording why is the
+deliverable; carrying a defect with a `Co-authored-by` trailer on it would not be.
+
+No issue is closed by this lane. #5146, #5097 and #5096 stay open.
+
+### #5147 — account-roster discovery: blocked on an attribution defect
+
+The roster is read by running the vendor CLI, which answers for the account **signed in to that
+CLI's home directory**. The result is then cached under a fingerprint of the **configured API
+key**. Those are two different identities. The fingerprint isolates cache reuse between
+configured keys, which is what it was designed for, but it does not make the roster belong to
+the key it is filed under: with key B configured and account A signed in to the CLI, the proxy
+advertises A's models as B's catalog. That is the same class of defect bundle 8 is about — an
+observation outliving the identity it was made under — so carrying it into this batch would
+contradict the batch.
+
+The rest of the pull request reviewed clean: the key is passed by environment rather than argv,
+output is bounded at 512 KiB with an 8-second timeout, an explicit `liveModels: false` is
+preserved, and a missing CLI warns and degrades to the static seed rather than crashing. The
+defect is the binding, not the plumbing.
+
+### #5148 — capture-only tool bridge: conflicts, and coverage short of the bar
+
+The capture-only security boundary itself reviewed sound: the MCP server advertises and captures
+but never resolves a call, no path traversal or execution route was found, and no secret reaches
+the logs. The CLI does not execute tools and client approval is preserved.
+
+It does not apply to current `dev` — `src/adapters/coding-agent/turn.ts` conflicts and seven
+touched files drifted since its merge base. More important for this batch, its tests do not
+reach the acceptance bar set for item 15. Directly uncovered: a **successful** multi-call
+assistant message, call-ID preservation across the capture boundary, bridge-specific reasoning
+replay on the continuation turn, and an integrated abort that proves process-tree cleanup rather
+than orphaning a child. Those four are exactly the cases a "the first tool call worked" test
+cannot see, which is why they were named as the completion condition.
+
+Landing it would mean rebasing the adapter work and writing those four regressions. That is a
+lane of its own, not a trailing commit on this one.
+
+### #5188 — Alibaba Token Plan default flip: evidence does not support it
+
+#5198 already landed the opt-in and declined the flip, and added a guard that fails if a
+Responses wire default is declared for this entry without `preserveResponsesReasoningContent`
+beside it. #5188 proposes exactly that declaration without that flag.
+
+The guard is not bureaucratic. The entry sets `preserveReasoningContentModels`, which the
+**Chat** adapter reads; the Responses serializer reads a different flag this entry does not set,
+so pinned models would replay continuations with blanked reasoning content — strictly less state
+than they carry today. Z.AI and DeepSeek set both flags together and their entry comments say
+why.
+
+The live evidence in #5097 covers a tool call and a continuation that replays
+`custom_tool_call` and `custom_tool_call_output`. It does not assert that reasoning content
+survived that continuation, which is the one thing the flip would change. The delegation's own
+constraint applies: do not change inbound behaviour or international endpoints without evidence.
+The opt-in stands; the flip waits for a replay that demonstrates reasoning preservation.
+
+## Verification
+
+Static source review plus exact-head hosted CI. No local suite, individual test, typecheck,
+build, install, live `ocx` execution or service restart was run — those are **NOT RUN**, not
+passing.
+
+Hosted CI at `40fe2ee7d8` is green: all four test shards, both macOS halves, `gates`
+(typecheck, GUI tests, privacy scan, generated skill surface), the structure gate, docker smoke,
+storage policy, api usage, the three `npm-global` smokes and the three keyring jobs.
+
+### What only CI could tell me, and what only review could
+
+Three defects reached a pushed head and were caught by adversarial review before CI ran, all in
+the same seam and all invisible to a status-code assertion:
+
+1. The route was resolved when the fetch wrapper was built, but `dispatchOverride` can rebuild a
+   queued request against a different upstream host. A host-scoped `noProxy` decision could
+   therefore be applied to a host it was not decided for, sending a bearer out an excluded route.
+   The decision moved to `sendWithConnectionPolicy` — the same boundary and the same reason
+   #4992 records for the connection policy.
+2. Refusing every `provider.fetch` as transport-owning was too broad. The xAI route installs a
+   wrapper on every request that only adds a generated request id, so an explicit route would
+   have thrown for one of the two providers #2894 names.
+3. The executor handed to an override was itself unmarked, so an ordinary provider would have
+   been refused on every overridden path — after the attempt had already been recorded. None of
+   the regressions written to that point covered the production-shaped nested send; two do now.
+
+CI then found two more that review had cleared. The zod field schemas used
+`z.unknown().superRefine(...)` without narrowing, so the parsed provider record carried
+`proxy: unknown` and failed to satisfy `OcxProviderConfig` — four typecheck errors, and a
+typecheck-based adapter contract test that asserts zero errors reported one. And the privacy
+scan reads a URL userinfo pair as an address, so the fixtures that deliberately carry a
+credential to prove it never reaches a log were read as one. They moved to the `.test` host the
+scanner already allows for fixtures, with the assertions unchanged. Both are the reason this
+lane treats hosted CI as the verification and static review as the preparation for it, rather
+than the reverse — and the second one repeated itself in this very document, which first
+described the defect by quoting the shape that caused it.
+
+Union-defect sweep before pushing:
+
+- **File-size ratchet.** No touched source file carries a cap.
+  `tests/server/management-provider-validation.test.ts` does (5,506) and is deliberately not
+  touched; the management egress cases are a registered sibling file.
+- **Exhaustive over a union.** Adding `proxy` and `noProxy` to `OcxProviderConfig` makes
+  `PROVIDER_CONFIG_FIELD_POLICY` — declared `satisfies Record<keyof OcxProviderConfig, …>` —
+  fail to compile until both are classified. Both are, and the classification is asserted rather
+  than assumed.
+- **Derived, not restated.** The tests import `PROVIDER_EGRESS_DIRECT`,
+  `MIN_BOUNDED_CODEX_WS_BUN_VERSION` and `CODEX_RESPONSES_HTTP_URL` from source instead of
+  repeating their values, and configuration validation calls the resolver instead of restating
+  what a valid proxy value is. No count in generated documentation was touched.
+- **Test layout.** Four new test files, each registered in both `scripts/test-layout/layout.json`
+  and `tests/fixtures/test-layout-expected.json`.
+- **Exact-list guards.** `tests/responses/responses-fetch-helpers-boundary.test.ts` pins the
+  runtime-import list of `fetch-helpers.ts` and needed the two modules this lane adds. It is the
+  restatement class in miniature, and it is the guard working as intended: the list is a
+  deliberate classification, so adding to it is a reviewed decision rather than a silent one.
+
+## Ownership
+
+Consumed and not redefined: lane C's send accounting, lane E's adapter event queue budget and
+per-key model/provider scope (`src/server/admission-model-scope.ts`), and lane D's per-model
+cache views. The `effectiveProxyFor` global decision belongs to lane B and is read, not changed.
diff --git a/devlog/_plan/260920_meaning_preservation_batch/060_lane_i.md b/devlog/_plan/260920_meaning_preservation_batch/060_lane_i.md
new file mode 100644
index 00000000000..bef4c28b42a
--- /dev/null
+++ b/devlog/_plan/260920_meaning_preservation_batch/060_lane_i.md
@@ -0,0 +1,112 @@
+# Lane I — per-key scope on the unrouted data planes
+
+Status: OPEN. Branch `codex/260920-lane-i-key-scope-dataplane` against `dev`, one pull request,
+ordered commits. Base is `origin/dev` at `043aa435ff`.
+
+Scope is one thing: the part of #5049 that #5265 (`447ac22ca6`) could not reach. That change put
+the model and provider scope on the resolved route, at the single capture point every Responses
+destination passes through, and Chat and Messages inherit it by translating into that path. Four
+authenticated endpoints spend provider quota without ever resolving a model through the router, so
+the predicate never saw them.
+
+## What each surface turned out to be
+
+### Images
+
+`handleImages` can settle on four different destinations, and only two of them use the model the
+caller sent. The ChatGPT forward account and a keyed OpenAI provider relay the body verbatim; the
+xAI Imagine bridge always runs `images.bridgeModel` on the configured xAI provider; the Antigravity
+fallback always runs its own CCA image model. Judging the body would therefore have authorized one
+thing and billed another on two of the four branches, which is the failure the landed design names.
+
+Each branch is checked as it is entered — the bridge and the Antigravity fallback before they
+resolve a credential, the two relays before the forward probe lease is consumed or the keyed picker
+commits a rotation. A refused request spends nothing and mutates nothing.
+
+### Audio and voice
+
+Transcription, the dictation socket, external voice call-create and the external sideband join all
+resolve through `resolveAudioUpstream`, which already receives both the admission and the model the
+upstream will run. One check on each of its two return paths covers all four endpoints. The forward
+path releases its probe lease on refusal, mirroring the adjacent unusable-account branch.
+
+The native `/v1/live` and `/v1/realtime/calls` path does not share that resolver, so it needed its
+own: `resolveLiveRelay` now takes the destination it is resolving for. The model is read where the
+client states it — `session.model` in a JSON or multipart call-create, the `model` parameter of a
+standalone socket query — and a join onto an existing call carries the default, because the call it
+attaches to stated its model when it was created.
+
+### Search
+
+The brief expected the non-account-qualified branch to hand the caller's model to the sidecar. It
+does not, and the distinction matters for where the check belongs. There are two unrouted branches,
+not one:
+
+- the forward relay copies the caller's model to whichever ChatGPT account the upstream resolved,
+  and that account is billed for it;
+- the sidecar fallback ignores the caller's model entirely and runs the backend and model the
+  operator configured, spending that backend's own credential.
+
+Both are destinations a scoped key must not reach, so both are checked — the first against the
+resolved account and the caller's model, the second against the configured backend and the model
+that backend runs. Exa has no provider entry, so its backend name is its destination. The
+account-qualified branch keeps the single check #5265 gave it and is not judged twice.
+
+## Rules that fell out of the review
+
+A request that names no model has no destination a model list can allow: the relay would copy the
+body and let the upstream pick. `UNNAMED_DESTINATION_MODEL` makes that explicit, so a key scoped by
+model is refused rather than sent to a provider default. A key scoped only by provider is
+unaffected, and a key with no scope at all reaches every surface exactly as before.
+
+No new policy system was introduced. `admissionScopeDenial` is a three-line composition of the
+landed `resolveAdmissionModelScope`, `routeAllowedByScope` and `admissionModelDeniedResponse`,
+shaped for handlers that return a `Response` rather than throwing into a route resolver. Every
+refusal is the same 403 naming the caller's own selector, with the resolved destination left to the
+server log.
+
+## Explicitly out of scope
+
+Redis, multi-tenancy, budgets and RPM/TPM ceilings. Nothing here reads or writes a credential, and
+no new field is logged: a refusal carries the selector the caller already knows and no account
+identifier, provider credential or request body.
+
+## Verification
+
+Static review against the `dev` source plus exact-head hosted CI. Per the lane instruction the
+local suite, focused test files, `typecheck`, `build`, `install` and any running `ocx` were NOT
+RUN; the file-size ratchet and the union-exhaustiveness classes were checked by reading the
+baseline and the changed files instead. No touched file carries a baseline cap, and the largest,
+`src/server/index/serve-options.ts`, stays well under the 2000-line threshold. The four new test
+files are registered in both `scripts/test-layout/layout.json` and
+`tests/fixtures/test-layout-expected.json`.
+
+## Remaining scope on #5049
+
+The issue stays open for the coordinator to judge. This lane closes the four endpoints named in the
+#5265 adversarial review and nothing beyond them.
+
+## What the first review round changed
+
+Three findings on PR #5290, all of them about a destination the first pass was willing to assume.
+
+The refusal marker was being used as a model id. A request that named no model was checked as the
+literal `(unnamed)`, which the configuration schema accepts like any other string, so an operator
+who copied it out of a refusal into `allowedModels` would have granted "whatever the upstream
+picks". The absent model is now absent: the denial helper takes an undefined model id and refuses
+any key carrying a model list, judging a provider-only scope on the provider alone. The marker is
+message vocabulary and never reaches the comparison.
+
+A Realtime standalone socket was judged as the default. The external audio path read the `model=`
+query only for the Frameless style — the one that rewrites its own query — while a
+`realtime-standalone` socket forwards that parameter untouched. Both standalone styles now report
+the model they forward, through the helper the native path already used.
+
+A join was authorized against an assumed model, and what to do about it depends on what each path
+can know. The external path keeps a per-key call registry, so the model a call settles on is now
+recorded in its `LiveCallBinding` and a rejoin is judged against it. The native compatibility path
+records nothing about the calls it relays and does not gain a registry here — adding call ownership
+to it is a different change from closing a scope hole — so a native join, and a native call-create
+that sends no session model, name no destination and a key carrying a model list is refused. That
+is a real restriction on model-scoped keys and it is written down beside the contract it
+constrains, in `structure/data-planes/inbound-compat.md`, rather than left to be rediscovered.
diff --git a/devlog/_plan/260920_regression_release/010_execution.md b/devlog/_plan/260920_regression_release/010_execution.md
new file mode 100644
index 00000000000..39b8ca8e61c
--- /dev/null
+++ b/devlog/_plan/260920_regression_release/010_execution.md
@@ -0,0 +1,90 @@
+# 2.60.0 regression and release execution
+
+Status: IN PROGRESS. This file records what was actually executed, with exact commits, runs and
+dispositions. It is not a completion claim beyond the evidence listed here.
+
+## Candidate freeze
+
+| Branch | Before | After |
+| --- | --- | --- |
+| dev | `12cb129d424d1a67319c1e7a761ba5474fdc48a4` | `1b57a572182d9f6f76cb6169eec7b65495be5910` (2.61.0) |
+| main | `134c92a01b120162f00c7275189cc47858720379` (2.59.0) | `7c625fc9755c9824653ab944190e243091a2c85c` (2.60.0) |
+| preview | `48e1ddba0bb8da9ad39e32f8e20c1e4d7f1794da` (2.58.0) | `84c4f014c8da51ff50c3e8b64f2d82b9ee3792da` (2.60.0) |
+
+The released tree is `015c67c46aaf16d4319543c8941c6dbec9887ae6`, the `dev` head after the last
+blocking repair and before the version pre-move.
+
+## Dev-tip regression failure and repair
+
+Run `35485314835` at `12cb129d42` failed on Linux `test 2/4` and macOS `macos 2/2` with the same
+single case, `sanitizeEncryptedContentInPlace > plaintext parked in encrypted slots becomes
+input_text; real blobs survive`, reporting `Expected: 2, Received: 3` at
+`tests/codex-integration/multi-agent-compat.test.ts:1392`. Every other producer and both keyring
+and docker legs passed, so the aggregate `ci` check failed on that one assertion.
+
+This is the merge-union class `AGENTS.md` describes. #5239 replaced `looksLikeBackendCiphertext`
+with `isStructurallyValidFernetToken`, which requires canonical base64url, length at least 100, a
+`0x80` version byte and a 16-byte-aligned ciphertext. The case predates that change and minted its
+surviving blob as `"gAAAAAB".padEnd(120, "Qw1_-=")`, which embeds `=` mid-token and is therefore no
+longer a valid token, so the sanitizer correctly lowered it as a third rewrite. #5239's own tests
+were updated; this one in another domain directory was not.
+
+#5246 mints the blob with the `fernetFixture()` helper already defined in the same `describe` —
+a 73-byte payload with `raw[0] = 0x80` encoding to a 100-character canonical token, giving
+`decoded.length - 57 === 16`. The classifier is untouched, the rewrite count returns to 2 and the
+surviving slot stays byte-identical. Merged to `dev` as `015c67c46aaf16d4319543c8941c6dbec9887ae6`.
+
+## Integration sequence
+
+1. #5242 archived the campaign unit to `_fin`; merged as `d3d637912ab5080e0d54ef60db273951746d0aa9`.
+2. #5246 repaired the fixture; merged as `015c67c46aaf16d4319543c8941c6dbec9887ae6`.
+3. `release/2.60.0` was cut at that head, before any version move.
+4. `dev-version-bump.yml` was dispatched with `intended-version=2.60.0`. The first dispatch from
+   `dev` was refused by the workflow's default-ref guard; the dispatch from `main`
+   (`35486732967`) opened #5247, merged as `1b57a572182d9f6f76cb6169eec7b65495be5910`, so `dev`
+   outranks the release at 2.61.0.
+5. #5249 promoted `release/2.60.0` to `main` as merge commit `7c625fc9755c9824653ab944190e243091a2c85c`.
+6. #5250 brought `preview` onto the same tree as `84c4f014c8da51ff50c3e8b64f2d82b9ee3792da`;
+   `git diff` against `main` was empty before the merge and after it.
+
+The maintainer directed admin integration without waiting for per-pull-request CI on the repair and
+promotion pull requests. That timing direction is recorded here rather than presented as a
+completed per-PR pass.
+
+## Publication gates and full regression evidence
+
+`release.yml` refuses to publish without a successful push-event `ci.yml` run for the exact release
+commit; a pull-request run does not qualify. The first dispatch (`35486936693`) failed on that gate
+while the `main` push run was still queued. `service-lifecycle.yml` was already satisfied for the
+same commit by run `35486928648`.
+
+The full regression from the request-time `main` baseline through the released candidate is push
+run `35486928618` at `7c625fc9755c9824653ab944190e243091a2c85c`, conclusion SUCCESS. Every
+event-requested producer passed: `changes`, all four Linux `test` shards, both macOS shards,
+`storage policy`, `api usage`, `gates`, `structure gate`, `docker smoke`, `docs site build`, all
+three `keyring` legs and all three `npm-global` legs. The nine-shard Windows matrix and
+`macos control` are workflow-dispatch lanes that this event does not request, so their skipped
+placeholders are applicability, not execution.
+
+## Publication
+
+Release run `35488151017` at the same commit completed SUCCESS with every step green, including
+`Require successful Cross-platform CI for this commit`, `Require dev to be ready for this release`,
+`Refuse a release the current tag set already outranks` and `Publish (or dry-run)` with
+`dry-run=false`.
+
+npm accepted `+ @bitkyc08/opencodex@2.60.0` on dist-tag `latest` with public access and a signed
+provenance statement recorded in the sigstore transparency log at index `2894025266`. Tarball
+`bitkyc08-opencodex-2.60.0.tgz`, shasum `651613e7536c33be936ac387a0a9f38ff290c4cc`, 1436 files.
+
+Tag `v2.60.0` points at `7c625fc9755c9824653ab944190e243091a2c85c` and the GitHub release was
+published at 2026-09-20T04:05:15Z, not a draft and not a prerelease.
+
+Registry propagation was still pending at the time of writing: npm reported "Your package is being
+processed and may take a few minutes to become available", the workflow's bounded six-attempt smoke
+ended `verification=pending`, and direct reads of
+`https://registry.npmjs.org/@bitkyc08%2fopencodex` still showed `latest` at 2.59.0 about fifteen
+minutes after publication. The publish itself is acknowledged and must not be republished; the
+remaining check is a later registry read confirming `2.60.0` under `latest`.
+
+Local suites, typecheck, builds, installs and runtime execution were not run in this lane.
diff --git a/devlog/_plan/260920_round2_followups/000_plan.md b/devlog/_plan/260920_round2_followups/000_plan.md
new file mode 100644
index 00000000000..bc113d7d542
--- /dev/null
+++ b/devlog/_plan/260920_round2_followups/000_plan.md
@@ -0,0 +1,69 @@
+# Round 2 — what the first batch left behind
+
+Status: OPEN. The sixteen post-2.60.0 bundles and the #5261 incident work all landed on `dev`
+today. This unit collects what that round deliberately left open, plus two things it caused.
+
+Everything here is either a defect a user hit, a remainder a lane recorded rather than hid, or a
+red check on `dev`. Nothing is new scope invented for its own sake.
+
+## Priority 1 — a 2.60.0 regression that locks users out of the transition
+
+#5321: on a Codex home whose history has been migrated to paginated form, enabling the integration
+in its authless provider-table shape is hard-refused with
+`history_paginated_openai_requires_native_writer`. Nothing is written and the integration stays
+disabled. Before 2.60.0 the same transition completed, with the history relabel standing down while
+the routing and catalog half was still written.
+
+The guard itself is right. `src/codex/history-provider.ts` explains why: a provider-table
+transition removes the root `openai_base_url`, and a row already paginated cannot be relabeled, so
+standing it down would route an openai-tagged thread to Codex's own OpenAI endpoint. Refusing to
+relabel is correct; refusing the entire transition and saying "do not retry" without naming a way
+forward is what traps the user.
+
+The reporter found the only exits by reading the preflight source: delete the affected
+conversations, or downgrade. On their home that meant deleting 173 sessions. Neither is a
+remediation this project can ship as the supported answer.
+
+#4812 is the same guard family from the other side: `restore`, `stop` and `uninstall` also refuse
+on paginated history, which leaves the CLI pointed at a dead proxy port. The two belong in one lane
+because a fix that unblocks activation while leaving recovery blocked trades one trap for another.
+
+## Priority 2 — `dev` is red from the desktop landing
+
+The app stack brought a `macos widget + bundle` job. MenuBarCore's 118 tests, the dashboard build,
+the sidecar preparation and the WidgetKit appex build all pass; `tauri build` then fails with
+`A public key has been found, but no private key`. The updater public key is committed while the
+private key is not a CI secret, so Tauri refuses to produce a signed update artifact.
+
+This is configuration, not code. The CI job's purpose is to prove the appex and the app bundle
+build and that the widget is embedded, which does not require a signed updater artifact. Release
+signing belongs to the release workflow, where the key can be held as a secret.
+
+## Remainders the first round recorded rather than hid
+
+| Item | What is left |
+| --- | --- |
+| #5292 | `gui/src/pages/Logs.tsx` restates the recovery-kind union with nine of thirteen members, so four durable kinds have no label. The fix derives the GUI union from the roster instead of restating it. |
+| #5261 | Generic OAuth and key login still discard the browser launch result, and the dashboard account roster keeps last-good rows after a failed refresh. |
+| #4191 | The WebSocket failure projection is not threaded into the durable record, and the SSE fallback the issue asks for is a transport change. |
+| #5180 | The shared cooldown and `Retry-After` handling are routing behaviour and were not in the stage-table branch. |
+| #4942 + #4989 | Both express rows of the landed stage table and overlap in `upstream-retry.ts` and `passthrough-dispatch.ts`. They must not each buy an independent replacement send for one logical request, so they are one reworked change. |
+| #2366, #3748, #3983, #5063 | Deferred as implemented because each adds a parallel store or a second emission path. The derived forms read from the landed recorder instead. |
+
+## Lanes
+
+| Lane | Scope |
+| --- | --- |
+| R1 | #5321 and #4812 — the paginated-history guard, from both activation and recovery |
+| R2 | the `macos widget + bundle` failure on `dev` |
+| R3 | #5292 and the two #5261 remainders |
+| R4 | #4942 and #4989 as one rework, plus the #4191 and #5180 remainders |
+| R5 | the four telemetry pull requests as derived consumers of the recorder |
+
+## Execution constraints
+
+Unchanged. One branch, ordered commits, one pull request to `dev` per lane. No native stack — the
+desktop chain proved why: squashing the bottom of one detaches every child and the remaining work
+has to be reconstructed. Carried contributor work needs a `Co-authored-by` trailer. No local
+suites, typecheck, builds, installs or live `ocx` execution; verification is static review plus
+exact-head hosted CI. Only the coordinator merges and closes.
diff --git a/devlog/_plan/260920_round2_followups/010_r1_paginated_history_guard.md b/devlog/_plan/260920_round2_followups/010_r1_paginated_history_guard.md
new file mode 100644
index 00000000000..a3db4957992
--- /dev/null
+++ b/devlog/_plan/260920_round2_followups/010_r1_paginated_history_guard.md
@@ -0,0 +1,91 @@
+# R1 — the paginated-history guard, from activation and from recovery
+
+Scope: #5321 (activation) and #4812 (recovery). Branch `codex/260920-r1-paginated-history-guard`.
+
+## What the guard was actually protecting
+
+`preflightCodexHistoryInjection` returns `history_paginated_openai_requires_native_writer` when a
+provider-table transition finds a thread row that is both `model_provider = 'openai'` and
+`history_mode = 'paginated'`. The reasoning is sound. The transition takes the root
+`openai_base_url` out, a paginated row cannot be relabeled, and Codex builds its provider map as
+`merge_configured_model_providers(built_in_model_providers(openai_base_url), model_providers)`, so
+without that root line the built-in `openai` entry is `api.openai.com`. The conversation would
+resume outside the proxy.
+
+What made it a lockout is that 2.60.0 classified it alongside "something is wrong with this
+store". `src/codex/inject.ts` refuses every reason that is not exactly `HISTORY_RELABEL_STANDS_DOWN`,
+so nothing was written at all: no config, no profile, no `model_catalog_json`, integration
+disabled. Before 2.60.0 the same home returned the plain stand-down, and the routing and catalog
+half landed while the relabel stood down.
+
+## The state that was already in the tree
+
+The injector already builds the safe state for one routing form. `keepRootOverrideAlongsideTable`
+keeps the marker-owned root override beside the provider table for client compaction, for exactly
+this reason, and passes `resumeHistory: false` so the relabel never runs. Authless was excluded
+deliberately — its point is `requires_openai_auth = false` — on the assumption that it could
+always forward-tag resume history instead. On a paginated home that assumption is false, and the
+refusal is where that showed up.
+
+So the fix is not a new mechanism. `src/codex/inject/paginated-openai-compat.ts` selects the
+existing one from the preflight verdict rather than from the routing form: when the reason is the
+paginated-openai code and the target can own a root key, retain the override, downgrade the reason
+to the stand-down constant, and let the transition complete. The paginated row is never read or
+written; it simply keeps resolving to this proxy.
+
+Two cases cannot reach that state, and both are honest outcomes rather than traps:
+
+- An admission-token form cannot use the root key at all, because Codex's built-in `openai` entry
+  carries no `x-opencodex-api-key` header. It keeps the refusal, and the message now names
+  `unauthenticatedLoopbackListener` and `syncResumeHistory` instead of "do not retry".
+- A root line the user owns is left alone. The conversation follows the destination they chose,
+  which is the guarantee the injector already makes everywhere else about a line it does not own,
+  and the journal correctly records the line as not ours.
+
+## Where it had to live
+
+`src/codex/inject.ts` was at 984 of its 987-line ratchet cap, so the decision could not be
+inlined. The new module costs the injector one import and one net line; the file now sits at
+exactly 987. The refusal code became an exported constant in `src/codex/history-provider.ts`
+because the same literal in two files is how the stand-down pair drifted the first time.
+
+## #4812, checked rather than assumed
+
+The recovery half is already closed on `dev`: `resolveRestoreHistoryDisposition` stands down on
+`HISTORY_RELABEL_STANDS_DOWN` and removal retains the provider table. The new code cannot reach
+restore at all — it is only set under `providerTableMode`, and restore preflights with
+`providerTableMode = false`, whose row predicate is `model_provider = 'opencodex'`.
+
+Two things were still wrong on that side. `ocx restore --remove-codex-provider-table` existed but
+appeared in no usage or help text, so the escape hatch was reachable only by reading the parser;
+it is now in the command registry and top-level usage, bound by a test that reads the flag out of
+`dispatch.ts` rather than restating it. And the public guide in all eight locales still said
+restore and removal refuse on paginated history and that such a home cannot be uninstalled, which
+has not been true since 2026-09-17.
+
+## Verification
+
+Static review plus exact-head hosted CI. Per the lane constraints, NOT RUN locally: `bun test`,
+any individual test file, `bun run typecheck`, any build, any install, live `ocx`, service
+restart, and credential or configuration changes.
+
+Regression coverage added:
+
+- `tests/codex-integration/history-paginated-openai-compat.test.ts` — the resolver itself: root
+  override retained and placed before the first table, CRLF preserved, a user-owned line left
+  untouched and not claimed, the admission-token refusal naming both remedies as keys that are
+  asserted to exist in `src/types/config.ts`, every other reason passing through unchanged, and a
+  source-oracle check that the refusal code is defined once.
+- `tests/codex-integration/codex-inject-integration.test.ts` — the end-to-end regression, rewritten
+  from "refuses" to the full transition: config carries both the table and the marker-owned root
+  override, the rollout bytes and the thread row are unchanged, and `ocx restore` afterwards takes
+  the retained override back out. That last assertion is the one that keeps this from trading
+  #5321 for a new #4812.
+- `tests/cli/cli-restore-back.test.ts` — the removal flag is discoverable in both help surfaces.
+
+## Not in this lane
+
+The other hard-refusal reasons on the recovery side still have no named repair command: a missing
+state database with pending manifest entries, and a backup manifest that is unreadable, foreign,
+or schema-invalid. Those are a different failure family from the guard and are left open rather
+than folded in here.
diff --git a/devlog/_plan/260920_round2_followups/020_r2_desktop_ci.md b/devlog/_plan/260920_round2_followups/020_r2_desktop_ci.md
new file mode 100644
index 00000000000..47c658ef83e
--- /dev/null
+++ b/devlog/_plan/260920_round2_followups/020_r2_desktop_ci.md
@@ -0,0 +1,54 @@
+# R2 — the `macos widget + bundle` failure on `dev`
+
+Status: the job had two independent defects stacked on top of each other. The second was
+invisible until the first was fixed, because it lived in a step that had never once executed.
+
+## First layer: the verification build demanded the release key
+
+`bundle.createUpdaterArtifacts` is on and the updater public key is committed, so `tauri build`
+concluded it had to emit a signed update artifact and stopped with `A public key has been found,
+but no private key`. On macOS this bites even with `--bundles app`, because the macOS updater
+artifact is derived from the `.app` itself.
+
+#5338 scoped the opt-out to the verification build with a `--config` override and left
+`tauri.conf.json` alone, so release signing stays in `release.yml` where the secret lives.
+`BundleConfig` carries `deny_unknown_fields`, so a misspelled override key fails the build
+rather than silently reverting to signing — the override cannot rot into a no-op.
+
+## Second layer: the Verify step asserted a filename that never existed
+
+With the build green the Verify step ran for the first time and failed on its first line,
+`test -x "$app/Contents/MacOS/OpenCodex"`, printing nothing because `test` is silent.
+
+Tauri renames the main binary only when `mainBinaryName` is set (`tauri-cli`
+`src/interface/mod.rs`, with `rename_app` in `src/interface/rust/desktop.rs` a no-op
+otherwise). This config does not set it, so the bundled executable keeps the Cargo bin name
+`opencodex-desktop`. The job log had said so all along: `Built application at:
+.../target/release/opencodex-desktop`.
+
+The fix reads `CFBundleExecutable` from the bundle's own `Info.plist`. `tauri-bundler`
+`create_info_plist` writes that key from the same `main_binary_name()` that
+`copy_binaries_to_bundle` uses for the filename, so the plist and the file on disk cannot
+disagree. An empty value is rejected so a missing key cannot pass by testing the `MacOS`
+directory.
+
+The other three assertions were checked against the same source and were already correct:
+`Settings::copy_binaries` strips the `-<target>` suffix so the sidecar lands as
+`Contents/MacOS/ocx`, and `copy_custom_files_to_bundle` resolves `bundle.macOS.files`
+relative to `Contents` and errors when the source is missing, so the appex is present with its
+executable bit intact.
+
+## What this leaves open
+
+CI no longer exercises updater bundling at all. A regression there surfaces only during a
+release. Two release-time backstops contain it — `collect-release-assets.ts` throws when the
+macOS `app.tar.gz` is missing, and `updater-manifest.ts --require-all` refuses a partially
+signed `latest.json` — and both are covered by `tests/ci-workflows/release-desktop-scripts.test.ts`.
+What nothing covers is `tauri.conf.json` itself: no test reads it, so flipping
+`createUpdaterArtifacts` off or mangling the `plugins.updater` block stays green everywhere
+until a release runs. A static contract test over that file is the cheap follow-up.
+
+The macOS updater filename is also restated by hand in four places —
+`collect-release-assets.ts`, `updater-manifest.ts`, the `release.yml` matrix, and
+`structure/desktop-shell.md` — with nothing deriving one from another. The same contract test
+should tie them together.
diff --git a/devlog/_plan/260920_round2_followups/030_lane_r3.md b/devlog/_plan/260920_round2_followups/030_lane_r3.md
new file mode 100644
index 00000000000..d38a851a40f
--- /dev/null
+++ b/devlog/_plan/260920_round2_followups/030_lane_r3.md
@@ -0,0 +1,90 @@
+# R3 — the roster and login remainders
+
+Status: implemented, awaiting review. Scope was #5292 and the two #5261 remainders.
+
+## #5292 was already closed before this lane opened
+
+The plan's table says `gui/src/pages/Logs.tsx` restates the recovery-kind union with nine of
+thirteen members. That was true when the table was written and stopped being true two hours
+earlier: `555f0cacdf` (#5300, 18:41) replaced the copy with the durable roster, and the plan
+commit landed at 20:48 from a snapshot taken before it.
+
+Current `dev` already has all of it. `Logs.tsx` imports `AttemptRecoveryKind` from
+`src/usage/telemetry-contract.ts` and its label map closes with
+`satisfies Record<AttemptRecoveryKind, string>`, so a fourteenth kind is a typecheck failure
+there rather than an "Unknown recovery reason". All ten catalogs carry all thirteen labels plus
+the fallback, and `tests/usage/request-outcome-agreement.test.ts` holds both: the label map has
+to cover every member of `ATTEMPT_RECOVERY_KIND_ROSTER`, and every key it names has to exist in
+every catalog. Verified by reading the tree, not by rerunning the suite.
+
+Nothing was changed for it. The row is stale, not open.
+
+## #5261, remainder one: the two CLI logins that discarded the launch
+
+`src/oauth/login-cli.ts` called `void openUrl(...)` in both `handleOAuthLogin` and
+`handleKeyLogin`. Each printed a URL, said it was opening a browser, and asked a question that
+assumes it opened — indistinguishable from a login that is working.
+
+The part that made this more than a missing `console.warn`: `OAuthController.onAuth` returns
+`void` and every one of the thirteen provider call sites invokes it as `ctrl.onAuth?.(...)` and
+moves on. The launcher's answer therefore arrives after the flow has continued, and on a
+callback-server provider `#waitForCallback` has already called `onManualCodeInput` by then. A
+warning written at that moment lands on the line the user is typing on.
+
+Making `onAuth` awaitable would mean changing the controller contract and all thirteen call
+sites, which is a much larger change than the defect deserves. Instead the launch reports itself
+when it settles, and the two things that could collide with it wait on that report: the
+manual-code prompt awaits it before asking, and the key login awaits it before it constructs a
+reader at all. A polling provider that never prompts is still told before the login claims to
+have worked.
+
+`BROWSER_LAUNCH_FAILED_HINT` in `src/cli/account-auth.ts` kept its ChatGPT-specific second line
+and now derives its first from `BROWSER_LAUNCH_FAILED_NOTICE`, so the sentence has one home
+across all three logins.
+
+The handlers took an optional deps object. The contract worth holding is an order, and an order
+is only observable from something that records both events; spawning a launcher and attaching to
+stdin to find that out would test the operating system. Production passes none of them.
+
+## #5261, remainder two: the roster that kept last-good rows silently
+
+`useCodexAccountPool` kept its rows after a failed read and also kept reporting `ready`. Keeping
+the rows is right — blanking a populated pool because one 30s poll missed is its own defect — but
+the surface then could not tell a list the server had just confirmed from one that predated a
+failure. The reported shape: add an account, the read that would bring it over fails, and the
+older accounts are on screen with the new one absent.
+
+`refreshFailed` sits beside `loadState` rather than inside it, for the same reason `refreshing`
+already does. `loadState` answers what the surface can draw and a warm failure does not change
+that answer; folding it in would mean either flashing the cold skeleton over good data or saying
+nothing. A cold failure still replaces the surface with the error it already had, and the banner
+only renders when rows survived, so an empty cold failure is never annotated instead of explained.
+
+## Verification
+
+Static review and hosted CI at the exact head. The lane ran no local suite, no individual test,
+no typecheck, no build, no install, no `ocx`, and changed no credential or configuration —
+recorded as NOT RUN.
+
+Checked by reading rather than running, because the ratchets are what a merge breaks:
+
+- No file this lane touches appears in `tests/fixtures/file-size-baseline.json`. The ten i18n
+  catalogs are in its `exempt` list.
+- `tests/oauth/oauth-login-cli-browser-launch.test.ts` is registered in both
+  `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`. The gui
+  suite has no layout guard.
+- The one new i18n key is in all ten catalogs, which `gui/tests/locale-parity.test.ts` and
+  `gui/tests/claude-desktop-locale.test.ts` both require.
+- `CodexAccountLoadState` gained no member. `CodexAccountPoolController` gained one, and the
+  source-oracle roster in `gui/tests/codex-account-pool-controller.test.ts` names it.
+- `CodexAccountPoolLoadStates` stopped restating the load-state union and derives it.
+
+## The GUI screenshot gate
+
+`enforce-target` requires a screenshot for a PR that touches `gui`. Producing one needs
+`bun run build:gui` and a running proxy, both of which this lane is forbidden to do, so the pull
+request says so and offers what can be checked instead: the rendered markup is asserted against a
+mounted DOM in `gui/tests/codex-account-pool-stale-refresh.test.tsx` — the banner appears with
+surviving rows, carries the catalog string, does not appear on a successful refresh, and does not
+replace the cold error — and the new class reuses the existing `.pwi-auth-state` block with the
+`--amber` pair already used elsewhere in the theme.
diff --git a/devlog/_plan/260920_round2_followups/040_r4_retry_rework.md b/devlog/_plan/260920_round2_followups/040_r4_retry_rework.md
new file mode 100644
index 00000000000..6022b10626a
--- /dev/null
+++ b/devlog/_plan/260920_round2_followups/040_r4_retry_rework.md
@@ -0,0 +1,53 @@
+# R4 — #4942 and #4989 as one ambiguous-resend gate
+
+Status: OPEN. Branch `codex/260920-r4-retry-rework`, cut from `origin/dev` at `d6d87440b7`.
+
+## Why the two pull requests are one change
+
+#4942 (FredAmartey) replays a native Responses send whose connection died before any response
+head, behind a per-provider opt-in. #4989 (lidge-jun) replaces a native Responses SSE stream that
+died after the head while the body had carried only control events. Written apart they read as two
+features. Against the stage table #5266 landed in `src/lib/request-failure-model.ts` they are one
+row: a stage whose `stageCommitment` is `nothing-observed`, with a cause whose
+`causeEvidence` is `unknown`. `resendPermission` answers `refused-ambiguous` for both, and
+the module already names the only thing that may override it — "a narrowly scoped, explicitly
+opted-in recovery that a maintainer reasoned about and bounded".
+
+Two overrides is one too many. #4942 spreads `replayResets: 2` into every dispatch leg of the
+request and #4989 takes `Math.min(1, remaining)` of the transient budget at the stream boundary,
+so one logical request that reset before the head and again after it would buy a replacement on
+each. The rework gives the override a single per-request allowance and makes both stages claim
+from it.
+
+## Shape
+
+- `src/lib/request-resend-gate.ts` — the one gate. Pure table lookup for the stages the caller
+  already observed something at, plus the operator override for the ambiguous row. It never
+  restates the table: stage, cause, permission and send class all come from
+  `request-failure-model.ts`, and the cause comes from the `AttemptRecoveryKind` that will be
+  recorded, so the reason in the log and the send it authorised cannot disagree.
+- `src/lib/request-execution-budget.ts` — the allowance lives on the shared send ledger, which is
+  what a combo child inherits through `deriveRequestExecutionBudget`. Parent and child therefore
+  cannot each hold one.
+- `src/server/responses/reset-replay.ts` — the provider opt-in and the body judgment from #4942,
+  plus the per-request authority both call sites use.
+- `src/lib/upstream-retry.ts` — the pre-header claim, as a callback rather than a number.
+- `src/server/responses/combo-stream-preflight.ts` — the preflight reports the stage it observed
+  instead of a boolean, so the gate rather than the preflight decides.
+
+## Stage classification at the stream boundary
+
+#4989 gated on `responseCreated && !outputCommitted && !terminal`. That is `protocol-prelude`.
+A read error before any parsed event is `headers-only`, which the table gives the same
+commitment and therefore the same answer; the rework admits it rather than refusing a row the
+table permits. Everything else the preflight can see is `semantic-output` or `terminal`, and
+those refuse regardless of cause.
+
+## In scope from the remainders
+
+#4191 and #5180 only to the extent the resend gate reaches them. Recorded in 050.
+
+## Verification
+
+Static review plus exact-head hosted CI. Local suites, individual tests, typecheck, build,
+install and live `ocx` execution are NOT RUN by lane policy.
diff --git a/devlog/_plan/260920_round2_followups/050_lane_r5.md b/devlog/_plan/260920_round2_followups/050_lane_r5.md
new file mode 100644
index 00000000000..7343408d0cf
--- /dev/null
+++ b/devlog/_plan/260920_round2_followups/050_lane_r5.md
@@ -0,0 +1,191 @@
+# Lane R5 — the four telemetry pull requests as derived consumers of the recorder
+
+Status: OPEN. Branch `codex/260920-r5-telemetry-derived`, rebased onto `dev` after `origin/dev`
+advanced mid-lane. One branch, ordered commits, one pull request to `dev`.
+
+Lane C deferred #2366, #3748, #3983 and #5063 "as implemented", because each adds a parallel store
+or a second emission path. [030_lane_c2.md](../260920_meaning_preservation_batch/030_lane_c2.md)
+then specified the derived form for each. This lane builds those four forms. It adds no store: the
+durable shapes stay `PersistedUsageAttempt` and `PersistedUsageEntry`, and every projection reads
+them.
+
+## What landed, per pull request
+
+### #2366 (chilung-cgu) — durable failure attribution, in the landed vocabulary
+
+`failureStage` and `failureCause` now ride the attempt that ended a request and the logical row,
+both closed roster members. `FailureSide` and the seven-member `FailureStage` are not here: two
+attribution vocabularies for one question is the class that blocked 2.60.0. The PR's widening of
+`transportPhase` and `terminalSource` to arbitrary strings is not here either; those validators
+stay closed, and `terminalStatus` — which was a plain `string` — joined them, because it is now a
+grouping-key slot and it is assembled from an upstream frame.
+
+The derivation reads only closed values. `errorCode` and `upstreamError` are excluded on purpose:
+both carry upstream text, so a classification keyed on them is a different answer per provider and
+per locale, and a key built from them cannot promise it carries no content. That exclusion is what
+lets the pair be a Prometheus label and a fingerprint component with no masking pass.
+
+It runs at `addFinalRequestLog`, the one seam every request passes exactly once, and before the
+attempt snapshot so the disk row and the live attempt carry the same pair. `addRequestLog` rebuilds
+the persisted row field by field, so the pair is written there explicitly — a field omitted at that
+line reaches `/api/logs` and never reaches `usage.jsonl`.
+
+**The resend verdict is not stored.** `/api/logs` computes `resendPermission` at read time for the
+row and each attempt. The tables that decide it live in this build; a row written months ago must
+not assert a permission the current tables refuse.
+
+**Known limit, recorded rather than hidden.** Only the attempt that ends a request, plus the one
+sealed by a key-account rotation, carry attribution. The other intermediate finalizers —
+`policy-fallback.ts` and five sites in `core-combo.ts` — still reach the ledger unattributed. Each
+has different evidence in scope and a branch verified by static review alone should not add six new
+classification call sites at once. The logical row is attributed in every case, which is what the
+projection and the exporter read.
+
+**Second known limit.** A ciphertext or reasoning-parameter recovery that SUCCEEDED, followed by an
+unrelated 400 on the same attempt, still reads as that recovery's cause. The rule is narrowed to
+the last recorded kind on the matching status, and the proper fix — clearing recovery evidence on
+success in `core-opaque-recovery.ts` — belongs in the recovery path, not the derivation.
+
+### #3748 (yansigit) — a failure grouping, not a second ledger
+
+`src/telemetry/` and its SQLite store are not built. Failed rows are grouped by a versioned
+fingerprint over a fixed-arity tuple of closed roster members, folded during a scan of
+`usage.jsonl` through the existing `scanUsageLedgerCooperatively`. The projection holds a count and
+two timestamps per group; delete a ledger row and it leaves the grouping on the next rebuild.
+
+The free-text `signature` and its regex masking are replaced by construction rather than by a
+better regex: an expression can only assert it removed what it matched, while a tuple whose every
+slot comes from a frozen list has nothing to remove. Absent facts are explicit nulls in fixed
+positions, because omitting them would let `[a, null, b]` and `[a, b]` collide.
+
+**A deliberate divergence from 030_lane_c2.md, flagged for the coordinator.** That document says
+"No provider". The lane brief for R5 says the fingerprint is over "closed cause + provider + model
+class". The brief is the later and more direct instruction, so `providerClass` is in the tuple —
+resolved against the provider registry so it is a registry id or `null`, never the alias a user
+typed. Model class is NOT in the tuple: no closed model-class vocabulary exists in this repository
+and inventing one is the union-exhaustive hazard this batch exists to avoid. Removing
+`providerClass` is one slot and a version bump if the coordinator prefers the C2 shape.
+
+The mutable `monitoring/dispatched/fixed/ignored` status and its notes are absent. They are
+operator state; they cannot be reconstructed from immutable request rows, so presenting them as a
+derived ledger would be a claim this projection cannot make.
+
+The reader is `GET /api/usage?failures=1` rather than a new route: it answers a different question
+from the usage summary and costs a scan, so it is opt-in and no new CLI-parity surface appears.
+
+### #3983 (yansigit) — five counts on the attempt, no second emission path
+
+`emitDebugLine` writes the in-process ring AND stderr, and stderr is redirected to the service log
+under launchd and systemd, so the PR's per-event lines would give an installed service a durable
+per-event history beside the ledger. Its per-payload HMAC used a process-global random key, making
+every repeated prompt fragment, tool name and error message correlatable for the process lifetime.
+
+Instead the attempt carries adapter events, relayed frames, semantic bytes, side effects and
+terminal frames. Adapter events are counted at the existing adapter-parse seam; relayed frames
+after a SUCCESSFUL `controller.enqueue`. Counting both at the reader would make them equal by
+construction and erase the loss signal. The recorder is bound to the request's translator budget
+and reaches the current attempt through a callback, so a mid-request attempt rotation credits the
+live attempt rather than one already finalized. The debug ring now FORMATS one line per finalized
+attempt from those counts, through `appendDebugLogLine` and never `emitDebugLine`.
+
+Adversarial review caught the case this design gets wrong on its own: a non-streaming turn delivers
+one body and calls no per-frame recorder, so every buffered response would have persisted adapter
+events with zero relayed ones — the loss signal, raised on every buffered request. The buffered
+seam now records its delivery from the body it built.
+
+`run-turn-execution.ts` is untouched. Its accounting distinguishes adapters that report their own
+physical sends, and the PR's unconditional pre-count would double-charge them.
+
+### #5063 (Vocllum) — retention with a revision contract
+
+`usageLedgerMaxBytes` is unset by default and unset means unlimited. When set, an append that
+crosses it publishes the newest whole rows byte for byte through the shared atomic writer.
+
+The defect this closes: #5063 captured a size, copied a suffix and renamed over whatever was there,
+so a row appended in between was silently dropped; its own concurrency test performed two
+sequential calls and said it could not test concurrency. Two things close it. The append is
+synchronous and the compaction runs inside the same call stack, so no in-process append can
+interleave, and a second server on the same home cannot append at all — it is refused by the
+existing ledger-owner lease, which is why the hook is installed after ownership. And
+`validateBeforeRename` re-opens the target immediately before the rename and refuses unless
+identity, size and revision metadata are byte-for-byte what was copied. A focused test drives that
+exact window through an injected hook.
+
+Rows are copied and never parsed, which is what keeps a field a newer build wrote intact through a
+compaction. The writer gained a streaming form so the retained span is not held in memory, and that
+form fsyncs the temp before the rename and the parent directory after it.
+
+The invalidation half was missing from the original entirely. A compaction now discards the
+2,000-entry Logs ring, the retained usage aggregate and failure projection, and the request-history
+index — otherwise `/api/logs` keeps serving rows the ledger no longer has.
+
+**This does not close #5063.** The Usage-page control it also asks for is not here: this lane may
+not build or run the GUI, so it cannot produce the screenshot the gate requires, and shipping an
+unverifiable control is worse than shipping the policy it would set. The limit is settable in
+`config.json` today and the configuration reference says so. Remaining scope: the dashboard
+control, its management route, and the ten catalog strings.
+
+## The GUI screenshot gate
+
+This branch changes `gui/src/pages/Logs.tsx` and the ten locale catalogs, so `missing_ui_screenshot`
+fires. It fires on changed paths under `gui/`, not on words in a description, and this lane may not
+run `bun run build:gui`. A maintainer comment or the `gui-screenshot-waived` label is the documented
+resolution.
+
+The evidence to judge it without the screenshot: the catalog edits are purely additive (+29 lines,
+0 removed, in each of ten files, all exempt from the file-size ratchet), every new key exists in all
+ten catalogs, and three `satisfies` clauses make a missing label a typecheck failure rather than a
+silent fallback. The visible change is three rows added to the Logs detail dialog for a failed
+request — the cause, the stage it reached and the resend verdict — and a named cause where the
+attempt table previously led with a bare wire code.
+
+## Pre-existing defect found and deliberately not fixed here
+
+`src/config/atomic-write.ts` scrubs a failed temp through `effective.write(tmp, "")`, but the default
+writer opens with `"wx"`, so that fallback always fails with `EEXIST` on an existing temp. It only
+matters when `truncate` has also failed, and the temp is owner-only. It predates this branch and
+affects every atomic config write, including secret-bearing ones, so fixing it is a change to a
+security-adjacent path that belongs in its own lane rather than inside a telemetry branch.
+
+## The file-size ratchet caught this branch once
+
+`src/server/request-log.ts` carries the whole request-logging surface and was 1,962 lines against
+the repository's 2,000-line seed threshold. The attribution wiring pushed it to 2,015, and
+`file-size ratchet: repository` reported `NEW_OVERSIZED` on the first exact-head run. The remedy is
+the one AGENTS.md gives — a move, never a number — so the two places a stage and cause are decided
+and written moved to `src/server/request-log-failure-attribution.ts`, leaving the file at 1,979.
+
+Worth recording for the next lane that touches this file: 21 lines of headroom is not much, and
+the cap only ever moves down.
+
+## Verification
+
+Static source review plus exact-head hosted CI, and three adversarial reviews at high effort
+covering typecheck hazards, repository gates, and runtime correctness and privacy. Their findings
+are in the branch: the transport-evidence precedence, the 402 mapping, `transport-unsent` no longer
+being the fall-through, the parent-directory fsync, the buffered delivery accounting, the rosters
+read instead of restated in two tests, and the invariant split into INV-RESEND-01 and
+INV-ATTRIBUTION-01 so each binds exactly one test.
+
+NOT RUN on this branch, by instruction: `bun run test`, any individual `bun test` file,
+`bun run typecheck`, `bun run build:gui`, `bun run lint:gui`, `bun install`,
+`bun run structure:check`, `bun run privacy:scan`, and any live `ocx` execution. None of these may
+be recorded as passing.
+
+Checked statically:
+
+- no file this branch touches is at or over its file-size ratchet cap; `src/server/index.ts` sits at
+  884 against 893, and the ten catalogs are exempt;
+- `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json` agree key for key,
+  and each new test's regex seed resolves to the domain it is registered to — `failure-attribution`
+  is named to avoid the `request-` seed that would have placed it in `usage`;
+- `src/usage/telemetry-contract.ts` still has no imports, `src/usage/request-outcome.ts` still reaches
+  nothing but it, and `gui/src/pages/Logs.tsx` still never names `src/usage/log`;
+- no test or document restates a source constant: the rosters, the fingerprint version and the label
+  keys are read from the modules that declare them.
+
+## Issues
+
+#2366, #3748 and #3983 are addressed by these derived forms; the coordinator decides closure. #5063
+is partially addressed and must not be closed — its dashboard control is named above as remaining
+scope.
diff --git a/devlog/_plan/260920_round2_followups/050_r4_remainders.md b/devlog/_plan/260920_round2_followups/050_r4_remainders.md
new file mode 100644
index 00000000000..4c826a9d172
--- /dev/null
+++ b/devlog/_plan/260920_round2_followups/050_r4_remainders.md
@@ -0,0 +1,59 @@
+# R4 — what the remainders reach, and what they do not
+
+The lane brief put #4191 and #5180 in R4 "as far as the rework reaches". This records where that
+line actually fell, with the evidence, so the next lane starts from a finding rather than a
+re-investigation.
+
+## #4191 — reached: nothing. Found: a wrong stage in the shared vocabulary
+
+The resend gate does not consult the WebSocket projection. The post-header path excludes a
+`isCodexWsUpstreamResponse` body on purpose: the WS transport settles its own ambiguous
+failures and marks them non-replayable, and a second reader of one exchange is a defect, not a
+recovery. So the durable threading the round-2 plan names is untouched here.
+
+The investigation did surface a real defect in the projection itself.
+`classifyCodexWsFailure` in `src/server/responses/codex-ws-wire.ts` returns
+`after-response-started` — which `CODEX_WS_FAILURE_PROJECTION` maps to `semantic-output` —
+as soon as `relayedEvents > 0`. But `src/server/responses/codex-ws-exchange.ts` increments
+`relayedEvents` for every non-metadata Responses event, and `response.created` is one:
+`controlFrame` is set only when the metadata channel consumes the frame, not for lifecycle
+events. `src/lib/request-failure-model.ts` puts `response.created` in `protocol-prelude`
+and requires an output-bearing event for `semantic-output`. A WS failure carrying only a
+created event therefore projects as committed output today.
+
+It is left here rather than fixed because the fix needs a counter the classifier does not have,
+and `CodexWsStageRecord` is derived from `CodexWsFailureStage` by `Omit`, so adding one
+lands in a persisted record whose read-back whitelist in `src/usage/log.ts` would reject every
+row written before it. Adding the counter and `Omit`-ing it from the durable twin avoids that,
+but the output-bearing predicate lives in `combo-stream-preflight.ts` and restating it in the
+exchange is the class of duplication this round already paid for three times. It belongs with
+the lane that threads `failureStage` / `failureCause` into the record, where both halves can
+be written once.
+
+The SSE fallback the issue asks for stays out regardless. After `ws.send()` returns, a
+fallback is a second physical send on another transport, which is a transport decision with its
+own duplicate-inference policy — not a retry-gate change.
+
+## #5180 — reached: nothing. The symptom is upstream of this gate
+
+The reported failure is a key-auth `openai-chat` provider answering a bare 429. Traced on
+current `dev`: `rateLimitRetryPolicyFor` returns null for every provider except the
+OpenCode Go destination, so the same-target wait never runs; key rotation needs a pool of at
+least two; and `fetchWithResetRetry` returns the first received HTTP response without
+consulting its status. One send, 429 returned, which is exactly what the reporter saw.
+`Retry-After` is forwarded to the client — synthesized as `2` for a bare retryable 429 by
+`src/lib/retry-after.ts` — but the proxy never waits on it itself.
+
+None of that is an ambiguous-resend question: a received 429 is `headers-only` with cause
+`rate-limit`, which the stage table already answers `permitted` and funds from the
+`transient` class. It needs no grant and no override. What it needs is a policy default and a
+process-wide cooldown that a single-key provider can write, and `keyCooldowns` cannot be
+reused unchanged because both its identity and its write path require a multi-key pool.
+
+One adjacent accounting gap is worth recording for whoever takes it. On the generic adapter
+path, `prepareAdapterExchange` passes `attempts` and `onSendsConsumed` to its retry helper
+only when `transientRetryOn5xx` is configured. An unconfigured provider's initial send is
+therefore recorded in the attempt log but never charged to the request-wide send counter. It is
+bounded today — without `replaySafe` the reset helper makes exactly one send — so it is an
+under-count rather than an amplification, and widening it without a suite to run is not a change
+worth making blind.
diff --git a/devlog/_plan/260920_round2_followups/060_r6_usage_models_table.md b/devlog/_plan/260920_round2_followups/060_r6_usage_models_table.md
new file mode 100644
index 00000000000..e3bd25cd139
--- /dev/null
+++ b/devlog/_plan/260920_round2_followups/060_r6_usage_models_table.md
@@ -0,0 +1,95 @@
+# R6 — the Usage models table
+
+Status: OPEN until the pull request lands on `dev`.
+
+Four defects a user hit on the dashboard Usage tab, all in the models table. Three are layout; the
+first is a reading the table gets wrong.
+
+## The hit rate was withheld from every provider that reports partial cache detail
+
+On the reporter's dashboard `gpt-5.6-sol` shows 2.8B cache hits and a hit rate of `—`.
+`gpt-6-astra`, `k3[1m]`, `gemini-3.8-flash`, `gpt-5.6-luna` and `grok-4.6` show the same thing. The
+reporter read it as the zero in the cache-writes column suppressing the rate.
+
+It is not the writes column. The summary is right and the dashboard was throwing its answer away.
+
+`calculateCacheHitRate` in `src/usage/summary.ts` averages cache reads over
+`cacheObservedInputTokens` — the input tokens whose cache detail was actually reported — and
+returns `null` when nothing was observed. That denominator is the #4546 contract recorded in
+`structure/gui-and-management-api.md`: a synthesized zero and an unreported detail must not be
+averaged as cache misses, or a pool that discarded every warm prefix reports a plausible hit rate.
+A provider that reports reads and never reports writes is observed, and it has a rate.
+
+The dashboard then required that denominator to cover the row's **entire** input before it would
+show the number:
+
+```tsx
+model.cacheObservedInputTokens >= model.inputTokens ? model.cacheHitRate : null
+```
+
+One request in the row with no cache detail — a locally answered turn, an unreported usage record,
+a row written by an older proxy — puts the denominator below `inputTokens` and blanks the column.
+For a busy model that is every row, which is why six models with billions of measured hits all read
+`—`. The gate arrived with the cache columns in #5268 and was never the server's rule.
+
+The fix drops the gate. The cell renders whatever the summary supplied, because the summary already
+refused to supply a number it could not justify, and the coverage becomes a tooltip instead of a
+reason to hide the value: `usage.cacheHitRate.partial` names the measured and total input tokens on
+a partially observed row, `usage.cacheHitRate.unmeasured` explains the em dash on a row where
+nothing reported cache detail. That row — no basis at all — is now the only one that shows `—`.
+
+The coverage sentence is carried twice: a `title` for a pointer, and an `sr-only` span so it is not
+mouse-only. A `td` is not focusable and a `title` never reaches a keyboard or a touch screen, and a
+cell whose whole point is to explain a number should not explain it to one input device.
+
+No server change. The denominator, the provenance split and the `null` are all correct as they
+stand, and the structure doc that owns the contract stays accurate.
+
+## Column order
+
+`Model, Provider, Share, Tokens, API list-price`, then the per-request detail:
+`Requests, Measured, Input tokens, Output tokens, Cache hits, Cache writes, Hit rate`. Identity
+first, then the three figures a reader compares models on, then the evidence behind them. The
+previous order buried share and price behind five cache columns.
+
+## Sideways scroll and pinned identity columns
+
+`.tbl` is `width: 100%`, so twelve columns divided the shell between them until eight-digit token
+totals folded onto a second line. The models table is now `width: max-content; min-width: 100%` and
+the shell scrolls sideways — `.tbl-wrap` was already `overflow-x: auto`, so nothing else had to
+move. Model and provider are `position: sticky` at fixed widths so a row stays identifiable while
+its numbers scroll; both offsets are one `var(--space-3)` step negative, the same trick the sticky
+header plays with `top`, so a stuck cell repaints the scrollport padding it slides over. Under
+720px the pinning stands down, because at that width two pinned columns cost more reading room than
+scrolling the whole table does.
+
+Every selector is doubled as `.tbl.usage-models-tbl`. This file is `@import`ed from the top of
+`styles.css`, so the whole of `styles.css` cascades after it, and a single class ties
+`.tbl { width: 100% }` on specificity and loses on source order — the sizing contract reads as
+applied and does nothing. The rules that already lived in this file buy the same margin with a
+`.usw-section` prefix. The source-oracle case asserts the doubled form, because the single-class
+version is the failure that looks correct.
+
+## The exclusion caption
+
+`(56 requests excluded)` shared a line with the amount and folded mid-phrase. It is a block now, so
+the amount is the first line and the caption is the second.
+
+## Verification
+
+GUI change, so the screenshot gate applies and this lane cannot satisfy it: builds are not
+permitted here, so no dashboard was rendered to photograph. The evidence offered instead is the
+column order and cell layout written out above, the regression assertions below, and hosted CI.
+
+- `gui/tests/usage-custom-range.test.tsx` — the partially observed row now asserts `90%` where it
+  asserted `—`, with both tooltips, and the header sequence asserts the new order.
+- `gui/tests/usage-layout.test.ts` — new source-oracle case binding the scroll, the pinned columns
+  and the block caption, so removing the stylesheet rules fails rather than degrading silently.
+- Adversarial static review by a second agent, since nothing here may be executed: it reproduced
+  the cascade defect above independently and hand-evaluated the rendered cell arrays for all three
+  fixture rows against the new JSX.
+- NOT RUN: `bun run test`, `bun test` on any single file, `bun run typecheck`, `bun run lint:gui`,
+  `bun run build:gui`, `bun install`, and any `ocx` execution. Hosted CI at the exact head is the
+  only execution evidence for this lane; GUI lint, typecheck and `gui` tests all run in the
+  `gates` job of `Cross-platform CI`, which a branch push does not trigger and the pull request
+  does.
diff --git a/devlog/_plan/260920_round2_followups/070_widget_signing.md b/devlog/_plan/260920_round2_followups/070_widget_signing.md
new file mode 100644
index 00000000000..9fbf7ec0059
--- /dev/null
+++ b/devlog/_plan/260920_round2_followups/070_widget_signing.md
@@ -0,0 +1,70 @@
+# Widget extension signing
+
+Status: OPEN until the pull request lands on `dev`.
+
+The macOS app would have installed with no widget, and nothing in the build would have said so.
+
+## What was wrong
+
+`macOS.files` in `desktop/src-tauri/tauri.conf.json` puts `PlugIns/OpenCodexWidget.appex` into the
+bundle. The Tauri bundler copies it and never signs it: `copy_custom_files_to_bundle` in
+tauri-bundler 2.5.0 writes the file and does not add it to `sign_paths`, which only ever holds
+`Contents/MacOS`, `Contents/Frameworks` and the `.app` itself. There is no `--deep` anywhere in
+that path. Whatever signature `build-widget.sh` leaves is therefore the signature that ships.
+
+`build-widget.sh` left an ad-hoc one. Its signing branch keys on `MACOS_SIGN_IDENTITY`, and the
+release workflow set that variable only on the `Build desktop bundles` step — the step *after* the
+widget was built. `Build WidgetKit extension` carried no `env:` block at all, so the script always
+took its `codesign --force --sign -` fallback, with `--timestamp=none` and no hardened runtime.
+
+macOS does not register an extension signed that way, and notarization rejects any Mach-O in a
+bundle that lacks the hardened runtime.
+
+## What had not happened yet
+
+No release has shipped a macOS app. v2.58, v2.59 and v2.60 all carry zero desktop assets, and the
+`APPLE_*` secrets were added to the repository hours after the last release ran. The signed branch
+of this script has never executed. This is a defect found before its first victim, not one being
+recovered from — the next release is where it would have landed.
+
+## The fix
+
+The script resolves its signing identity before the Swift build, so a release that holds Developer
+ID material and somehow has no identity fails in a second instead of after a universal build, and
+never leaves a half-built unsigned appex behind. `WIDGET_SIGN_REQUIRED=1` makes that refusal the
+behaviour whenever the workflow holds a certificate; the ad-hoc branch stays for local builds.
+
+Signing walks every Mach-O the bundle actually contains, chosen by magic bytes rather than by name.
+Today that set is one file. A suffix filter is the thing that fails silently when that stops being
+true: a helper tool or an embedded dylib carries no extension to match, stays unsigned, and the
+submission comes back "The binary is not signed with a valid Developer ID certificate" while the
+containing bundle looks perfectly signed. Every signature now carries `--options runtime`, and the
+script re-reads its own result and fails if the runtime flag is missing.
+
+The workflow imports the certificate into a temporary keychain before the widget is built, because
+codesign resolves an identity through the keychain search list and Tauri does not build its own
+keychain until the bundling step. Tauri re-adds itself to the same search list, so the two do not
+collide, and a cleanup step deletes the keychain on any outcome.
+
+## Verification
+
+Run locally on macOS 27 with Xcode 27.0 and a real Developer ID in the keychain.
+
+- Signed path: `flags=0x10000(runtime)`, `Authority=Developer ID Application`, `TeamIdentifier`
+  set, secure timestamp present, `com.apple.security.app-sandbox` preserved, and
+  `codesign --verify --deep --strict` clean. `CFBundleShortVersionString` and `CFBundleVersion`
+  both resolve to the Tauri version.
+- Ad-hoc path with no identity: `flags=0x10002(adhoc,runtime)` — the hardened runtime is now on
+  the local build too, so the two paths differ only in who signed.
+- `WIDGET_SIGN_REQUIRED=1` with no identity: refuses in under a second, before the build.
+- Bundle simulation: an `.app` holding the signed appex under `Contents/PlugIns`, signed the way
+  Tauri signs — inner executables, then the bundle, no `--deep` — keeps the nested Developer ID
+  signature, runtime flag, team identifier and entitlements intact, and
+  `codesign --verify --deep --strict` reports `--validated:...OpenCodexWidget.appex`.
+- The same simulation over an appex left unsigned fails outer signing with
+  `In subcomponent: .../OpenCodexWidget.appex`.
+- `tests/ci-workflows/release-desktop-scripts.test.ts` — 11 pass, binding the workflow wiring, the
+  magic-byte sweep, the hardened runtime and its self-check, and the refusal.
+
+End-to-end notarization of a full OpenCodex `.app` was not run; that needs a complete `tauri build`
+and the release workflow is where it belongs.
diff --git a/devlog/_plan/260920_round2_followups/090_closeout.md b/devlog/_plan/260920_round2_followups/090_closeout.md
new file mode 100644
index 00000000000..7d491dff65e
--- /dev/null
+++ b/devlog/_plan/260920_round2_followups/090_closeout.md
@@ -0,0 +1,66 @@
+# Round 2 closeout
+
+Status: CLOSED. Every R lane landed on `dev` and the branch is green again. This file records
+what landed, the two incidents the round produced, and the rule the maintainer approved because
+of them.
+
+## What landed
+
+| Lane | Pull request | Subject |
+| --- | --- | --- |
+| R1 | #5331 | Complete the provider-table transition on a paginated OpenAI home |
+| R2 | #5338, #5351 | Keep the verification build out of updater signing, then assert the executable the bundle declares |
+| R3 | #5332 | Make a failed browser launch and a failed account refresh visible (#5261) |
+| R4 | #5342 | Rework #4942 and #4989 into one ambiguous-resend gate with one grant per request |
+| R5 | #5347 | Derive the four telemetry pull requests from the landed recorder |
+| R6 | #5333, #5345, #5353 | Usage table readability, WidgetKit Developer ID signing, keychain step location |
+
+#5342 is the one to notice. An earlier lane had ruled that #4942 and #4989 must not each buy an
+independent replacement send for one logical request, and that they therefore belonged in a
+single reworked change rather than two. That disposition closed as an implementation rather than
+as a note.
+
+## Incident one: a default flip that no test could see
+
+#5271 removed a hostname test that decided the `developer` wire role. Deleting the inference was
+right — a gateway proxying OpenAI accepts the role and the hostname cannot say so. The
+replacement default was wrong in the other direction: forwarding to every destination assumed
+each one accepts a standard role until an operator marks it.
+
+Three lane dispatches died on `400 role 'developer' is not allowed` within four seconds of
+starting. Nothing in this repository saw it first, because every test in the tree was written
+against the new default and passed. What broke was outside the tree.
+
+#5334 made the key tri-state with the unset state on the safe side, and then three more landings
+were needed because three suites still asserted the forwarded role and the first sweep missed
+them: the Lab conformance vector in `src/lab/` (#5341), a suite whose messages come from a
+helper rather than a literal (#5344), and a suite about documents that reads the role only to
+locate the turn (#5346). Searching for a string is not how you find what asserts a default; the
+reliable question is which tests call the adapter at all.
+
+## Incident two: a verification step that had never run
+
+The `macos widget + bundle` job failed on `tauri build` because the updater public key is
+committed and the private key is not in CI. #5338 scoped the opt-out to the verification build.
+With that green, the Verify step ran for the first time and failed on its first line, silently,
+because `test` prints nothing: it asserted `Contents/MacOS/OpenCodex` while Tauri keeps the Cargo
+bin name unless `mainBinaryName` is set. #5351 reads `CFBundleExecutable` from the bundle instead.
+
+The same shape appeared once more at the end. #5345's test located a workflow step by name, #5339
+renamed that step while the branch was open, and the rename survived the merge while the assertion
+did not. #5353 locates the steps by what they run.
+
+## The rule the maintainer approved
+
+A change that flips an existing default is a separate approval item before merge. Tests in the
+tree are written against the new default and pass; what breaks is the set of real destinations
+outside it, which exact-head CI cannot reach. Two instances landed on the same day — the 1 MiB
+queue budget in #5182 and the role default in #5271 — and only the second was caught by a human
+noticing that dispatch had stopped working.
+
+## Still open
+
+#5261 keeps two remainders: generic OAuth and key login still discard the launch result, and the
+dashboard roster keeps last-good rows after a failed refresh. #4191 wants the SSE fallback and
+#5180 the shared cooldown, both transport and routing changes. #5292 records the Logs page union
+restatement. #2366, #3748, #3983 and #5063 remain deferred with reasons recorded on each.
diff --git a/devlog/_plan/260920_round2_followups/r6-usage-table/r6-01-column-order.png b/devlog/_plan/260920_round2_followups/r6-usage-table/r6-01-column-order.png
new file mode 100644
index 00000000000..eae536967f7
Binary files /dev/null and b/devlog/_plan/260920_round2_followups/r6-usage-table/r6-01-column-order.png differ
diff --git a/devlog/_plan/260920_round2_followups/r6-usage-table/r6-02-pinned-scroll.png b/devlog/_plan/260920_round2_followups/r6-usage-table/r6-02-pinned-scroll.png
new file mode 100644
index 00000000000..dc835c86e0f
Binary files /dev/null and b/devlog/_plan/260920_round2_followups/r6-usage-table/r6-02-pinned-scroll.png differ
diff --git a/devlog/_plan/260920_round2_followups/r6-usage-table/r6-03-narrow-fallback.png b/devlog/_plan/260920_round2_followups/r6-usage-table/r6-03-narrow-fallback.png
new file mode 100644
index 00000000000..623f653e1a9
Binary files /dev/null and b/devlog/_plan/260920_round2_followups/r6-usage-table/r6-03-narrow-fallback.png differ
diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs
index 29b5abb1e79..2b68b5d457b 100644
--- a/docs-site/astro.config.mjs
+++ b/docs-site/astro.config.mjs
@@ -96,6 +96,8 @@ export default defineConfig({
             { label: "Codex App Model Picker", translations: { fr: "Sélecteur de modèles de Codex App", ko: "Codex App 모델 선택기", "zh-CN": "Codex App 模型选择器", "zh-TW": "Codex App 模型選擇器", ru: "Выбор модели в Codex App", ja: "Codex App モデルピッカー", tr: "Codex App Model Seçici" }, slug: "guides/codex-app-models" },
             { label: "Codex Prompt Layers", translations: { fr: "Couches d'invite Codex", ko: "Codex 프롬프트 레이어", "zh-CN": "Codex 提示词层", "zh-TW": "Codex 提示詞層", ru: "Слои промпта Codex", ja: "Codex プロンプトレイヤー", tr: "Codex İstem Katmanları" }, slug: "guides/codex-prompt" },
             { label: "Native Context Compatibility", translations: { ko: "네이티브 컨텍스트 호환성" }, slug: "guides/codex-native-context" },
+            { label: "macOS Menu Bar App", translations: { fr: "Application barre de menus macOS", ko: "macOS 메뉴바 앱", "zh-CN": "macOS 菜单栏应用", "zh-TW": "macOS 選單列 App", ru: "Приложение в строке меню macOS", ja: "macOS メニューバーアプリ", tr: "macOS Menü Çubuğu Uygulaması" }, slug: "guides/macos-menu-bar" },
+            { label: "Desktop App", translations: { fr: "Application de bureau", ko: "데스크톱 앱", "zh-CN": "桌面应用", "zh-TW": "桌面 App", ru: "Настольное приложение", ja: "デスクトップアプリ", tr: "Masaüstü Uygulaması" }, slug: "guides/desktop-app" },
             { label: "Model Ordering", translations: { fr: "Ordre des modèles", ko: "모델 정렬에 관하여", "zh-CN": "模型排序", "zh-TW": "模型排序", ru: "Сортировка моделей", ja: "モデルの並び順", tr: "Model Sıralaması" }, slug: "guides/model-ordering" },
             { label: "Combos", translations: { fr: "Combinaisons", ko: "콤보", "zh-CN": "组合", "zh-TW": "組合", ru: "Комбо", ja: "コンボ", tr: "Kombolar" }, slug: "guides/combos" },
             { label: "Claude Code", translations: { fr: "Claude Code", ko: "Claude Code", "zh-CN": "Claude Code", "zh-TW": "Claude Code", ru: "Claude Code", ja: "Claude Code", tr: "Claude Code" }, slug: "guides/claude-code" },
@@ -164,6 +166,7 @@ export default defineConfig({
           items: [
             { label: "Windows Memory Growth", translations: { fr: "Augmentation de la mémoire sous Windows", ko: "Windows 메모리 증가", "zh-CN": "Windows 内存增长", "zh-TW": "Windows 記憶體增長", ru: "Рост памяти в Windows", ja: "Windows メモリ増加", tr: "Windows Bellek Artışı" }, slug: "troubleshooting/windows-memory" },
             { label: "Disk Usage from Temp Files", translations: { fr: "Espace disque et fichiers temporaires", ko: "임시 파일 디스크 사용량", "zh-CN": "临时文件磁盘占用", "zh-TW": "暫存檔磁碟用量", ru: "Использование диска временными файлами", ja: "一時ファイルのディスク使用量", tr: "Geçici Dosya Disk Kullanımı" }, slug: "troubleshooting/disk-usage-temp-files" },
+            { label: "Codex Cannot Sign In or Load", translations: { fr: "Codex ne peut pas se connecter", ko: "Codex 로그인 불가", "zh-CN": "Codex 无法登录", "zh-TW": "Codex 無法登入", ru: "Codex не может войти", ja: "Codex にサインインできない", tr: "Codex Oturum Açamıyor" }, slug: "troubleshooting/codex-cannot-sign-in" },
           ],
         },
         { label: "Contributing", translations: { fr: "Contribuer", ko: "기여하기", "zh-CN": "贡献", "zh-TW": "貢獻", ru: "Как внести вклад", ja: "コントリビュート", tr: "Katkıda Bulunma" }, slug: "contributing" },
diff --git a/docs-site/public/favicon.ico b/docs-site/public/favicon.ico
index de1689b20be..8f120715e2d 100644
Binary files a/docs-site/public/favicon.ico and b/docs-site/public/favicon.ico differ
diff --git a/docs-site/public/favicon.png b/docs-site/public/favicon.png
index 7a741511cff..6c26bfafb00 100644
Binary files a/docs-site/public/favicon.png and b/docs-site/public/favicon.png differ
diff --git a/docs-site/src/content/docs/fr/getting-started/quickstart.md b/docs-site/src/content/docs/fr/getting-started/quickstart.md
index 7a7c3f8cec3..73512a4a6c8 100644
--- a/docs-site/src/content/docs/fr/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/fr/getting-started/quickstart.md
@@ -13,7 +13,7 @@ ocx init
 
 `ocx init` vous accompagne dans les étapes suivantes :
 
-1. **Choix d’un fournisseur** — sélectionnez l’un des 95 préréglages intégrés au registre, ou `custom` pour saisir une
+1. **Choix d’un fournisseur** — sélectionnez l’un des 96 préréglages intégrés au registre, ou `custom` pour saisir une
    URL de base et un adaptateur.
 2. **Clé API** — collez une clé ou référencez une variable d’environnement telle que `${ANTHROPIC_API_KEY}`.
 3. **Modèle par défaut** — pour les fournisseurs clés, locaux et personnalisés, acceptez le préréglage ou saisissez un identifiant de modèle.
diff --git a/docs-site/src/content/docs/fr/guides/claude-code.md b/docs-site/src/content/docs/fr/guides/claude-code.md
index d207a3bc003..45851d1fc0d 100644
--- a/docs-site/src/content/docs/fr/guides/claude-code.md
+++ b/docs-site/src/content/docs/fr/guides/claude-code.md
@@ -121,7 +121,34 @@ Sur macOS, l'intégration automatique (`claudeCode.systemEnv`) suit la même ré
 `claude` lancée sans passer par `ocx` se comporte donc de la même manière. Le fichier d'environnement est un instantané actualisé au
 démarrage du proxy ou lors de l'enregistrement des paramètres, tandis que `ocx claude` effectue toujours une résolution immédiate.
 
-## Profil Claude Desktop
+## Modes Claude Desktop : first-party (par défaut) et passerelle
+
+Claude Desktop utilise OpenCodex dans l'un de deux modes mutuellement exclusifs. Choisissez-le dans
+**Claude → Bureau → Mode de connexion** du tableau de bord ou avec
+`ocx claude desktop apply --first-party|--gateway`.
+
+- **First-party (par défaut)** : Desktop lui-même n'est pas reconfiguré. La connexion claude.ai,
+  l'onglet Chat, les connecteurs et le contrôle à distance continuent de fonctionner. OpenCodex
+  n'écrit que deux valeurs dans le bloc `env` de `~/.claude/settings.json` :
+  `HTTPS_PROXY=http://127.0.0.1:<port public+100>` et
+  `NODE_EXTRA_CA_CERTS=~/.opencodex/claude-intercept/ca.pem`. Seuls Claude Code lancé par Desktop
+  pour l'onglet Code (sous-agents compris) et la CLI `claude` du terminal les lisent et passent par le
+  proxy d'interception local ; seuls `POST /v1/messages` et `count_tokens` sont traités par OpenCodex,
+  les autres chemins de `api.anthropic.com` sont relayés tels quels vers Anthropic. L'AC n'est jamais
+  installée dans le magasin de confiance du système.
+- **Passerelle (tiers)** : l'ancien mode ; le profil ci-dessous fait basculer toute l'application sur
+  OpenCodex comme passerelle. Sélectionnez-le explicitement (`--gateway`, ou les anciens
+  `--static`/`--hybrid`/`--discovery-only`).
+
+Le mode est enregistré dans `claudeCode.desktopMode`. Les installations ayant déjà appliqué un profil
+passerelle le conservent après mise à jour ; seules les nouvelles installations démarrent en
+first-party. Changer de mode supprime la configuration de l'autre mode (uniquement les valeurs
+écrites par OpenCodex) ; un `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` étranger (proxy d'entreprise) n'est
+jamais écrasé et l'application est refusée. Quittez complètement Desktop puis rouvrez-le après un
+changement. Les détails et la compatibilité de la CLI Claude Code sont décrits dans la documentation
+anglaise.
+
+## Profil Claude Desktop (mode passerelle)
 
 Claude Desktop utilise un profil distinct de Claude Code. Ouvrez **Claude → Bureau** dans le
 tableau de bord afin de placer chaque route disponible dans l'une des quatre familles : Opus, Fable, Sonnet ou Haiku.
@@ -628,4 +655,4 @@ Utilisez `"haiku"` comme valeur de remplacement pour le modèle.
 
 Dans `config.json`, `claudeCode.stabilizePromptCache: true` déplace les notices Claude reconnues en fin des instructions système vers un dernier message utilisateur sur les routes traduites. La valeur par défaut est `false`. Activez cette option seulement si ce changement de rôle convient à vos clients. Les exemples dans des blocs de code et le texte non reconnu sont conservés ; le transfert Anthropic natif reste inchangé. Sans métadonnées, la clé de cache suit les instructions stabilisées. Cette option ne crée pas une identité de conversation et ne garantit aucun succès du cache amont.
 
-Sur la route Chat d’OpenCode Go pour `deepseek-v4.1-flash`, les rappels système traduits dans l’historique conservent automatiquement leur position et leur rôle system, après les résultats d’outils encore attendus. Ainsi, l’ajout de rappels ne réécrit pas le prompt système initial. Ce comportement s’applique avec ou sans `stabilizePromptCache` ; la conversion des autres modèles et destinations, ainsi que le transfert Anthropic natif, restent inchangés. La réutilisation du cache exige toujours une identité de session stable et un cache disponible en amont. Les changements des instructions ou outils antérieurs et la compaction de la conversation peuvent aussi affecter les succès du cache ; préserver l’ordre des rappels ne suffit pas à garantir sa réutilisation.
+Sur toutes les routes Chat traduites, les rappels de l’historique conservent leur position dans la conversation, après les résultats d’outils encore attendus. L’ajout d’un rappel ne réécrit donc pas le prompt système initial, et une instruction placée au milieu de la conversation n’arrive plus avant les tours qu’elle était censée suivre. Le rôle porté par cet emplacement se décide séparément : un rappel part en `system`, sauf si le fournisseur enregistre `foldDeveloperRoleToSystem: false`, ce qui indique que le service en amont accepte le rôle `developer` et le transmet à la même position. Un service qui ne l’accepte pas répond `400 role 'developer' is not allowed` et le tour ne démarre pas, d’où le repli d’une destination non enregistrée. Ce comportement s’applique avec ou sans `stabilizePromptCache` ; le transfert Anthropic natif reste inchangé. La réutilisation du cache exige toujours une identité de session stable et un cache disponible en amont. Les changements des instructions ou outils antérieurs et la compaction de la conversation peuvent aussi affecter les succès du cache ; préserver l’ordre des rappels ne suffit pas à garantir sa réutilisation.
diff --git a/docs-site/src/content/docs/fr/guides/codex-integration.md b/docs-site/src/content/docs/fr/guides/codex-integration.md
index dd1d5f97dd6..f5aada09618 100644
--- a/docs-site/src/content/docs/fr/guides/codex-integration.md
+++ b/docs-site/src/content/docs/fr/guides/codex-integration.md
@@ -21,7 +21,7 @@ l'identifiant du fournisseur `openai` intégré à Codex et fait pointer ce four
 ```toml
 # root keys, before the first table
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 openai_base_url = "http://127.0.0.1:10100/v1"
 
 # only when fastMode is set; unset adds no [features] table
@@ -119,7 +119,7 @@ model_provider = "opencodex"
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
 
 # appended at the end of the file
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 [model_providers.opencodex]
 name = "OpenCodex Proxy"
 base_url = "http://your-host:10100/v1"
@@ -419,7 +419,7 @@ Codex. Seule l'exécution explicite de `ocx stop` ou `ocx service stop` restaure
 
 ## Refus de sécurité pour l’historique paginé
 
-Une transition de fournisseur peut renvoyer `history_paginated_requires_native_writer` si le stockage concerné prend en charge la pagination, même pour ses lignes legacy. Cette raison ne refuse plus la configuration Codex, le profil de référence ni le catalogue de modèles. `ocx sync` et `ocx start` écrivent toujours ces fichiers et définissent `model_catalog_json`, afin que le sélecteur de modèles Codex continue d’afficher tous les modèles routés par OpenCodex. Seule cette raison interrompt le réétiquetage de l’historique des conversations, car Codex attribue les numéros d’historique paginé dans son propre processus d’écriture et aucune nouvelle tentative n’y change rien. Toute autre raison de contrôle préalable de l’historique — une base d’état illisible, un historique dont l’identité a changé, ou un contrôle préalable qui n’a pas pu s’exécuter — refuse encore toute la transition et l’annule, car ces cas peuvent réussir plus tard. Dans cet état, OpenCodex ne modifie jamais les fichiers d’historique paginé ni les lignes de conversation. Les conversations existantes conservent le fournisseur déjà associé et ne sont pas migrées ; les nouvelles conversations passent par le proxy. Lorsque le réétiquetage est interrompu, une table `[model_providers.opencodex]` déjà présente dans le répertoire d’accueil est conservée plutôt que retirée, y compris sous la forme root-override (loopback), afin que les conversations dont les lignes sont étiquetées `opencodex` gardent un identifiant de fournisseur qui existe encore. Le CLI affiche `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`. `ocx restore` et la suppression de la configuration Codex refusent toujours sur `history_paginated_requires_native_writer`. Retirer la définition `[model_providers.opencodex]` alors que des lignes de conversation la référencent encore rendrait ces conversations irrésolubles, et le chemin de restauration n’a aucun moyen de conserver une table de fournisseur de compatibilité. Un répertoire d’accueil déjà paginé ne peut pas actuellement être désinstallé par le produit ; c’est un travail ouvert connu, et non le comportement voulu.
+Une transition de fournisseur peut renvoyer `history_paginated_requires_native_writer` si le stockage concerné prend en charge la pagination, même pour ses lignes legacy. Cette raison ne refuse plus la configuration Codex, le profil de référence ni le catalogue de modèles. `ocx sync` et `ocx start` écrivent toujours ces fichiers et définissent `model_catalog_json`, afin que le sélecteur de modèles Codex continue d’afficher tous les modèles routés par OpenCodex. Seule cette raison interrompt le réétiquetage de l’historique des conversations, car Codex attribue les numéros d’historique paginé dans son propre processus d’écriture et aucune nouvelle tentative n’y change rien. Toute autre raison de contrôle préalable de l’historique — une base d’état illisible, un historique dont l’identité a changé, ou un contrôle préalable qui n’a pas pu s’exécuter — refuse encore toute la transition et l’annule, car ces cas peuvent réussir plus tard. Dans cet état, OpenCodex ne modifie jamais les fichiers d’historique paginé ni les lignes de conversation. Les conversations existantes conservent le fournisseur déjà associé et ne sont pas migrées ; les nouvelles conversations passent par le proxy. Lorsque le réétiquetage est interrompu, une table `[model_providers.opencodex]` déjà présente dans le répertoire d’accueil est conservée plutôt que retirée, y compris sous la forme root-override (loopback), afin que les conversations dont les lignes sont étiquetées `opencodex` gardent un identifiant de fournisseur qui existe encore. Le CLI affiche `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`. `ocx restore`, `ocx stop` et `ocx uninstall` ne refusent plus sur `history_paginated_requires_native_writer`. Ils retirent toutes les clés de routage racine d'OpenCodex et conservent la définition `[model_providers.opencodex]` sur le disque : les conversations dont les lignes nomment encore ce fournisseur restent résolubles, tandis que `codex` seul cesse de pointer vers le proxy. Le résultat est signalé comme une restauration partielle qui nomme les lignes conservées, et `ocx restore --remove-codex-provider-table` les supprime aussi, après quoi ces conversations ne s'ouvrent plus. Par ailleurs, activer l'intégration sous sa forme table de fournisseur sur un répertoire d'accueil dont les conversations marquées `openai` ont déjà été paginées par Codex était auparavant refusé d'emblée avec `history_paginated_openai_requires_native_writer` : rien n'était écrit et l'intégration restait désactivée. OpenCodex termine désormais cette transition en conservant la redéfinition racine gérée `openai_base_url` à côté de la table `[model_providers.opencodex]`. Codex fusionne cette redéfinition avec son fournisseur `openai` intégré, donc ces conversations continuent d'atteindre le proxy sans être réétiquetées, et aucun octet d'historique ni ligne de conversation n'est modifié. Seule une forme de routage exigeant l'en-tête d'admission `x-opencodex-api-key` refuse encore, car le fournisseur intégré de Codex ne peut pas porter cet en-tête ; son message nomme les deux réglages qui résolvent la situation — router Codex par l'écouteur loopback pour conserver la redéfinition, ou mettre `syncResumeHistory` à `false` en acceptant que ces conversations reprennent sur le point de terminaison OpenAI propre à Codex.
 
 Lors du retour au mode de remplacement de l’URL racine, OpenCodex conserve la définition `[model_providers.opencodex]` existante avant de valider la configuration, même si la vérification préalable de l’historique réussit. Les anciennes conversations `opencodex` peuvent ainsi toujours retrouver leur fournisseur si Codex migre l’historique après cette validation ou pendant le démarrage du traitement en arrière-plan. Les nouvelles conversations utilisent le fournisseur racine sélectionné ; la restauration explicite conserve ses contrôles de suppression distincts.
 
diff --git a/docs-site/src/content/docs/fr/guides/integrations.md b/docs-site/src/content/docs/fr/guides/integrations.md
index 38fb208516d..1f3e04ada55 100644
--- a/docs-site/src/content/docs/fr/guides/integrations.md
+++ b/docs-site/src/content/docs/fr/guides/integrations.md
@@ -254,6 +254,36 @@ Les détails des clients ont été vérifiés par rapport au format de configura
 consultez les notes de recherche dans
 `devlog/_fin/260802_client_toggle_api/002_client_toggle_matrix.md` pour savoir ce qui a été contrôlé et quand.
 
+## ZCode 3.14 et versions ultérieures
+
+ZCode 3.14 a déplacé ses fournisseurs personnalisés vers `~/.zcode/v2/provider_config.json` et ne
+lit plus `~/.zcode/v2/config.json` qu'au travers d'un import unique, exécuté seulement quand le
+nouveau fichier est absent. ZCode crée ce nouveau fichier au premier lancement : sur toute
+installation déjà démarrée une fois, l'import a donc déjà eu lieu et une écriture dans
+`config.json` n'atteint plus rien.
+
+opencodex écrit désormais `provider_config.json` directement quand il le peut. Activer
+l'intégration ajoute la règle de fournisseur `opencodex` dans ce fichier, une actualisation du
+catalogue la met à jour, et la désactivation retire exactement ce qu'opencodex y a mis. Toutes les
+autres règles du fichier restent intactes, y compris celle qu'un autre fournisseur conserve pour un
+identifiant de modèle qui figure aussi chez nous. Une règle portant l'identifiant `opencodex`
+qu'opencodex n'a pas écrite est un conflit et non quelque chose à reprendre : réglez-la dans ZCode,
+ou utilisez l'écrasement explicite.
+
+Deux situations refusent encore au lieu d'écrire. Un bloc écrit par opencodex avant le déplacement
+du stockage maintient l'intégration sur `config.json` : désactivez-la d'abord à cet endroit, puis
+réactivez-la pour écrire le nouveau stockage. Et un `provider_config.json` dont le
+`schemaVersion` n'est pas un de ceux qu'opencodex a observés est signalé plutôt que fusionné :
+ce fichier contient tous les fournisseurs de ZCode, et y affirmer une forme échangerait une
+absence d'effet silencieuse contre une perte silencieuse. L'état nomme le fichier que ZCode lit dès
+que l'intégration ne l'écrit pas.
+
+Dans ce second cas, ajoutez le fournisseur dans les réglages de ZCode : URL de base
+`http://127.0.0.1:10100/v1` (ajustez le port à votre écoute), une clé non vide quelconque, et les
+identifiants de modèle donnés par `ocx export --client zcode`. Supprimer
+`provider_config.json` pour relancer l'import de ZCode n'est pas pris en charge : cela détruit
+tous les fournisseurs que ZCode y conserve.
+
 ## Cline CLI
 
 Cline CLI utilise providers.json et models.json. Quittez Cline avant toute modification ou synchronisation, puis redémarrez-le. Annuler restaure les deux originaux. Le fournisseur par défaut reste inchangé. Cette intégration ne migre pas le stockage des anciennes extensions VS Code.
diff --git a/docs-site/src/content/docs/fr/guides/providers.md b/docs-site/src/content/docs/fr/guides/providers.md
index f34081cfcc5..7e9115e0033 100644
--- a/docs-site/src/content/docs/fr/guides/providers.md
+++ b/docs-site/src/content/docs/fr/guides/providers.md
@@ -283,7 +283,7 @@ existante n'est pas concernée.
 
 ## 3. Catalogue des clés API
 
-opencodex fournit 95 préréglages intégrés : 79 à clé, 12 OAuth, trois locaux et un préréglage par défaut de
+opencodex fournit 96 préréglages intégrés : 80 à clé, 12 OAuth, trois locaux et un préréglage par défaut de
 transfert ChatGPT. Dans le tableau de bord, le sélecteur **Ajouter un fournisseur** ouvre le tableau de bord du
 fournisseur à clé, valide la clé et l'enregistre ; la validation dépend du fournisseur. Parmi les entrées notables :
 
diff --git a/docs-site/src/content/docs/fr/reference/cli/lifecycle.md b/docs-site/src/content/docs/fr/reference/cli/lifecycle.md
index c134193f422..f59ebe9916b 100644
--- a/docs-site/src/content/docs/fr/reference/cli/lifecycle.md
+++ b/docs-site/src/content/docs/fr/reference/cli/lifecycle.md
@@ -303,6 +303,7 @@ Utilisez `ocx service` pour maintenir un proxy d’arrière-plan toujours actif,
 ### `ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`
 
 Installe et contrôle l’icône OpenCodex dans la zone de notification Windows. Elle démarre à l’ouverture de session et fournit des commandes du proxy accessibles en un clic. `start` et `stop` contrôlent uniquement l’icône ; utilisez son menu pour contrôler le proxy. `--no-start` s’applique à `install` et installe l’icône sans la lancer immédiatement.
+Obsolète : l’application OpenCodex fournit la zone de notification sous Windows, macOS et Linux ; `ocx tray` reste disponible pour les installations sans l’application de bureau.
 
 ## Tableau de bord
 
diff --git a/docs-site/src/content/docs/fr/reference/configuration/providers.md b/docs-site/src/content/docs/fr/reference/configuration/providers.md
index a96d502b6c4..c4fd2dc57de 100644
--- a/docs-site/src/content/docs/fr/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/fr/reference/configuration/providers.md
@@ -132,12 +132,14 @@ sauvegarde dont le contenu diffère, puis réécrit en identifiants sans préfix
 | `noPenaltyModels?` | `string[]` | Modèles qui rejettent les pénalités presence/frequency. |
 | `noStructuredOutputModels?` | `string[]` | ID de modèle exact dont le point final `openai-chat` rejette `response_format`. Seule une correspondance exacte du modèle demandé omet le champ ; la traduction à sortie structurée reste activée pour tous les autres modèles `openai-chat`. |
 | `noJsonSchemaModels?` | `string[]` | ID de modèle exact dont le point final `openai-chat` rejette un `response_format` `json_schema` mais accepte encore `json_object`. Une telle requête est rétrogradée vers `json_object` au lieu d’être supprimée, donc un appelant qui demande du JSON en reçoit toujours. `noStructuredOutputModels` l’emporte quand un modèle figure dans les deux listes. Les préréglages `opencode go`, `opencode zen` et `opencode free` l’embarquent pour leurs routes DeepSeek. |
+| `foldDeveloperRoleToSystem?` | `boolean` | Indique si une destination `openai-chat` accepte le rôle `developer`. `foldDeveloperRoleToSystem` non défini envoie `system`, `true` envoie `system` et `false` envoie `developer`. Non défini signifie que rien n'a été enregistré pour cette destination ; `true` enregistre un service en amont qui refuse le rôle ; `false` en enregistre un qui l'accepte. Dans tous les cas le message conserve sa position dans la conversation ; seul le rôle change. Une destination qui refuse le rôle répond `400 role 'developer' is not allowed` et le tour ne démarre pas, d'où l'état non enregistré replié par défaut. |
 | `parallelToolCalls?` | `boolean` | Contrôler les appels d’outils parallèles. Pour `openai-chat`, ils sont activés par défaut ; `false` envoie explicitement `parallel_tool_calls: false`. Les autres adaptateurs ne les annoncent que lorsque la valeur vaut explicitement `true`. |
 | `terminalContinuationGuard?` | `boolean` | Active, pour un fournisseur `openai-chat`, une relance interne bornée lorsqu’un tour exploitable annonce une action puis s’arrête proprement sans appel d’outil. La valeur par défaut est `false`, et une valeur explicite `false` équivaut à l’absence du champ. Les tentatives de combinaison et les tours de compactage routés sont exclus ; les autres adaptateurs ignorent cette option. |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | Réparation SSE en aval désactivée par défaut pour les identifiants d'espace réservé exacts, les identifiants de terminal manquants et (avec `repairInvalidIds`) les identifiants message/reasoning manquant du préfixe canonique `msg_`/`rs_`. Les identifiants d’appel de fonction ne sont jamais réécrits. Le DeepSeek intégré active les deux derniers par défaut. |
 | `responsesSnapshotRepair?` | `boolean` | Réparation côté client désactivée par défaut pour les instantanés du cycle de vie des réponses clairsemés dans SSE et JSON. Remplit les métadonnées d'état canonique, de sortie et d'outil manquantes tandis que l'inspection brute et la persistance restent inchangées. |
 | `retryOn429?` | `{ enabled?: boolean; attempts?: number; intervalMs?: number; maxIntervalMs?: number; respectRetryAfter?: boolean }` | Fournisseurs à clé API uniquement (`authMode: "key"`). Nouvelle tentative facultative sur la même cible après un 429 : lorsque `retryOn429` est absent, la fonctionnalité est désactivée ; la présence d'un objet l'active, sauf avec `enabled: false`. Après un 429, le proxy attend selon `Retry-After` reçu en amont ou selon l'intervalle fixe, puis relit la requête à l'identique avec la même clé avant tout basculement de clé. Ce comportement couvre la boucle principale de récupération d'un tour textuel, le protocole de transfert Responses, le pont d'images et de vidéos, le service auxiliaire de recherche Web et les continuations du terminal. Seules les réponses HTTP 429 reçues avant le début de la diffusion peuvent être relues ; les transports `runTurn` personnalisés ne font pas partie de la boucle de nouvelle tentative HTTP. `attempts` compte les relectures avec la même clé après le premier 429, soit `attempts` + 1 envois au total, et constitue un budget commun à toute la requête, partagé entre la boucle principale de récupération, la continuation de la garde du terminal et les nouvelles tentatives du pont. L'épuisement de `attempts` arrête uniquement les relectures supplémentaires avec la même clé : le basculement normal de clé ou la gestion de l'erreur finale s'applique ensuite selon les cibles disponibles. Sur le protocole de transfert authentifié par clé, aucun basculement n'est possible ; le 429 final est donc renvoyé sans modification. Codex ne retente jamais lui-même une requête après un 429 : cette option constitue ainsi la seule protection pour les fournisseurs à clé unique. Valeurs par défaut : `enabled: true`, `attempts: 3`, `intervalMs: 5000`, `maxIntervalMs: 60000` (chaque attente est plafonnée à `maxIntervalMs`, lui-même plafonné à 600000), `respectRetryAfter: true`. |
 | `transientRetryOn5xx?` | `{ enabled?: boolean; attempts?: number }` | Fournisseurs `openai-chat` et `openai-responses` authentifiés par clé uniquement. Les fournisseurs `authMode: "forward"` (le pool de comptes ChatGPT) ne lisent jamais cette option et conservent l'échelle par défaut. Nouvelle tentative facultative pour les états transitoires reçus en amont avant le début de la diffusion (500, 502, 503, 504, 520, 521, 522) : l'absence de l'option la désactive ; la présence d'un objet l'active, sauf avec `enabled: false`. Ce comportement couvre la requête Responses initiale, la continuation de la garde du terminal, le point de terminaison natif `/v1/chat/completions` et les réémissions liées à la récupération après un 429 ou à la récupération de compte. `attempts` représente le nombre TOTAL d'envois en amont autorisés pour une requête, premier envoi compris (de 1 à 10, valeur par défaut : 3). Il constitue un budget commun à la requête, partagé avec la récupération après une réinitialisation de connexion ; ainsi, `3` signifie qu'au plus trois requêtes réelles atteignent le fournisseur. Les attentes utilisent une temporisation exponentielle à base fixe de 400 ms, plafonnée à 5 s, et respectent `Retry-After`. Cette option est distincte de `retryOn429`, qui traite la limitation de débit ; les échecs en cours de diffusion ne sont jamais relus. |
+| `retryOnReset?` | `{ enabled?: boolean; replacements?: number }` | Fournisseurs `openai-responses` natifs uniquement, `authMode: "forward"` compris. Remplacement facultatif d'un envoi qui a échoué alors que l'appelant n'avait rien observé : l'absence de l'option la désactive ; la présence d'un objet l'active, sauf avec `enabled: false`. Couvre les deux étapes ambiguës — une connexion rompue avant tout en-tête de réponse, et un corps SSE rompu après l'en-tête alors qu'il ne portait que des événements de contrôle. Seule une requête autonome est remplacée : `store: false`, `input` complet, ni `previous_response_id`, ni `conversation`, ni `stream_id`, et uniquement des outils exécutés par le client. `replacements` est le nombre d'envois de remplacement qu'UNE requête logique peut effectuer, toutes étapes et tous enfants de combo confondus (de 1 à 2, valeur par défaut : 1). Ce n'est ni un nombre de tentatives par étape ni un budget d'envoi : un remplacement doit toujours tenir dans l'allocation d'envois dont l'étape disposait déjà. Une requête qui a déjà émis une sortie ou un appel d'outil n'est jamais remplacée, quelle que soit cette valeur. L'inférence de remplacement peut tout de même être facturée si l'origine avait déjà démarré la première, d'où la désactivation par défaut. |
 | `autoToolChoiceOnlyModels?` | `string[]` | Modèles dont `tool_choice` accepte uniquement `auto` ou `none` ; les choix forcés sont dévalorisés. |
 | `preserveReasoningContentModels?` | `string[]` | Modèles nécessitant un assistant préalable `reasoning_content` dans l'historique des discussions. |
 | `reasoningDetailsModels?` | `string[]` | Modèles dont le point de terminaison renvoie la réflexion sous forme de tableau structuré `reasoning_details` (MiniMax série M avec `reasoning_split`) ; les deltas de flux sont des instantanés cumulatifs comparés par préfixe, et la réflexion conservée est rejouée sous forme de tableau `reasoning_details` plutôt que de chaîne `reasoning_content`. |
diff --git a/docs-site/src/content/docs/getting-started/installation.md b/docs-site/src/content/docs/getting-started/installation.md
index c5a7d36578e..9ff7e5a72c6 100644
--- a/docs-site/src/content/docs/getting-started/installation.md
+++ b/docs-site/src/content/docs/getting-started/installation.md
@@ -49,6 +49,19 @@ ocx --version
 opencodex --version
 ```
 
+## Standalone binary (no npm)
+
+Release downloads also include a standalone `ocx` binary for supported macOS, Linux, and Windows
+targets. It includes the Bun runtime and dashboard, so npm, Node, and a separate Bun installation
+are not required. Download the archive for your platform, extract it, and run:
+
+```bash
+./ocx --version
+./ocx start
+```
+
+The extracted `gui/dist` directory must stay beside the binary so `GET /` can serve the dashboard.
+
 ### Release channels
 
 The stable `latest` channel already includes GPT-5.6 Sol/Terra/Luna catalog support for ChatGPT,
diff --git a/docs-site/src/content/docs/getting-started/quickstart.md b/docs-site/src/content/docs/getting-started/quickstart.md
index 042eb183045..a673daf5e82 100644
--- a/docs-site/src/content/docs/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/getting-started/quickstart.md
@@ -5,6 +5,11 @@ description: Configure your first provider and route OpenAI Codex through openco
 
 This guide takes you from a fresh install to running Codex against a non-OpenAI model.
 
+## Standalone binary (no npm)
+
+You can also use a release archive containing the `ocx` binary and Bun runtime without npm.
+Extract it with its `gui/dist` directory beside the binary, then run `./ocx start`.
+
 ## 1. Run the setup wizard
 
 ```bash
@@ -13,7 +18,7 @@ ocx init
 
 `ocx init` walks you through:
 
-1. **Pick a provider** — choose one of the 95 built-in registry presets or `custom` to type a base
+1. **Pick a provider** — choose one of the 96 built-in registry presets or `custom` to type a base
    URL and adapter.
 2. **API key** — paste a key, or reference an environment variable like `${ANTHROPIC_API_KEY}`.
 3. **Default model** — for key, local, and custom providers, accept the preset or enter a model id.
diff --git a/docs-site/src/content/docs/guides/claude-code.md b/docs-site/src/content/docs/guides/claude-code.md
index 89078ca1f6d..83da2dad162 100644
--- a/docs-site/src/content/docs/guides/claude-code.md
+++ b/docs-site/src/content/docs/guides/claude-code.md
@@ -135,9 +135,73 @@ the proxy starts or you save settings, while `ocx claude` always resolves live.
 
 ## System environment integration (macOS)
 
-## Claude Desktop profile
+## Claude Desktop modes: first-party (default) and gateway
 
-Claude Desktop uses a separate profile from Claude Code. Open **Claude → Desktop** in the
+Claude Desktop can use OpenCodex in one of two mutually exclusive modes. Pick it in
+**Claude → Desktop → Connection mode** in the dashboard or with `ocx claude desktop apply
+--first-party|--gateway`.
+
+**First-party** is the default for new installs. Desktop itself is not reconfigured: it stays
+signed in to claude.ai, and the Chat tab, connectors, cloud sessions and remote control keep
+working. OpenCodex only writes two variables into the `env` block of `~/.claude/settings.json`
+(honoured by `CLAUDE_CONFIG_DIR`):
+
+```json
+{
+  "env": {
+    "HTTPS_PROXY": "http://127.0.0.1:10200",
+    "NODE_EXTRA_CA_CERTS": "<home>/.opencodex/claude-intercept/ca.pem"
+  }
+}
+```
+
+Claude Code — the process Desktop spawns for its Code tab, every subagent it launches, and the
+standalone `claude` CLI — reads that env and sends its `api.anthropic.com` traffic through the
+local intercept proxy. The proxy listens on the public port + 100 (`claudeCode.intercept.port`
+overrides it), terminates TLS with a per-install CA stored under `~/.opencodex/claude-intercept/`
+(never installed into the OS trust store; only Node processes that read `NODE_EXTRA_CA_CERTS`
+trust it), and hands `POST /v1/messages` and `POST /v1/messages/count_tokens` to the same
+Messages handler `ocx claude` uses. Every other path on `api.anthropic.com` (OAuth, profile,
+usage) is relayed byte-for-byte to Anthropic, and unrelated hosts are tunnelled untouched, so your
+subscription login keeps working. Existing OpenCodex features — `modelMap`, aliases, native
+passthrough, sidecars, auto-context — apply the same way they do for `ocx claude`.
+
+**Gateway** is the previous third-party mode: the profile described in the next section switches
+the whole app to OpenCodex as its inference gateway. Chat runs locally through OpenCodex and the
+claude.ai-only features are unavailable. Select it explicitly (`--gateway`, the dashboard
+selector, or the legacy `--static` / `--hybrid` / `--discovery-only` flags, which imply it).
+
+Mode is persisted as `claudeCode.desktopMode`. Installs that already applied a gateway profile
+keep gateway after updating; nothing is switched silently. Switching in either direction removes
+the other mode's configuration (only values OpenCodex wrote — a foreign `HTTPS_PROXY` or
+`NODE_EXTRA_CA_CERTS`, for example a corporate proxy, is never overwritten and the apply is
+refused instead). Fully quit and reopen Desktop after switching. `ocx ensure` refreshes a stale
+first-party env when the integration is ON and removes it when OFF. Set
+`claudeCode.intercept.enabled: false` to disable the proxy entirely; first-party then cannot be
+applied and an implicit apply falls back to gateway. On a connected client the proxy runs on the
+hub, so `ocx claude desktop apply` there uses the gateway profile.
+
+### Claude Code CLI compatibility
+
+The same `settings.json` env drives the standalone `claude` CLI, so a first-party apply also
+covers terminal sessions, `claude -p`, and subagents without `ocx claude`'s
+`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` shell env. Differences from `ocx claude`:
+
+- Model discovery (`/model` → "From gateway") is not available; Claude Code only queries
+  `GET /v1/models` on a configured gateway. Use `modelMap` to route the built-in Anthropic model
+  ids, or type an alias directly.
+- `ANTHROPIC_SMALL_FAST_MODEL` and `CLAUDE_CODE_SUBAGENT_MODEL` are chosen by the CLI before the
+  request is sent; set them in `settings.json` yourself if a sidecar or subagent should use a
+  mapped id.
+- `ocx claude` and first-party coexist: a session started with `ocx claude` talks to
+  `ANTHROPIC_BASE_URL` (plain HTTP on loopback), which `HTTPS_PROXY` does not cover, so that
+  process reaches OpenCodex directly and the proxy simply sees no traffic from it.
+- Claude Code honours `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` as documented for corporate proxies;
+  a CLI release that stops doing so would stop routing, not break login.
+
+## Claude Desktop profile (gateway mode)
+
+The profile below is written only in gateway mode. Claude Desktop uses a separate profile from Claude Code. Open **Claude → Desktop** in the
 dashboard to place each available route in one of four families: Opus, Fable, Sonnet, or Haiku.
 All routes start in Opus on a new profile. The first Opus route becomes the initial overall
 default, and every non-empty family always has one family default.
@@ -161,9 +225,10 @@ ocx claude desktop export <path|->
 ocx claude desktop import <path> [--apply]
 ```
 
-`ocx claude desktop` and `apply` both write the current profile to Claude Desktop. `show` gives a
-readable summary; `status` reports the applied profile, drift, request activity, and Windows
-managed-policy health. Add `--json` for scripts. `export -` writes versioned JSON to standard output.
+`ocx claude desktop` and `apply` apply the selected mode: first-party writes the Claude Code proxy
+env, gateway writes the current profile to Claude Desktop. `show` gives a
+readable summary; `status` reports the effective mode, the applied profile or proxy env, drift,
+request activity, and (gateway mode only) Windows managed-policy health. Add `--json` for scripts. `export -` writes versioned JSON to standard output.
 Import validates the complete file before saving, so an invalid file leaves the current profile
 unchanged. Add `--apply` to write a valid imported profile to Desktop immediately. Use `none` only
 for an empty family; every non-empty family must keep one default.
@@ -637,6 +702,9 @@ Claude debug immediately clears the ring.
 The dashboard sidebar has a dedicated **Claude** page (below API) and a **Claude ON** toggle
 (label intentionally identical in every language). The page shows:
 
+- Desktop tab: **Connection mode** selector — first-party (default) or gateway — with the
+  running proxy port in first-party mode. Only **Save & apply** switches modes; **Save** alone
+  stores the gateway profile lanes for a later gateway apply and leaves the current mode as is
 - Inbound kill switch (enabled toggle)
 - Quickstart (`ocx claude`) and manual env block
 - Fast Mode selector (Auto / ON / OFF)
@@ -708,12 +776,16 @@ route. Pass `"haiku"` as the model placeholder.
 
 Set `claudeCode.stabilizePromptCache` to `true` in `config.json` to relocate supported trailing Claude harness notices from system instructions to a trailing user message on translated routes. The default is `false`. Enable it only when this role change is appropriate for your clients. It preserves fenced examples and unmatched text; native Anthropic passthrough is unchanged. The metadata-less prompt-cache key then follows stabilized instructions. This does not create conversation identity or guarantee upstream cache hits.
 
-On OpenCode Go's `deepseek-v4.1-flash` Chat route, translated timeline system
-reminders automatically retain their position and system role, after any pending
-tool results. This prevents newly appended reminders from rewriting the leading
-system prompt. It applies with or without `stabilizePromptCache`; other models
-and destinations keep their existing conversion; native Anthropic passthrough
-is unchanged. Cache reuse still requires stable session identity and upstream
-cache availability. Changes to earlier instructions or tools, and conversation
-compaction, can still affect cache hits; preserving reminder order alone does
-not guarantee reuse.
+On every translated Chat route, timeline reminders keep their position in the
+conversation, after any pending tool results. This prevents a newly appended
+reminder from rewriting the leading system prompt, and stops a mid-conversation
+instruction from arriving ahead of the turns it was written to follow. The role
+that slot carries is decided separately: a reminder is sent as `system` unless
+the provider records `foldDeveloperRoleToSystem: false`, which states that the
+upstream accepts the `developer` role and forwards it in the same position. An
+upstream that does not accept it answers `400 role 'developer' is not allowed`
+and the turn never starts, so an unrecorded destination folds. This applies with or without
+`stabilizePromptCache`, and native Anthropic passthrough is unchanged. Cache
+reuse still requires stable session identity and upstream cache availability.
+Changes to earlier instructions or tools, and conversation compaction, can still
+affect cache hits; preserving reminder order alone does not guarantee reuse.
diff --git a/docs-site/src/content/docs/guides/codex-integration.md b/docs-site/src/content/docs/guides/codex-integration.md
index 66e28cb9ab2..6513400b4a6 100644
--- a/docs-site/src/content/docs/guides/codex-integration.md
+++ b/docs-site/src/content/docs/guides/codex-integration.md
@@ -35,9 +35,9 @@ Codex's built-in `openai` provider id and points that provider at opencodex:
 ```toml
 # root keys, before the first table
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 openai_base_url = "http://127.0.0.1:10100/v1"
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 experimental_realtime_ws_base_url = "http://127.0.0.1:10100/v1"
 
 # only when fastMode is set; unset adds no [features] table
@@ -299,7 +299,7 @@ model_provider = "opencodex"
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
 
 # appended at the end of the file
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 [model_providers.opencodex]
 name = "OpenCodex Proxy"
 base_url = "http://your-host:10100/v1"
@@ -720,6 +720,22 @@ See [The parser and bridge](/reference/architecture/#the-parser) for the explici
 There is no provider-level setting that can add a missing `tool_search` declaration; ordinary
 code-mode discovery remains a separate path.
 
+### Cache-read diagnostics
+
+Set `OPENCODEX_CACHE_DEBUG=1` before starting the proxy to write one diagnostic record per
+finalized request to `<config-dir>/cache-debug.jsonl`. The switch is off by default; set it to `0`
+or remove it to disable capture. The file is owner-only (`0600`) in the hardened config directory
+and rolls after 200 lines, retaining the newest 100.
+
+Each JSONL record contains the protocol, routed provider/model, cache-counter presence and
+provenance, process-local equality tags for the account, prompt-cache key, and allowlisted session
+headers, plus ordered fingerprints for instructions, tools, and message/input blocks. Prefix
+sections retain at most 128 tags and identify only the first divergent section/index. The
+diagnostic never stores prompt or message text, tool names, raw headers, raw cache/session/account
+identifiers, or a durable tag derived from them. Its random HMAC key is created at process start,
+separate from other debug keys, and is never persisted; tags therefore compare values only within
+one proxy process.
+
 ### Catalog troubleshooting
 
 If a model is missing from Codex, or the catalog order/visibility looks wrong, check in order:
@@ -903,7 +919,9 @@ When an affected history store supports paginated records, a provider transition
 
 When returning to the root-override form, OpenCodex retains an existing `[model_providers.opencodex]` definition before committing the configuration, even if history preflight currently passes. This keeps older `opencodex` conversations resolvable if Codex migrates history after that commit or while the background worker starts. New conversations still use the selected root provider; explicit restore keeps its separate removal guards.
 
-`ocx restore` and Codex config removal still refuse on `history_paginated_requires_native_writer`. Stripping the `[model_providers.opencodex]` definition while thread rows still reference it would make those conversations unresolvable, and the restore path has no way to keep a compatibility provider table. A home that is already paginated cannot currently be uninstalled through the product; that is known open work rather than intended behaviour.
+`ocx restore`, `ocx stop` and `ocx uninstall` no longer refuse on `history_paginated_requires_native_writer`. They take every OpenCodex root routing key out and keep the `[model_providers.opencodex]` definition on disk, so conversations whose rows still name that provider keep resolving while plain `codex` stops pointing at the proxy. The result is reported as a partial restore that names the retained lines, and `ocx restore --remove-codex-provider-table` removes them too, after which those conversations stop opening.
+
+Enabling the integration in its provider-table form on a home whose `openai`-tagged conversations Codex has already paginated used to be refused outright with `history_paginated_openai_requires_native_writer`: nothing was written and the integration stayed disabled. OpenCodex now completes that transition by keeping the managed root `openai_base_url` override beside the `[model_providers.opencodex]` table. Codex merges the override onto its built-in `openai` provider, so those conversations keep reaching the proxy without being relabeled and no rollout byte or thread row is touched. Only a routing form that requires the `x-opencodex-api-key` admission header still refuses, because Codex's built-in provider cannot carry that header; its message names the two settings that resolve it — route Codex through the loopback listener so the override can be retained, or set `syncResumeHistory` to `false` to accept that those conversations resume against Codex's own OpenAI endpoint.
 
 Do not rewrite an active paginated rollout or thread row to migrate those conversations yourself. Close the affected conversation before any recovery, and report the exact error and versions without uploading private history. A backup or a successful script alone does not prove the conversation is visible again. Check the restored conversation in Codex after reopening.
 
diff --git a/docs-site/src/content/docs/guides/desktop-app.md b/docs-site/src/content/docs/guides/desktop-app.md
new file mode 100644
index 00000000000..c1405fc0c29
--- /dev/null
+++ b/docs-site/src/content/docs/guides/desktop-app.md
@@ -0,0 +1,84 @@
+---
+title: Desktop App
+description: Install and use the OpenCodex desktop app on macOS, Windows, and Linux.
+---
+
+The OpenCodex desktop app combines a native tray with the web dashboard. It discovers an
+existing local proxy, or starts the bundled `ocx` sidecar when no proxy is running.
+
+The dashboard remains available at [http://127.0.0.1:10100](http://127.0.0.1:10100).
+The desktop app does not replace the proxy; it is a local shell around the dashboard and
+its bundled runtime.
+
+## Install
+
+### macOS
+
+Download `OpenCodex-<version>-macos.dmg` from the
+[latest release](https://github.com/lidge-jun/opencodex/releases). Open the DMG and drag
+`OpenCodex.app` to Applications.
+
+On first launch, macOS Gatekeeper may warn that the developer cannot be verified. Right-click
+the app, choose **Open**, and confirm **Open**. This build is signed for integrity but is not
+yet notarized.
+
+### Windows
+
+Download `OpenCodex-<version>-windows-x64.msi` and run the installer. Windows SmartScreen may
+warn because the installer is not yet code-signed; choose **More info → Run anyway** after
+confirming that you downloaded it from the release page.
+
+### Linux
+
+Download `OpenCodex-<version>-linux-x86_64.AppImage` or
+`OpenCodex-<version>-linux-amd64.deb` from the release page.
+
+For the AppImage:
+
+```bash
+chmod +x OpenCodex-<version>-linux-x86_64.AppImage
+./OpenCodex-<version>-linux-x86_64.AppImage
+```
+
+For Debian-based distributions:
+
+```bash
+sudo apt install ./OpenCodex-<version>-linux-amd64.deb
+```
+
+The tray icon requires an AppIndicator-capable desktop environment.
+
+## First launch
+
+The app first looks for an existing `ocx` proxy on loopback, using the runtime port
+metadata when available and falling back to port `10100`. If no proxy answers, it starts
+the bundled sidecar. The dashboard is then opened inside the app's webview.
+
+Use the tray's **Open dashboard** or **Open in browser** action to move between the
+embedded dashboard and your normal browser. The tray also provides update checks.
+
+## Updates
+
+Choose **Check for Updates…** in the tray menu to check immediately. Release builds also
+check automatically after startup and every six hours. Updates are verified with the
+project's signed updater public key before installation. On macOS, in-app updates download
+`OpenCodex-<version>-macos.app.tar.gz`; the DMG is for the first installation.
+The release manifest is generated only when the updater key secret is configured and then
+requires all four platforms to be signed.
+
+## Widget
+
+The macOS app includes the OpenCodex WidgetKit extension. See the
+[macOS Menu Bar App guide](/opencodex/guides/macos-menu-bar/) for widget setup and the
+privacy-safe snapshot details.
+
+## Uninstall
+
+On macOS, drag `OpenCodex.app` from Applications to the Trash. On Windows, remove
+OpenCodex from **Installed apps**. On Debian-based Linux systems, run:
+
+```bash
+sudo apt remove opencodex
+```
+
+For an AppImage, delete the downloaded file.
diff --git a/docs-site/src/content/docs/guides/integrations.md b/docs-site/src/content/docs/guides/integrations.md
index 32263f12a67..2b32b59122e 100644
--- a/docs-site/src/content/docs/guides/integrations.md
+++ b/docs-site/src/content/docs/guides/integrations.md
@@ -375,6 +375,32 @@ catalogs are refused; the existing explicit overwrite and drift-confirmation con
 available. Fully quit and reopen Aside to load changed model files.
 
 
+## ZCode 3.14 and later
+
+ZCode 3.14 moved its custom providers to `~/.zcode/v2/provider_config.json` and left
+`~/.zcode/v2/config.json` reachable only through a one-shot import that runs when the new file is
+missing. ZCode creates the new file the first time it runs, so on any install that has ever been
+launched the import is already spent and a write to `config.json` reaches nothing.
+
+opencodex writes `provider_config.json` directly where it can. Enabling the integration adds the
+`opencodex` provider rule to that file, a catalog refresh updates it, and disabling removes exactly
+what opencodex put there. Every other rule in the file is left alone, including a rule another
+provider keeps for a model id that also appears under ours. A rule carrying the `opencodex` id that
+opencodex did not write is a conflict rather than something to take over; resolve it in ZCode, or
+use the explicit overwrite.
+
+Two situations still refuse rather than write. A block opencodex applied before ZCode moved its
+store keeps the integration on `config.json`: disable it there first, then enable it again to write
+the new store. And a `provider_config.json` whose `schemaVersion` is not one opencodex has observed
+is reported rather than merged into, because that file holds every provider ZCode has and asserting
+a shape into it would trade a silent no-op for a silent loss. Status names the file ZCode reads
+whenever the integration is not writing it.
+
+In that second case, add the provider in ZCode's own settings: base URL
+`http://127.0.0.1:10100/v1` (adjust the port to your bind), any non-empty key, and the model ids
+from `ocx export --client zcode`. Deleting `provider_config.json` to re-trigger ZCode's import is
+not supported — it discards every provider ZCode keeps there.
+
 ## Cline CLI
 
 This integration targets Cline's current CLI/shared SDK provider store, whose native schema has
diff --git a/docs-site/src/content/docs/guides/macos-menu-bar.md b/docs-site/src/content/docs/guides/macos-menu-bar.md
new file mode 100644
index 00000000000..c95888a716e
--- /dev/null
+++ b/docs-site/src/content/docs/guides/macos-menu-bar.md
@@ -0,0 +1,171 @@
+---
+title: macOS Menu Bar App
+description: A native menu bar companion that shows OpenCodex proxy status, usage, and provider quotas at a glance.
+---
+
+The macOS companion puts OpenCodex in your menu bar: proxy health, recent usage, and
+per-provider quota pressure, without opening the dashboard.
+
+It is a separate application from the proxy. `ocx` keeps running as it always has; the
+companion is a read-mostly client that talks to the local management API.
+
+## Desktop app (Tauri)
+
+The same dashboard can run inside the OpenCodex desktop app. The Usage companion panel
+uses the OS selector to show the matching macOS, Windows, or Linux installation steps.
+While the dashboard is inside the desktop shell, choose **Open in browser** to open the
+current dashboard view in your normal browser.
+
+## Install
+
+Install the desktop app from the
+[latest release](https://github.com/lidge-jun/opencodex/releases). On macOS, download
+`OpenCodex-<version>-macos.dmg`, open it, and drag `OpenCodex.app` to Applications.
+Windows users can run `OpenCodex-<version>-windows-x64.msi`; Linux users can use the
+AppImage or `OpenCodex-<version>-linux-amd64.deb`.
+
+```bash
+chmod +x OpenCodex-<version>-linux-x86_64.AppImage
+sudo apt install ./OpenCodex-<version>-linux-amd64.deb
+```
+
+## First launch: Gatekeeper
+
+**The first launch will be blocked.** macOS will say:
+
+> "OpenCodex.app" cannot be opened because the developer cannot be verified.
+
+This is expected, and it is worth explaining rather than talking you past it. Gatekeeper
+wants a Developer ID signature and a notarization ticket from Apple, both of which
+require a paid Apple Developer account. OpenCodex does not have one, so the app ships
+ad-hoc signed: the bundle is intact and its signature is valid, but Apple has not
+vouched for the publisher.
+
+To open it anyway:
+
+1. Right-click (or Control-click) `OpenCodex.app` in Finder.
+2. Choose **Open**.
+3. Click **Open** in the dialog that appears.
+
+If that dialog does not offer an Open button, go to **System Settings → Privacy &
+Security**, find the blocked-app notice, and click **Open Anyway**.
+
+macOS remembers the decision, so this is a one-time step per version.
+
+Alternatively, remove the quarantine attribute from the terminal:
+
+```bash
+xattr -d com.apple.quarantine /Applications/OpenCodex.app
+```
+
+If you would rather not do either, build from source — a local build carries no
+quarantine attribute at all. See [Build from source](#build-from-source).
+
+## What it shows
+
+The menu bar icon reflects proxy state without using colour, since macOS menu bar items
+are monochrome by convention:
+
+| Icon | Meaning |
+| --- | --- |
+| Solid mark | Running and protected |
+| Solid mark with a notch | Running, but routing protection is at risk |
+| Outlined mark | Starting up, or degraded |
+| Faded outline | Not running, or needs an API key |
+
+Clicking it opens a panel with four sections:
+
+**Status** — whether the proxy is running, the loopback endpoint the app is using, and
+the protection state. When the proxy recommends a remediation command (for example
+`ocx service install`), it appears here as selectable text. The app never runs it for
+you.
+
+**Usage** — requests, tokens, and estimated cost over the last 7 days, with a daily
+trend. A `~` after the request count means part of it is estimated rather than reported
+by the provider.
+
+By default, the menu bar headline shows total tokens; change the headline metric in the
+dashboard Usage companion settings when you prefer requests, cost, quota, or an icon only.
+On macOS 26, the popover and widgets adopt Liquid Glass; earlier macOS versions use the
+standard popover material.
+
+**Quotas** — one row per provider, showing the window under the most pressure. A
+provider at 99% of a five-hour limit and 10% of its monthly limit shows the five-hour
+figure, because that is the one currently blocking you. The window name is printed under
+the provider so `42% of API usage` and `42% of a month` are never confused.
+
+**Providers** — a collapsible list with a switch per provider. The default provider's
+switch is inert while it is enabled, because the proxy refuses to disable it; choose a
+different default in the dashboard first.
+
+## What it can do
+
+- **Dashboard** opens the web dashboard in your browser.
+- **Stop proxy** stops the proxy, after confirming. This is deliberately not called
+  "Restart": stopping also stops the launchd service, so nothing brings the proxy back
+  automatically. The panel then shows the command to start it again.
+- **Provider switches** enable or disable a provider.
+
+Everything else — accounts, model configuration, storage — stays in the dashboard.
+
+## Widget
+
+Add the widget from the desktop: right-click, choose **Edit Widgets**, then add
+**OpenCodex**. It shows proxy status, today's usage, quota pressure, and the same
+privacy-safe usage snapshot as the desktop app. The widget refreshes when the app polls.
+It requires macOS 14 or later and reads only the privacy-safe snapshot written by the
+OpenCodex app; it does not receive API keys or raw account data.
+
+## Connecting to the proxy
+
+The app finds the proxy automatically. It reads `~/.opencodex/runtime-port.json` (or
+`$OPENCODEX_HOME/runtime-port.json`) and falls back to port `10100`. Only the port is
+taken from that file; the host is always loopback.
+
+If your proxy is bound to a non-loopback address it will require an API key. The panel
+says so and offers a link to the dashboard.
+
+**This case is not supported yet.** The app reads a key from the macOS Keychain and
+retries once with it, but there is no UI for entering one and no supported way to
+provision it by hand — the item is a data-protection Keychain entry, which Keychain
+Access does not create. So on a non-loopback bind the panel stays on "Needs API key".
+
+A loopback proxy — the default — needs no key at all. Native key entry is planned.
+
+## Polling
+
+The app is deliberately quiet. It checks whether the proxy is alive every 5 seconds, and
+fetches the expensive aggregate data — usage and quotas — only while the panel is open,
+at most once a minute. After three consecutive failures it backs off to every 30 seconds
+rather than hammering a proxy you stopped on purpose.
+
+## Build from source
+
+Requires macOS 13 or later, the Xcode Command Line Tools, and [Bun](https://bun.sh):
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+bun run prepare-sidecar
+bun run prepare-widget
+bunx tauri build
+```
+
+The bundle appears in Tauri's release output, with the WidgetKit appex under
+`OpenCodex.app/Contents/PlugIns/`.
+
+Building a universal binary (`UNIVERSAL=1`) needs the full Xcode toolchain — Command
+Line Tools ships only current-architecture Swift compatibility libraries, and the build
+will tell you so rather than failing with a linker error.
+
+If you have a Developer ID certificate in your keychain, set `MACOS_SIGN_IDENTITY` to
+sign with the hardened runtime instead of ad-hoc:
+
+```bash
+MACOS_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" bun run prepare-widget
+```
+
+## Uninstall
+
+Drag `OpenCodex.app` to the Trash. The app writes no preferences or state of its own, and
+stores nothing in the Keychain today.
diff --git a/docs-site/src/content/docs/guides/pi.md b/docs-site/src/content/docs/guides/pi.md
index d7b9e3c3edf..99f44144f9b 100644
--- a/docs-site/src/content/docs/guides/pi.md
+++ b/docs-site/src/content/docs/guides/pi.md
@@ -146,14 +146,17 @@ An explicit reasoning effort of `none` survives Chat conversion. Output limits a
 controls are preserved for generic API-key Responses targets; the canonical ChatGPT target
 still applies its own restrictions. This does not make all providers' controls equivalent.
 
-**Audio and files need a native input wire that supports them.** OpenCodex does not yet have
-a lossless audio/file carrier for translated requests. When Chat requires projection, or a
-Responses request targets a translated adapter, recognized audio/file attachments return an
-explicit error rather than succeeding without the attachment. File-ID-only images have the
-same restriction because translated adapters cannot resolve those IDs. Convert the attachment
-to text first, or use a native wire and model that support it. Native Chat and raw Responses
-(including Azure) retain their existing behavior; this is not a promise of every model's
-upstream media support. Video conversion limits remain adapter-specific.
+**Audio and most file attachments need a native input wire that supports them.** A document
+that carries its own base64 bytes in a user message is the exception: it survives translation
+and reaches the Anthropic, OpenAI Chat and Google wires as a native document, file part and
+inline data part. Everything else still returns an explicit error rather than succeeding
+without the attachment — audio, a file-ID or remote reference the proxy cannot dereference, an
+attachment in a tool output or a system message, and a document routed to a wire with no byte
+carrier. File-ID-only images have the same restriction because translated adapters cannot
+resolve those IDs. Convert the attachment to text first, or use a native wire and model that
+support it. Native Chat and raw Responses (including Azure) retain their existing behavior;
+this is not a promise of every model's upstream media support. Video conversion limits remain
+adapter-specific.
 
 ## Schema status
 
diff --git a/docs-site/src/content/docs/guides/providers.md b/docs-site/src/content/docs/guides/providers.md
index cd5b5c8b61c..e8cba6c928d 100644
--- a/docs-site/src/content/docs/guides/providers.md
+++ b/docs-site/src/content/docs/guides/providers.md
@@ -198,7 +198,7 @@ ocx logout <provider>
 | --- | --- | --- | --- |
 | `xai` | `openai-chat` | `https://cli-chat-proxy.grok.com/v1` | OAuth uses the separate Grok CLI subscription gateway. The API-key override uses `https://api.x.ai/v1` and may inject Priority Processing. Live-first Grok catalog; `grok-4.5` is the fallback default. |
 | `anthropic` | `anthropic` | `https://api.anthropic.com` | Claude models; live model list fetched from `/v1/models`. |
-| `kimi` | `openai-chat` | `https://api.kimi.com/coding/v1` | Kimi K2.7/K2.6/K2.5 coding models. |
+| `kimi` | `openai-chat` | `https://api.kimi.com/coding/v1` | Kimi Code Plan coding models. Defaults to the stable `kimi-for-coding` alias (currently K2.8 Preview): 1M-token context window, adjustable `low`/`high`/`max` thinking (default `max`), text + image input. Retired `kimi-k2.x` selections are migrated to the alias on upgrade. |
 | `nous` | `openai-chat` | `https://inference-api.nousresearch.com/v1` | Nous Research subscription gateway (same backend Hermes Agent uses). Device-grant login against `portal.nousresearch.com`; the access token is the per-request inference JWT. Mixed paid + `:free` model catalog (`tencent/hy3:free`, `stepfun/step-3.7-flash:free`, ...) discovered live from the signed-in account. Refresh tokens are single-use and rotated on every refresh. |
 | `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | Initial login imports the installed, signed-in `kiro-cli` session (on Unix, install with `curl -fsSL https://cli.kiro.dev/install` &#124; `bash`; on Windows PowerShell, use `irm 'https://cli.kiro.dev/install.ps1'` &#124; `iex`; then run `kiro-cli login`). **Add account** logs `kiro-cli` out, starts a fresh browser login that switches the account used by `kiro-cli`, and stores account-scoped profile metadata. Existing OpenCodex accounts are preserved, and cancellation or failure restores the previous `kiro-cli` session. |
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | Google OAuth over the Cloud Code Assist wire. Live discovery uses CCA's authenticated `v1internal:fetchAvailableModels` endpoint and publishes the agent models available to the signed-in account; the maintained catalog remains the fallback. |
@@ -412,7 +412,7 @@ selectors, then retry. Signing in from a machine with no existing `kiro-cli` ses
 
 ## 3. API-key catalog
 
-opencodex ships 95 built-in presets: 79 key-based, 12 OAuth, three local, and one default
+opencodex ships 96 built-in presets: 80 key-based, 12 OAuth, three local, and one default
 ChatGPT-forward preset. The dashboard's **Add provider** picker opens a key provider's dashboard,
 validates the key, and stores it; validation is provider-specific. Notable entries:
 
@@ -692,7 +692,7 @@ voice models on the same host.
 Two things worth knowing before you pick it. **A Muse Code subscription does not apply
 here:** Meta scopes that credential to the Muse Code CLI and bills any other key
 pay-as-you-go. And the Contributor tier is cheap because Meta trains on your prompts —
-roughly 92% off input, 95% off output, and 99% off cached input — so keep confidential
+roughly 92% off input, 96% off output, and 99% off cached input — so keep confidential
 material off it. Muse Spark is also reachable through resellers, with a narrower roster:
 `command-code` carries both tiers, while `opencode-go` serves only
 `muse-spark-1.3-contributor`.
diff --git a/docs-site/src/content/docs/guides/web-dashboard.md b/docs-site/src/content/docs/guides/web-dashboard.md
index ed8f4cb709c..72c1a821d96 100644
--- a/docs-site/src/content/docs/guides/web-dashboard.md
+++ b/docs-site/src/content/docs/guides/web-dashboard.md
@@ -93,7 +93,7 @@ badge or the version value to read the full value.
 | **Subagents** | Feature up to five bare native or namespaced routed models in the `spawn_agent` override list. |
 | **Models** | Toggle native GPT and routed models, set provider allowlists and context caps, choose v1/base/v2, and configure the v2 thread limit. The page distinguishes a catalog saved on the hub, a catalog fetched by this client, and activation in a running client. A fetch timestamp does not prove it includes the latest hub save, and runtime activation is shown as unverified. Configured providers stay visible as zero-model groups when discovery is off or returns no rows. |
 | **Logs** | Auto-refresh recent requests with tokens, requested effort and (when available) effective outbound effort, resolved model, provider, status, request id, duration, and error details. The detail view includes the exact reasoning wire field when the adapter emits one. Filter by opaque conversation/session id (when the client sends one) to total tokens and estimated list-price cost for the currently loaded Logs ring. |
-| **Usage / Debug** | Inspect token-usage coverage and trends, or enable opt-in provider transport and usage-extraction diagnostics. |
+| **Usage / Debug** | Inspect token-usage coverage and trends. The Usage page's Models table also breaks each model down into input tokens, output tokens, cache hits, cache writes, and cache hit rate; a dash means cache telemetry for that metric is unavailable. Or enable opt-in provider transport and usage-extraction diagnostics. |
 | **Storage** | Read-only CODEX_HOME disk breakdown (sessions, archives, DBs, attachments). Optional archived cleanup: preview the oldest N%, then quarantine to `CODEX_HOME/.trash` (default) or permanently delete behind an explicit checkbox. **Auto-cleanup policy** is opt-in and **default OFF** (`storageCleanupPolicy.enabled`); configure threshold/target/schedule/mode on the Storage page, or trigger **Run now**. Quarantined entries can be restored from the Storage page (JSONL + threads). Active sessions stay read-only. Cleanup and restore are refused while Codex holds the newest/active `state_*.sqlite` locked. |
 | **Stop** | Gracefully stop the proxy and installed background service, restore native Codex, and exit (`POST /api/stop`). On Windows with the Task Scheduler backend the dashboard refuses and asks you to run `ocx stop` instead: that wrapper can respawn the proxy after the task ends, and only a stop running outside this process can verify the restart window before restoring your client config. Nothing is changed when it refuses. |
 
diff --git a/docs-site/src/content/docs/ja/getting-started/installation.md b/docs-site/src/content/docs/ja/getting-started/installation.md
index a62daede0a6..49b50f7d37d 100644
--- a/docs-site/src/content/docs/ja/getting-started/installation.md
+++ b/docs-site/src/content/docs/ja/getting-started/installation.md
@@ -43,6 +43,19 @@ ocx --version
 opencodex --version
 ```
 
+## スタンドアロンバイナリ（npm 不要）
+
+リリースには、対応する macOS、Linux、Windows 向けのスタンドアロン `ocx` バイナリも含まれます。
+Bun ランタイムとダッシュボードが含まれるため、npm、Node、別途の Bun インストールは必要ありません。
+お使いの環境向けのアーカイブをダウンロードして展開し、次のように実行します。
+
+```bash
+./ocx --version
+./ocx start
+```
+
+ダッシュボードを提供するため、展開した `gui/dist` ディレクトリはバイナリの隣に置いたままにしてください。
+
 ### 配布チャネル
 
 安定チャネルの `latest` にも ChatGPT、OpenAI API キー、OpenRouter、実験段階の Cursor 経路のための
diff --git a/docs-site/src/content/docs/ja/getting-started/quickstart.md b/docs-site/src/content/docs/ja/getting-started/quickstart.md
index f9184dfc5f6..d9d83201963 100644
--- a/docs-site/src/content/docs/ja/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/ja/getting-started/quickstart.md
@@ -5,6 +5,11 @@ description: 最初のプロバイダーを構成し、3 つのコマンドで O
 
 このガイドでは、新規インストールから非 OpenAI モデルに対して Codex を実行するまでを説明します。
 
+## スタンドアロンバイナリ（npm 不要）
+
+npm を使わず、Bun ランタイムを含むリリースアーカイブの `ocx` バイナリも利用できます。
+`gui/dist` ディレクトリをバイナリの隣に置いて展開し、`./ocx start` を実行してください。
+
 ## 1. セットアップウィザードを実行します
 
 ```bash
@@ -13,7 +18,7 @@ ocx init
 
 `ocx init` では次の手順を説明します。
 
-1. **プロバイダーを選択してください** — 95 個の組み込みレジストリプリセットのいずれか、または `custom` を選択してベース URL とアダプターを入力します。
+1. **プロバイダーを選択してください** — 96 個の組み込みレジストリプリセットのいずれか、または `custom` を選択してベース URL とアダプターを入力します。
 2. **API キー** — キーを貼り付けるか、`${ANTHROPIC_API_KEY}` のような環境変数を参照します。
 3. **デフォルト モデル** — キー、ローカル、カスタム プロバイダーの場合は、プリセットを受け入れるか、モデル ID を入力します。
 4. **プロキシ ポート** — デフォルトは `10100` です。
diff --git a/docs-site/src/content/docs/ja/guides/claude-code.md b/docs-site/src/content/docs/ja/guides/claude-code.md
index 4dfa380673f..390fbccd054 100644
--- a/docs-site/src/content/docs/ja/guides/claude-code.md
+++ b/docs-site/src/content/docs/ja/guides/claude-code.md
@@ -95,6 +95,29 @@ hook を削除します。Claude Desktop は独立した profile を使用し、
 `claudeCode.nativePassthrough: false` でオフにでき、`claudeCode.anthropicBaseUrl` で別のアドレスを
 指定できます。
 
+## Claude Desktop のモード: 1P（デフォルト）とゲートウェイ
+
+Claude Desktop は排他的な 2 つのモードのどちらかで OpenCodex を使います。ダッシュボードの
+**Claude → Desktop → 接続モード**、または `ocx claude desktop apply --first-party|--gateway` で選びます。
+
+- **1P（ファーストパーティ、デフォルト）**: Desktop 本体は変更しません。claude.ai のログイン、
+  チャットタブ、コネクタ、リモート操作はそのまま動きます。OpenCodex は `~/.claude/settings.json` の
+  `env` に `HTTPS_PROXY=http://127.0.0.1:<公開ポート+100>` と
+  `NODE_EXTRA_CA_CERTS=~/.opencodex/claude-intercept/ca.pem` の 2 つだけを書きます。Desktop が
+  Code タブ用に起動する Claude Code（サブエージェント含む）とターミナルの `claude` CLI だけがこれを読み、
+  ローカルのインターセプトプロキシを通ります。`POST /v1/messages` と `count_tokens` のみ OpenCodex が
+  処理し、他の `api.anthropic.com` パスはそのまま Anthropic に中継されます。CA は OS の信頼ストアには
+  インストールされません。
+- **ゲートウェイ（3P）**: 従来の方式で、下記のプロファイルによりアプリ全体が OpenCodex を
+  ゲートウェイとして使います。`--gateway`（または従来の `--static`/`--hybrid`/`--discovery-only`）で
+  明示的に選びます。
+
+モードは `claudeCode.desktopMode` に保存されます。すでにゲートウェイプロファイルを適用済みの環境は
+更新後もゲートウェイのままで、新規インストールだけが 1P になります。切り替えると他方のモードの設定
+（OpenCodex が書いた値のみ）が削除され、社内プロキシなど外部の `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS`
+は上書きせず適用を拒否します。切り替え後は Desktop を完全に終了して再起動してください。詳細と
+Claude Code CLI 互換性は英語版ドキュメントを参照してください。
+
 ## リモートハブに接続した Claude Desktop
 
 接続中のマシンで `ocx claude desktop apply` または `ocx claude desktop` を実行すると、
@@ -498,4 +521,4 @@ Anthropic バックエンドを明示すると意図的に失敗後停止しま
 
 `config.json` の `claudeCode.stabilizePromptCache` を `true` にすると、変換ルートのシステム指示末尾にある対応済み Claude 通知を最後のユーザーメッセージへ移します。既定値は `false` です。このロール変更が適切なクライアントでのみ有効にしてください。コードフェンス内の例と一致しない本文は保持され、Anthropic のネイティブ転送は変わりません。メタデータがない場合のキャッシュキーは安定化した指示から計算されます。会話 ID の生成やキャッシュヒットの保証は行いません。
 
-OpenCode Go の `deepseek-v4.1-flash` Chat ルートでは、変換されたタイムライン上のシステムリマインダーは、保留中のツール結果の後で位置と system ロールを自動的に維持します。これにより、新しいリマインダーを追加しても先頭のシステムプロンプトが書き換わりません。`stabilizePromptCache` の設定にかかわらず適用され、他のモデルや接続先の変換、および Anthropic のネイティブ転送は変わりません。キャッシュの再利用には、安定したセッション ID と上流キャッシュの利用可能性が引き続き必要です。過去の指示やツールの変更、会話の圧縮もキャッシュヒットに影響します。リマインダーの順序を保つだけで再利用が保証されるわけではありません。
+変換されたすべての Chat ルートで、タイムライン上のリマインダーは保留中のツール結果の後、会話内の元の位置を保ちます。これにより、新しいリマインダーを追加しても先頭のシステムプロンプトが書き換わらず、会話の途中に置かれた指示がそれより前のターンの前に移動することもありません。そのスロットが運ぶロールは別に決まります。プロバイダーが `foldDeveloperRoleToSystem: false` を記録していないかぎり、リマインダーは `system` として送られます。この記録は上流が `developer` ロールを受け付けることを表し、その場合は同じ位置のまま転送します。受け付けない上流は `400 role 'developer' is not allowed` を返してターンが始まらないため、記録のない宛先は畳む側になります。`stabilizePromptCache` の設定にかかわらず適用され、Anthropic のネイティブ転送は変わりません。キャッシュの再利用には、安定したセッション ID と上流キャッシュの利用可能性が引き続き必要です。過去の指示やツールの変更、会話の圧縮もキャッシュヒットに影響します。リマインダーの順序を保つだけで再利用が保証されるわけではありません。
diff --git a/docs-site/src/content/docs/ja/guides/codex-integration.md b/docs-site/src/content/docs/ja/guides/codex-integration.md
index 56c69f388e7..4bd4530decc 100644
--- a/docs-site/src/content/docs/ja/guides/codex-integration.md
+++ b/docs-site/src/content/docs/ja/guides/codex-integration.md
@@ -14,7 +14,7 @@ opencodex は、Codex が読み取る 2 つの内容 (構成 (`$CODEX_HOME/confi
 ```toml
 # root keys, before the first table
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 openai_base_url = "http://127.0.0.1:10100/v1"
 
 # fastMode を設定した場合のみ。未設定なら [features] は作られません
@@ -82,7 +82,7 @@ model_provider = "opencodex"
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
 
 # appended at the end of the file
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 [model_providers.opencodex]
 name = "OpenCodex Proxy"
 base_url = "http://your-host:10100/v1"
@@ -281,7 +281,7 @@ opencodex が管理対象 [バックグラウンドサービス](/reference/cli/
 
 ## ページ分割履歴の保護による拒否
 
-対象の履歴ストアがページ分割をサポートする場合、プロバイダー変更は `history_paginated_requires_native_writer` を返すことがあります。この理由では、Codex の設定、参照プロファイル、モデルカタログは拒否されません。`ocx sync` と `ocx start` はこれらのファイルを書き込み、`model_catalog_json` を設定するため、Codex のモデル選択には OpenCodex 経由のモデルがすべて表示され続けます。会話履歴の再ラベル付けを控えるのはこの理由だけの場合です。ページ分割された履歴の番号は Codex 自身の書き込み処理が割り当て、再試行しても変わりません。読み取れない状態データベース、識別子が変わった履歴、実行できなかった事前検査など、それ以外の履歴事前検査の理由では、後から成功する可能性があるため、遷移全体を拒否してロールバックします。この状態では OpenCodex はページ分割された履歴ファイルやスレッド行を変更しません。既存の会話はすでに付いているプロバイダーのまま移行されず、新しい会話は通常どおりプロキシ経由でルーティングされます。再ラベル付けを控えるとき、ホームに既にある `[model_providers.opencodex]` テーブルは廃止せず残します。ルート上書き（loopback）形式でも同じで、行が `opencodex` と付いている会話は、まだ存在するプロバイダー id を保てます。移行可能なストアの legacy 行も対象です。CLI は `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)` と表示します。`ocx restore` と Codex 設定の削除は、いまも `history_paginated_requires_native_writer` で拒否されます。スレッド行がまだ参照しているのに `[model_providers.opencodex]` 定義を外すと、それらの会話は解決できなくなり、復元経路には互換プロバイダー表を残す手段がありません。すでにページ分割されているホームは、現状では製品からアンインストールできません。意図した動作ではなく、既知の未解決作業です。
+対象の履歴ストアがページ分割をサポートする場合、プロバイダー変更は `history_paginated_requires_native_writer` を返すことがあります。この理由では、Codex の設定、参照プロファイル、モデルカタログは拒否されません。`ocx sync` と `ocx start` はこれらのファイルを書き込み、`model_catalog_json` を設定するため、Codex のモデル選択には OpenCodex 経由のモデルがすべて表示され続けます。会話履歴の再ラベル付けを控えるのはこの理由だけの場合です。ページ分割された履歴の番号は Codex 自身の書き込み処理が割り当て、再試行しても変わりません。読み取れない状態データベース、識別子が変わった履歴、実行できなかった事前検査など、それ以外の履歴事前検査の理由では、後から成功する可能性があるため、遷移全体を拒否してロールバックします。この状態では OpenCodex はページ分割された履歴ファイルやスレッド行を変更しません。既存の会話はすでに付いているプロバイダーのまま移行されず、新しい会話は通常どおりプロキシ経由でルーティングされます。再ラベル付けを控えるとき、ホームに既にある `[model_providers.opencodex]` テーブルは廃止せず残します。ルート上書き（loopback）形式でも同じで、行が `opencodex` と付いている会話は、まだ存在するプロバイダー id を保てます。移行可能なストアの legacy 行も対象です。CLI は `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)` と表示します。`ocx restore`、`ocx stop`、`ocx uninstall` は `history_paginated_requires_native_writer` で拒否しなくなりました。OpenCodex が書いたルートのルーティングキーをすべて取り除き、`[model_providers.opencodex]` の定義はディスクに残します。そのプロバイダーを指している会話は解決でき、素の `codex` はプロキシを向かなくなります。結果は残した行を示す部分復元として報告され、`ocx restore --remove-codex-provider-table` を使えばその行も削除できます。そのときは該当の会話が開かなくなります。また、`openai` と付いた会話を Codex がすでにページ分割したホームでプロバイダーテーブル形式の統合を有効にすると、以前は `history_paginated_openai_requires_native_writer` で全体が拒否され、何も書かれず統合も無効のままでした。現在は、管理対象のルート `openai_base_url` 上書きを `[model_providers.opencodex]` テーブルと一緒に残す形で移行を完了します。Codex はこの上書きを組み込みの `openai` プロバイダーに統合するため、それらの会話は再ラベル付けなしでプロキシに届き、履歴ファイルやスレッド行は変更されません。`x-opencodex-api-key` の受け入れヘッダーを必要とするルーティング形式だけは今も拒否されます。組み込みプロバイダーがそのヘッダーを運べないためで、そのメッセージは解決策を二つ名指しします。ループバックリスナー経由で Codex を接続して上書きを維持するか、`syncResumeHistory` を `false` にして、それらの会話が Codex 自身の OpenAI エンドポイントに向かうことを受け入れるかです。
 
 ルート URL 上書き方式に戻すとき、履歴の事前確認が成功していても、OpenCodex は設定を確定する前に既存の `[model_providers.opencodex]` 定義を保持します。確定後やバックグラウンドの履歴処理開始中に Codex が履歴形式を移行しても、以前の `opencodex` 会話はプロバイダーを引き続き解決できます。新しい会話は選択されたルートプロバイダーを使い、明示的な復元には従来の個別の削除チェックが適用されます。
 
diff --git a/docs-site/src/content/docs/ja/guides/macos-menu-bar.md b/docs-site/src/content/docs/ja/guides/macos-menu-bar.md
new file mode 100644
index 00000000000..bf429ac0dc1
--- /dev/null
+++ b/docs-site/src/content/docs/ja/guides/macos-menu-bar.md
@@ -0,0 +1,169 @@
+---
+title: macOS メニューバーアプリ
+description: OpenCodex プロキシの状態、使用量、プロバイダーのクォータをメニューバーから確認できるネイティブアプリ。
+---
+
+メニューバーアプリは、ダッシュボードを開かずにプロキシの状態、直近の使用量、プロバイダーごとの
+クォータ状況を表示します。
+
+プロキシとは別のアプリケーションです。`ocx` はこれまで通り動作し、メニューバーアプリは
+ローカルの管理 API に接続するクライアントとして動きます。
+
+## デスクトップアプリ (Tauri)
+
+同じダッシュボードを OpenCodex デスクトップアプリ内で実行できます。Usage コンパニオン
+パネルは OS に合ったインストール手順を表示し、デスクトップシェル内では **ブラウザーで開く**
+を選ぶと現在の画面を通常のブラウザーで開けます。
+
+## インストール
+
+基本のインストール方法は OpenCodex デスクトップアプリです。[リリースページ](https://github.com/lidge-jun/opencodex/releases)から、macOS では
+`OpenCodex-<version>-macos.dmg` をダウンロードし、DMG を開いて `OpenCodex.app` を
+アプリケーションフォルダへドラッグします。Windows では
+`OpenCodex-<version>-windows-x64.msi` を実行し、Linux では AppImage または
+`OpenCodex-<version>-linux-amd64.deb` を使います。
+
+```bash
+chmod +x OpenCodex-<version>-linux-x86_64.AppImage
+sudo apt install ./OpenCodex-<version>-linux-amd64.deb
+```
+
+Windows SmartScreen や macOS Gatekeeper の警告が表示されることがあります。アプリは
+既存の `ocx` に接続し、見つからなければ同梱のサイドカーを起動します。
+
+## 初回起動: Gatekeeper
+
+**初回起動はブロックされます。** 次のメッセージが表示されます。
+
+> "OpenCodex.app"は、開発元を検証できないため開けません。
+
+これは想定された動作なので、読み飛ばさずに理由を説明します。Gatekeeper は Apple の
+Developer ID 署名と公証（notarization）チケットを要求しますが、どちらも有料の Apple
+Developer アカウントが必要です。OpenCodex はそのアカウントを持たないため、アプリは ad-hoc
+署名で配布されます。バンドル自体は壊れておらず署名も有効ですが、Apple が配布元を保証しては
+いない、という状態です。
+
+それでも開くには:
+
+1. Finder で `OpenCodex.app` を右クリック（または Control クリック）します。
+2. **開く** を選択します。
+3. 表示されたダイアログで再度 **開く** をクリックします。
+
+ダイアログに「開く」が無い場合は、**システム設定 → プライバシーとセキュリティ** でブロック
+通知を探し、**このまま開く** をクリックしてください。
+
+一度許可すれば macOS が記憶するため、バージョンごとに一度だけの操作です。
+
+ターミナルから隔離属性を削除する方法もあります。
+
+```bash
+xattr -d com.apple.quarantine /Applications/OpenCodex.app
+```
+
+どちらも避けたい場合はソースからビルドしてください。ローカルビルドには隔離属性が付きません。
+[ソースからビルド](#ソースからビルド)を参照してください。
+
+## 表示される内容
+
+メニューバーのアイコンは色ではなく形で状態を示します。macOS のメニューバーアイコンは単色が
+慣例だからです。
+
+| アイコン | 意味 |
+| --- | --- |
+| 塗りつぶし | 実行中、ルーティング保護あり |
+| 切り欠き付き | 実行中だがルーティング保護が不安定 |
+| 輪郭のみ | 確認中、または応答が異常 |
+| 薄い輪郭 | 停止中、または API キーが必要 |
+
+アイコンをクリックすると 4 つのセクションを持つパネルが開きます。
+
+**ステータス** — プロキシの稼働状況、アプリが使用しているループバックアドレス、保護状態。プロキシが対処コマンド
+（例: `ocx service install`）を推奨している場合は選択可能なテキストとして表示します。アプリが
+代わりに実行することはありません。
+
+**使用量** — 直近 7 日間のリクエスト数、トークン、推定コストと日別の推移。リクエスト数の後ろの
+`~` は、一部がプロバイダー報告値ではなく推定値であることを示します。
+
+デフォルトでは、メニューバーのヘッドラインに合計トークン数が表示されます。リクエスト数、コスト、クォータ、
+またはアイコンだけを表示したい場合は、ダッシュボードの Usage コンパニオン設定でヘッドライン指標を変更できます。
+macOS 26 ではポップオーバーとウィジェットに Liquid Glass が採用され、それ以前の macOS バージョンでは標準の
+ポップオーバーマテリアルが使われます。
+
+**クォータ** — プロバイダーごとに 1 行、最も逼迫しているウィンドウを表示します。5 時間枠を
+99%、月間枠を 10% 使っているプロバイダーなら 5 時間枠の数値を出します。いま実際に制限に
+かかっているのはそちらだからです。ウィンドウ名を併記するため、`API usage の 42%` と
+`1 か月の 42%` を取り違えることはありません。
+
+**プロバイダー** — 展開できる一覧で、プロバイダーごとにスイッチがあります。デフォルト
+プロバイダーは有効な間スイッチが無効化されます。プロキシがデフォルトの無効化を拒否するため、
+先にダッシュボードでデフォルトを変更してください。
+
+## できること
+
+- **Dashboard** — ブラウザで Web ダッシュボードを開きます。
+- **Stop proxy** — 確認のうえプロキシを停止します。あえて「再起動」とは呼びません。停止すると
+  launchd サービスも止まり、自動的には復帰しないためです。停止後は再起動用のコマンドを
+  パネルに表示します。
+- **プロバイダースイッチ** — プロバイダーの有効・無効を切り替えます。
+
+アカウント、モデル設定、ストレージなどはダッシュボードで操作します。
+
+## ウィジェット
+
+デスクトップを右クリックして **ウィジェットを編集** を選び、**OpenCodex** を追加します。
+プロキシの状態、今日の使用量、クォータを表示し、メニューバーアプリと同じプライバシー保護済み
+スナップショットを使います。アプリのポーリング時に更新されます。macOS 14 以降が必要で、
+API キーや生のアカウント情報は受け取りません。
+
+## プロキシへの接続
+
+アプリが自動で見つけます。`~/.opencodex/runtime-port.json`（または
+`$OPENCODEX_HOME/runtime-port.json`）を読み、無ければポート `10100` を使います。この
+ファイルから取得するのはポートのみで、ホストは常にループバックです。
+
+プロキシがループバック以外のアドレスにバインドされている場合は API キーが必要です。パネルが
+その旨を表示し、ダッシュボードへのボタンを出します。
+
+**この経路はまだサポートされていません。** アプリは macOS キーチェーンからキーを読み取って
+一度だけ再試行しますが、キーを入力する画面はなく、手動で用意する方法もありません。データ保護
+キーチェーンの項目であり、キーチェーンアクセスでは作成できないためです。したがってループバック
+以外のバインドではパネルは「Needs API key」のままになります。
+
+既定であるループバックのプロキシではキーは不要です。ネイティブのキー入力は今後追加予定です。
+
+## ポーリング
+
+アプリは意図的に控えめに動作します。プロキシの生存確認は 5 秒ごと、負荷の大きい集計データ
+（使用量とクォータ）はパネルが開いている間のみ、最大でも 1 分に 1 回取得します。3 回連続で
+失敗した場合は 30 秒間隔に広げます。ユーザーが意図的に停止したプロキシを叩き続けないためです。
+
+## ソースからビルド
+
+macOS 13 以降、Xcode Command Line Tools、および [Bun](https://bun.sh) が必要です。
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+bun run prepare-sidecar
+bun run prepare-widget
+bunx tauri build
+```
+
+バンドルは Tauri のリリース出力に生成され、WidgetKit 拡張は
+`OpenCodex.app/Contents/PlugIns/` に含まれます。
+
+ユニバーサルバイナリ（`UNIVERSAL=1`）には完全な Xcode が必要です。Command Line Tools には
+現在のアーキテクチャ用の Swift 互換ライブラリしか含まれないため、その場合はリンカーエラーでは
+なく理由を説明するメッセージが表示されます。
+
+キーチェーンに Developer ID 証明書がある場合は、`MACOS_SIGN_IDENTITY` を指定すると ad-hoc
+ではなく hardened runtime で署名できます。
+
+```bash
+MACOS_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" bun run prepare-widget
+```
+
+## アンインストール
+
+`OpenCodex.app` をゴミ箱に移動してください。アプリは設定ファイルなどを残さず、現時点では
+キーチェーンにも何も保存しません。
diff --git a/docs-site/src/content/docs/ja/guides/providers.md b/docs-site/src/content/docs/ja/guides/providers.md
index f60ba96b0e6..adad28ad00c 100644
--- a/docs-site/src/content/docs/ja/guides/providers.md
+++ b/docs-site/src/content/docs/ja/guides/providers.md
@@ -185,7 +185,7 @@ Kiro のログインには Kiro CLI が必要です。Unix では `curl -fsSL ht
 
 ## 3. API キーカタログ
 
-opencodex には組み込みプリセットが 95 個含まれています。キー方式 79、OAuth 12、ローカル 3、
+opencodex には組み込みプリセットが 96 個含まれています。キー方式 80、OAuth 12、ローカル 3、
 デフォルト ChatGPT 転送プリセット 1 です。ダッシュボードの **Add provider** ピッカーはキー発行ページを開き、
 入力したキーを検証した後保存します(検証はプロバイダー固有です)。主な項目は以下のとおりです:
 
diff --git a/docs-site/src/content/docs/ja/reference/cli/lifecycle.md b/docs-site/src/content/docs/ja/reference/cli/lifecycle.md
index bf37bc911b6..877954e9755 100644
--- a/docs-site/src/content/docs/ja/reference/cli/lifecycle.md
+++ b/docs-site/src/content/docs/ja/reference/cli/lifecycle.md
@@ -272,6 +272,7 @@ OpenCodex の更新後、既存の Windows シムにこの動作を適用する
 ### `ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`
 
 Windows ステータス トレイ アイコンをインストールして制御します。 Windows ログイン時に開始され、ワンクリックでプロキシ コントロールを提供します。 `start` および `stop` はアイコンのみを制御します。そのメニューを使用してプロキシを制御します。 `--no-start` は `install` に適用され、トレイをすぐに起動せずにインストールします。
+非推奨: OpenCodex デスクトップアプリは Windows、macOS、Linux のトレイを提供します。`ocx tray` はデスクトップアプリを使わないインストール向けに残っています。
 
 ## ダッシュボード
 
diff --git a/docs-site/src/content/docs/ja/reference/configuration/providers.md b/docs-site/src/content/docs/ja/reference/configuration/providers.md
index a9fdaf8c813..7dacef8a955 100644
--- a/docs-site/src/content/docs/ja/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/ja/reference/configuration/providers.md
@@ -125,11 +125,13 @@ account を削除しても mapping は保持され、同じ id を再追加す
 | `noPenaltyModels?` | `string[]` |存在/周波数ペナルティを拒否するモデル。 |
 | `noStructuredOutputModels?` | `string[]` | `openai-chat` エンドポイントが `response_format` を拒否する正確なモデル ID。要求モデルが項目と完全一致する場合だけフィールドを省略し、その他の `openai-chat` モデルでは structured-output 変換を維持します。 |
 | `noJsonSchemaModels?` | `string[]` | `openai-chat` エンドポイントが `json_schema` 形式は拒否しつつ `json_object` は受け入れる正確なモデル ID。この要求はフィールドを削除せず `json_object` に降格して送るため、JSON を求めた呼び出し側は散文ではなく JSON を受け取れます。両方の一覧に載るモデルでは `noStructuredOutputModels` が優先します。`opencode go` / `opencode zen` / `opencode free` プリセットが DeepSeek 経路に既定で載せます。 |
+| `foldDeveloperRoleToSystem?` | `boolean` | `openai-chat` の宛先が `developer` ロールを受け付けるかを記録します。`foldDeveloperRoleToSystem` が未設定なら `system`、`true` なら `system`、`false` なら `developer` として送ります。未設定はこの宛先について何も記録されていないことを意味し、`true` は上流がロールを拒否する記録、`false` は受け付ける記録です。いずれの場合もメッセージは会話内の位置を保ち、変わるのはロールだけです。ロールを拒否する宛先は `400 role 'developer' is not allowed` を返してターンが始まらないため、未記録の既定は畳む側にしてあります。 |
 | `parallelToolCalls?` | `boolean` |並列ツール呼び出しを切り替えます。 OpenAI Chat はデフォルトでオンになっています。非チャット アダプターは明示的な `true` でのみアドバタイズします。 |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` |正確なプレースホルダー ID、欠落している端末 ID、および（`repairInvalidIds` で）正規の `msg_`/`rs_` 接頭辞を欠く message/reasoning ID に対するダウンストリーム SSE 修復はデフォルトで無効になっています。関数呼び出し ID は決して書き換えられません。組み込み DeepSeek は最後の 2 つをデフォルトで有効にします。 |
 | `responsesSnapshotRepair?` | `boolean` | デフォルトで無効のクライアント向け修復です。SSE と JSON の Responses ライフサイクルで欠落した status、output、ツールメタデータを補完し、raw 検査と永続化は変更しません。 |
 | `retryOn429?` | `{ enabled?: boolean; attempts?: number; intervalMs?: number; maxIntervalMs?: number; respectRetryAfter?: boolean }` | API-key プロバイダーのみ(`authMode: "key"`)。オプトインの同一ターゲット 429 リトライ: `retryOn429` が無ければ無効で、オブジェクトがあれば `enabled: false` でない限り有効になります。429 時に待機(上流の `Retry-After` または固定間隔)してから、キー フェイルオーバーの前に同一キーで同一リクエストを再送します — メインのテキストターン回復ループ、Responses passthrough、画像/動画ブリッジ、web-search サイドカー、ターミナル継続要求をすべてカバーします。再送の対象はプリストリームの HTTP 429 応答のみで、カスタム `runTurn` トランスポートは HTTP リトライループの対象外です。`attempts` は最初の 429 以降の同一キー再送回数(合計送信数 = `attempts` + 1)で、メインの回復ループ・ターミナルガード継続・ブリッジ再試行で共有されるリクエスト単位の予算です。`attempts` を使い切っても同一キーでの再送が止まるだけで、通常のキー フェイルオーバーまたは最終エラー処理が利用可能なターゲットに応じて続きます — キー認証の passthrough ワイヤにはフェイルオーバーがないため、使い切った 429 はそのまま返ります。Codex 自体は 429 をリトライしないため、単一キーのプロバイダーでは唯一の防御です。デフォルト: `enabled: true`、`attempts: 3`、`intervalMs: 5000`、`maxIntervalMs: 60000`(1回の待機は `maxIntervalMs` で上限、その上限は 600000)、`respectRetryAfter: true`。 |
 | `transientRetryOn5xx?` | `{ enabled?: boolean; attempts?: number }` | キー認証の `openai-chat` および `openai-responses` プロバイダーのみ。`authMode: "forward"` のプロバイダー（ChatGPT アカウントプール）はこのオプションを読まず、既定の再試行段数を維持します。ストリーム開始前に上流から返される一時的なステータス（500、502、503、504、520、521、522）に対するオプトインの再試行です。設定がなければ無効で、オブジェクトを指定すると `enabled: false` でない限り有効になります。最初の Responses リクエスト、ターミナルガード継続、ネイティブの `/v1/chat/completions`、および 429／アカウント回復時の再取得が対象です。`attempts` は最初の送信を含め、1 回のリクエストで許可される上流への送信総数です（1～10、デフォルトは 3）。接続リセット回復と共有するリクエスト単位の単一予算であるため、`3` を指定した場合、プロバイダーに到達する実リクエストは最大 3 回です。待機には 400 ms を基準とする固定式の指数バックオフを使用し、上限は 5 秒で、`Retry-After` に従います。レート制限を扱う `retryOn429` とは別の機能であり、ストリーム開始後の失敗は再送されません。 |
+| `retryOnReset?` | `{ enabled?: boolean; replacements?: number }` | ネイティブ `openai-responses` プロバイダー専用で、`authMode: "forward"` も含みます。呼び出し側が何も観測しないまま失敗した送信を、オプトインで置き換えます。設定がなければ無効で、オブジェクトを指定すると `enabled: false` でない限り有効になります。レスポンスヘッダーが届く前に接続が切れた場合と、ヘッダー後に SSE 本文が制御イベントだけを運んだまま切れた場合の両方が対象です。置き換えるのは自己完結したリクエストだけで、`store: false`、完全な `input`、`previous_response_id` / `conversation` / `stream_id` がないこと、クライアントが実行するツールのみ、が条件です。`replacements` は、すべてのレッグとすべてのコンボ子リクエストを合わせて 1 つの論理リクエストが行える置き換え送信の回数です（1..2、デフォルトは 1）。レッグ単位の再試行回数でも送信予算でもないため、置き換え送信もそのレッグがすでに持つ送信許容量に収まる必要があります。すでに出力やツール呼び出しを送ったリクエストは、この値に関わらず置き換えません。元の送信がすでに開始されていた場合は置き換えた推論も課金される可能性があるため、既定では無効です。 |
 | `autoToolChoiceOnlyModels?` | `string[]` | `tool_choice` が `auto` または `none` のみを受け入れるモデル。強制的な選択は格下げされます。 |
 | `preserveReasoningContentModels?` | `string[]` |チャット履歴に以前のアシスタント `reasoning_content` が必要なモデル。 |
 | `reasoningDetailsModels?` | `string[]` | thinking を構造化された `reasoning_details` 配列で返すモデル（`reasoning_split` 使用の MiniMax M シリーズ）。ストリーム差分は累積スナップショットとして prefix-diff され、保持された reasoning は `reasoning_content` 文字列ではなく `reasoning_details` 配列としてリプレイされます。 |
diff --git a/docs-site/src/content/docs/ko/getting-started/installation.md b/docs-site/src/content/docs/ko/getting-started/installation.md
index 70a62f86099..146f25bb01c 100644
--- a/docs-site/src/content/docs/ko/getting-started/installation.md
+++ b/docs-site/src/content/docs/ko/getting-started/installation.md
@@ -43,6 +43,19 @@ ocx --version
 opencodex --version
 ```
 
+## 독립 실행형 바이너리(npm 없음)
+
+릴리스에는 지원되는 macOS, Linux, Windows용 독립 실행형 `ocx` 바이너리도 포함됩니다.
+Bun 런타임과 대시보드가 포함되어 있으므로 npm, Node 또는 별도의 Bun 설치가 필요하지 않습니다.
+플랫폼에 맞는 아카이브를 다운로드해 압축을 풀고 다음과 같이 실행하세요.
+
+```bash
+./ocx --version
+./ocx start
+```
+
+대시보드를 제공하려면 압축을 푼 `gui/dist` 디렉터리를 바이너리 옆에 그대로 두어야 합니다.
+
 ### 배포 채널
 
 안정화 채널인 `latest`에도 ChatGPT, OpenAI API 키, OpenRouter, 실험 단계의 Cursor 경로를 위한
diff --git a/docs-site/src/content/docs/ko/getting-started/quickstart.md b/docs-site/src/content/docs/ko/getting-started/quickstart.md
index f1a179649b7..91d11f1eff3 100644
--- a/docs-site/src/content/docs/ko/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/ko/getting-started/quickstart.md
@@ -5,6 +5,11 @@ description: 첫 프로바이더를 설정하고 명령어 세 개로 OpenAI Cod
 
 이 가이드는 새로 설치한 상태에서 OpenAI가 아닌 모델로 Codex를 실행하기까지의 과정을 안내합니다.
 
+## 독립 실행형 바이너리(npm 없음)
+
+npm 없이 Bun 런타임이 포함된 릴리스 아카이브의 `ocx` 바이너리를 사용할 수도 있습니다.
+`gui/dist` 디렉터리를 바이너리 옆에 둔 채 압축을 풀고 `./ocx start`를 실행하세요.
+
 ## 1. 설정 마법사 실행
 
 ```bash
@@ -13,7 +18,7 @@ ocx init
 
 `ocx init`은 다음 과정을 안내합니다:
 
-1. **프로바이더 선택** — 내장 레지스트리 프리셋 95개 중 하나를 고르거나 `custom`을 선택해 base URL과 adapter를 직접 입력합니다.
+1. **프로바이더 선택** — 내장 레지스트리 프리셋 96개 중 하나를 고르거나 `custom`을 선택해 base URL과 adapter를 직접 입력합니다.
 2. **API 키** — 키를 붙여넣거나 `${ANTHROPIC_API_KEY}` 같은 환경 변수를 참조합니다.
 3. **기본 모델** — 키, 로컬, custom 프로바이더에서는 프리셋을 그대로 쓰거나 모델 ID를 직접 입력합니다.
 4. **프록시 포트** — 기본값은 `10100`입니다.
diff --git a/docs-site/src/content/docs/ko/guides/claude-code.md b/docs-site/src/content/docs/ko/guides/claude-code.md
index 97ccbf35666..27759bbc709 100644
--- a/docs-site/src/content/docs/ko/guides/claude-code.md
+++ b/docs-site/src/content/docs/ko/guides/claude-code.md
@@ -118,6 +118,27 @@ hook을 제거해요. Claude Desktop은 별도 profile을 사용하며 shell hoo
 `claudeCode.nativePassthrough: false`로 끌 수 있고, `claudeCode.anthropicBaseUrl`로 다른 주소를
 지정할 수 있어요.
 
+## Claude Desktop 모드: 1P(기본값)와 게이트웨이
+
+Claude Desktop은 서로 배타적인 두 모드 중 하나로 OpenCodex를 사용해요. 대시보드의
+**Claude → Desktop → 연결 모드** 또는 `ocx claude desktop apply --first-party|--gateway`로 선택합니다.
+
+- **1P(퍼스트파티, 기본값)**: Desktop 자체는 건드리지 않아요. claude.ai 로그인, 채팅 탭, 커넥터,
+  원격 제어가 그대로 유지됩니다. OpenCodex는 `~/.claude/settings.json`의 `env`에
+  `HTTPS_PROXY=http://127.0.0.1:<공개 포트+100>`과 `NODE_EXTRA_CA_CERTS=~/.opencodex/claude-intercept/ca.pem`
+  두 값만 씁니다. Desktop이 Code 탭용으로 실행하는 Claude Code(서브에이전트 포함)와 터미널의
+  `claude` CLI만 이 값을 읽어 로컬 인터셉트 프록시를 거치고, `POST /v1/messages`·`count_tokens`만
+  OpenCodex가 처리하며 나머지 `api.anthropic.com` 경로는 그대로 Anthropic으로 전달돼요. CA는 OS
+  신뢰 저장소에 설치되지 않습니다.
+- **게이트웨이(3P)**: 기존 방식으로, 아래 프로필을 써서 앱 전체가 OpenCodex를 게이트웨이로
+  사용해요. `--gateway`(또는 기존 `--static`/`--hybrid`/`--discovery-only`)로 명시적으로 선택합니다.
+
+모드는 `claudeCode.desktopMode`에 저장돼요. 이미 게이트웨이 프로필을 적용한 설치는 업데이트 후에도
+게이트웨이를 유지하고, 새 설치만 1P가 기본이에요. 모드를 바꾸면 다른 모드의 설정(OpenCodex가 쓴
+값만)이 제거되며, 회사 프록시 같은 외부 `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` 값은 덮어쓰지 않고 적용을
+거부해요. 전환 후에는 Desktop을 완전히 종료하고 다시 열어 주세요. 자세한 내용과 Claude Code CLI
+호환성은 영어 문서를 참고하세요.
+
 ## 원격 허브에 연결된 Claude Desktop
 
 허브에 연결된 컴퓨터에서 `ocx claude desktop apply` 또는 `ocx claude desktop`을 실행하면
@@ -563,4 +584,4 @@ Anthropic 백엔드를 명시하면 의도적으로 실패 후 중단해요.
 
 `config.json`에서 `claudeCode.stabilizePromptCache`를 `true`로 설정하면 번역 경로의 시스템 지시 끝에 붙은 지원 대상 Claude 알림을 마지막 사용자 메시지로 옮깁니다. 기본값은 `false`입니다. 사용하는 클라이언트에서 이 역할 변경을 허용할 때만 켜세요. 코드 펜스 안의 예제와 일치하지 않는 원문은 보존하며, Anthropic 원본 전달 경로는 바꾸지 않습니다. 메타데이터가 없는 요청의 캐시 키는 정리된 지시문을 기준으로 계산합니다. 대화 식별자를 만들거나 상위 서비스의 캐시 적중을 보장하는 기능은 아닙니다.
 
-OpenCode Go의 `deepseek-v4.1-flash` Chat 경로에서는 변환된 타임라인 시스템 알림이 대기 중인 도구 결과 뒤에서 원래 위치와 system 역할을 자동으로 유지합니다. 따라서 새 알림을 추가해도 맨 앞의 시스템 프롬프트를 다시 쓰지 않습니다. `stabilizePromptCache` 설정과 관계없이 적용되며, 다른 모델과 대상의 변환 및 Anthropic 네이티브 전달은 기존 동작을 유지합니다. 캐시 재사용에는 안정적인 세션 식별자와 사용 가능한 상위 서비스 캐시가 여전히 필요합니다. 이전 지시나 도구의 변경, 대화 압축도 캐시 적중에 영향을 줄 수 있으며, 알림 순서를 유지하는 것만으로 재사용을 보장하지는 않습니다.
+변환된 모든 Chat 경로에서 타임라인 알림은 대기 중인 도구 결과 뒤, 대화 안의 원래 위치를 그대로 유지합니다. 덕분에 새 알림을 추가해도 맨 앞의 시스템 프롬프트를 다시 쓰지 않고, 대화 중간의 지시가 그 지시보다 앞선 턴으로 끌려가지도 않습니다. 그 자리가 어떤 역할을 싣는지는 따로 정합니다. 공급자가 `foldDeveloperRoleToSystem: false`를 기록하지 않는 한 알림은 `system`으로 보내며, 이 기록은 상위 서비스가 `developer` 역할을 받아들인다는 뜻이라 같은 위치에서 그대로 전달합니다. 받아들이지 않는 상위 서비스는 `400 role 'developer' is not allowed`로 응답해 턴이 시작조차 못 하므로, 기록이 없는 목적지는 접는 쪽을 씁니다. `stabilizePromptCache` 설정과 관계없이 적용되며 Anthropic 네이티브 전달은 기존 동작을 유지합니다. 캐시 재사용에는 안정적인 세션 식별자와 사용 가능한 상위 서비스 캐시가 여전히 필요합니다. 이전 지시나 도구의 변경, 대화 압축도 캐시 적중에 영향을 줄 수 있으며, 알림 순서를 유지하는 것만으로 재사용을 보장하지는 않습니다.
diff --git a/docs-site/src/content/docs/ko/guides/codex-integration.md b/docs-site/src/content/docs/ko/guides/codex-integration.md
index fa172286f18..1aefaeb8b75 100644
--- a/docs-site/src/content/docs/ko/guides/codex-integration.md
+++ b/docs-site/src/content/docs/ko/guides/codex-integration.md
@@ -20,9 +20,9 @@ Pool 모드에서는 선택된 저장 계정이 쿨다운 중이고 사용 가
 ```toml
 # root keys, before the first table
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 openai_base_url = "http://127.0.0.1:10100/v1"
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 experimental_realtime_ws_base_url = "http://127.0.0.1:10100/v1"
 
 # fastMode를 설정했을 때만 들어갑니다. 설정하지 않으면 [features] 자체가 생기지 않습니다
@@ -169,7 +169,7 @@ model_provider = "opencodex"
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
 
 # appended at the end of the file
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 [model_providers.opencodex]
 name = "OpenCodex Proxy"
 base_url = "http://your-host:10100/v1"
@@ -391,7 +391,7 @@ opencodex가 managed [background service](/reference/cli/#ocx-service)로 실행
 
 ## 페이지 분할 기록 보호에 따른 거부
 
-영향받는 기록 저장소가 페이지 분할을 지원하면 프로바이더 전환이 `history_paginated_requires_native_writer`를 반환할 수 있습니다. 이 이유로는 Codex 설정, 참조 프로필, 모델 카탈로그를 더 이상 거부하지 않습니다. `ocx sync`와 `ocx start`는 해당 파일과 `model_catalog_json`을 계속 쓰므로 Codex 모델 선택기에는 OpenCodex가 라우팅하는 모델이 모두 그대로 보입니다. 대화 기록의 프로바이더 재지정을 건너뛰는 것은 이 이유뿐이며, 페이지 분할 순번은 Codex 자체의 네이티브 기록 작성자가 할당하고 재시도해도 달라지지 않기 때문입니다. 읽을 수 없는 상태 데이터베이스, 식별자가 바뀐 대화 원본, 실행하지 못한 사전 검사처럼 다른 기록 사전 검사 이유는 나중에 성공할 수 있으므로 전환 전체를 거부하고 되돌립니다. 이 상태에서 OpenCodex는 페이지 분할 대화 원본이나 스레드 행을 수정하지 않습니다. 기존 대화는 이미 붙어 있는 프로바이더를 유지하고 이전되지 않으며, 새 대화는 평소처럼 프록시를 통해 라우팅됩니다. 재지정을 건너뛸 때 홈에 이미 있던 `[model_providers.opencodex]` 테이블은 폐기하지 않고 유지합니다. root-override(loopback) 형식에서도 같아서, 행이 `opencodex`로 표시된 대화는 아직 존재하는 프로바이더 id를 유지합니다. 변환 가능한 저장소의 `legacy` 행도 포함됩니다. CLI는 `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`를 출력합니다. `ocx restore`와 Codex 설정 제거는 여전히 `history_paginated_requires_native_writer`로 거부됩니다. 스레드 행이 아직 참조하는데 `[model_providers.opencodex]` 정의를 걷어내면 그 대화를 해석할 수 없고, 복원 경로에는 호환 프로바이더 테이블을 남겨 둘 방법이 없습니다. 이미 페이지 분할된 홈은 지금은 제품으로 제거할 수 없습니다. 의도한 동작이 아니라 알려진 미해결 작업입니다.
+영향받는 기록 저장소가 페이지 분할을 지원하면 프로바이더 전환이 `history_paginated_requires_native_writer`를 반환할 수 있습니다. 이 이유로는 Codex 설정, 참조 프로필, 모델 카탈로그를 더 이상 거부하지 않습니다. `ocx sync`와 `ocx start`는 해당 파일과 `model_catalog_json`을 계속 쓰므로 Codex 모델 선택기에는 OpenCodex가 라우팅하는 모델이 모두 그대로 보입니다. 대화 기록의 프로바이더 재지정을 건너뛰는 것은 이 이유뿐이며, 페이지 분할 순번은 Codex 자체의 네이티브 기록 작성자가 할당하고 재시도해도 달라지지 않기 때문입니다. 읽을 수 없는 상태 데이터베이스, 식별자가 바뀐 대화 원본, 실행하지 못한 사전 검사처럼 다른 기록 사전 검사 이유는 나중에 성공할 수 있으므로 전환 전체를 거부하고 되돌립니다. 이 상태에서 OpenCodex는 페이지 분할 대화 원본이나 스레드 행을 수정하지 않습니다. 기존 대화는 이미 붙어 있는 프로바이더를 유지하고 이전되지 않으며, 새 대화는 평소처럼 프록시를 통해 라우팅됩니다. 재지정을 건너뛸 때 홈에 이미 있던 `[model_providers.opencodex]` 테이블은 폐기하지 않고 유지합니다. root-override(loopback) 형식에서도 같아서, 행이 `opencodex`로 표시된 대화는 아직 존재하는 프로바이더 id를 유지합니다. 변환 가능한 저장소의 `legacy` 행도 포함됩니다. CLI는 `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`를 출력합니다. `ocx restore`, `ocx stop`, `ocx uninstall`은 이제 `history_paginated_requires_native_writer`로 거부하지 않습니다. OpenCodex가 넣은 루트 라우팅 키를 모두 걷어내고 `[model_providers.opencodex]` 정의는 디스크에 남기므로, 그 프로바이더를 가리키는 대화는 계속 열리고 plain `codex`는 더 이상 프록시를 향하지 않습니다. 결과는 남겨 둔 줄을 함께 알려 주는 부분 복원으로 보고되며, `ocx restore --remove-codex-provider-table`을 쓰면 그 줄까지 지웁니다. 대신 해당 대화는 열리지 않게 됩니다. 한편 `openai`로 표시된 대화를 Codex가 이미 페이지 분할한 홈에서 프로바이더 테이블 형식으로 통합을 켜면, 예전에는 `history_paginated_openai_requires_native_writer`로 전체가 거부되어 아무것도 쓰이지 않고 통합도 꺼진 채로 남았습니다. 지금은 관리 대상 루트 `openai_base_url` 재정의를 `[model_providers.opencodex]` 테이블과 함께 남겨 두는 방식으로 전환을 끝냅니다. Codex가 이 재정의를 내장 `openai` 프로바이더에 합치므로 해당 대화는 재지정 없이 계속 프록시에 닿고, 대화 원본이나 스레드 행은 건드리지 않습니다. `x-opencodex-api-key` 승인 헤더가 필요한 라우팅 형식만 여전히 거부합니다. 내장 프로바이더가 그 헤더를 실을 수 없기 때문이며, 이때 메시지는 해결 방법 두 가지를 이름으로 알려 줍니다. 루프백 리스너로 Codex를 연결해 재정의를 유지하거나, `syncResumeHistory`를 `false`로 두어 해당 대화가 Codex 자체 OpenAI 엔드포인트로 이어지는 것을 받아들이는 것입니다.
 
 루트 URL 재정의 방식으로 돌아갈 때 OpenCodex는 기록 사전 점검이 통과하더라도 기존 `[model_providers.opencodex]` 정의를 설정 적용 전에 유지합니다. 설정 적용 후나 백그라운드 기록 작업 시작 중에 Codex가 기록 형식을 전환해도 이전 `opencodex` 대화가 제공자를 계속 찾을 수 있습니다. 새 대화는 선택된 루트 제공자를 사용하며, 명시적 복원에는 기존의 별도 제거 검사가 적용됩니다.
 
diff --git a/docs-site/src/content/docs/ko/guides/macos-menu-bar.md b/docs-site/src/content/docs/ko/guides/macos-menu-bar.md
new file mode 100644
index 00000000000..6aeb3e77425
--- /dev/null
+++ b/docs-site/src/content/docs/ko/guides/macos-menu-bar.md
@@ -0,0 +1,164 @@
+---
+title: macOS 메뉴바 앱
+description: OpenCodex 프록시 상태와 사용량, 프로바이더 쿼터를 메뉴바에서 바로 확인하는 네이티브 앱입니다.
+---
+
+메뉴바 앱은 대시보드를 열지 않아도 프록시 상태와 최근 사용량, 프로바이더별 쿼터를 한눈에
+보여줍니다.
+
+프록시와는 별개의 앱입니다. `ocx`는 지금까지처럼 그대로 돌아가고, 메뉴바 앱은 로컬 관리
+API에 붙는 클라이언트입니다.
+
+## 데스크톱 앱 (Tauri)
+
+같은 대시보드를 OpenCodex 데스크톱 앱에서 실행할 수 있습니다. 사용량 패널은 운영체제에
+맞는 설치 단계를 보여주며, 데스크톱 셸 안에서는 **브라우저에서 열기**를 선택해 현재
+대시보드 화면을 일반 브라우저로 열 수 있습니다.
+
+## 설치
+
+기본 설치 경로는 OpenCodex 데스크톱 앱입니다. [릴리스 페이지](https://github.com/lidge-jun/opencodex/releases)에서 macOS용
+`OpenCodex-<버전>-macos.dmg`를 내려받아 DMG를 열고 `OpenCodex.app`을 응용 프로그램
+폴더로 드래그하세요. Windows에서는 `OpenCodex-<버전>-windows-x64.msi`를 실행하고,
+Linux에서는 AppImage 또는 `OpenCodex-<버전>-linux-amd64.deb`를 사용하세요.
+
+```bash
+chmod +x OpenCodex-<버전>-linux-x86_64.AppImage
+sudo apt install ./OpenCodex-<버전>-linux-amd64.deb
+```
+
+Windows SmartScreen 또는 macOS Gatekeeper 경고가 표시될 수 있습니다. 앱은 기존 `ocx`
+프록시에 연결하고, 찾지 못하면 포함된 사이드카를 시작합니다.
+
+## 첫 실행: Gatekeeper 차단
+
+**처음 실행하면 macOS가 막습니다.** 이런 메시지가 뜹니다.
+
+> "OpenCodex.app"은(는) 개발자를 확인할 수 없기 때문에 열 수 없습니다.
+
+예상된 동작이라 그냥 넘어가지 않고 이유를 적어둡니다. Gatekeeper는 Apple의 Developer ID
+서명과 공증(notarization) 티켓을 요구하는데, 둘 다 유료 Apple Developer 계정이 있어야
+합니다. OpenCodex에는 그 계정이 없어서 앱은 ad-hoc 서명 상태로 배포됩니다. 번들 자체는
+온전하고 서명도 유효하지만, Apple이 배포자를 보증해 주지는 않았다는 뜻입니다.
+
+그래도 열려면:
+
+1. Finder에서 `OpenCodex.app`을 우클릭(또는 Control-클릭)합니다.
+2. **열기**를 선택합니다.
+3. 뜨는 대화상자에서 다시 **열기**를 누릅니다.
+
+대화상자에 열기 버튼이 없다면 **시스템 설정 → 개인정보 보호 및 보안**에서 차단 알림을 찾아
+**그래도 열기**를 누르세요.
+
+한 번 허용하면 macOS가 기억하므로 버전마다 한 번씩만 하면 됩니다.
+
+터미널에서 격리 속성을 지워도 됩니다.
+
+```bash
+xattr -d com.apple.quarantine /Applications/OpenCodex.app
+```
+
+둘 다 내키지 않으면 직접 빌드하세요. 로컬 빌드에는 격리 속성이 아예 붙지 않습니다.
+[소스에서 빌드하기](#소스에서-빌드하기)를 참고하세요.
+
+## 무엇을 보여주나
+
+메뉴바 아이콘은 색이 아니라 형태로 상태를 나타냅니다. macOS 메뉴바 아이콘은 단색이
+관례이기 때문입니다.
+
+| 아이콘 | 의미 |
+| --- | --- |
+| 꽉 찬 마크 | 실행 중이고 라우팅이 보호됨 |
+| 홈이 파인 마크 | 실행 중이지만 라우팅 보호가 불안정함 |
+| 외곽선 마크 | 확인 중이거나 응답이 이상함 |
+| 흐린 외곽선 | 실행 중이 아니거나 API 키가 필요함 |
+
+아이콘을 누르면 네 영역이 있는 패널이 열립니다.
+
+**상태** — 프록시 실행 여부, 앱이 사용 중인 루프백 주소, 보호 상태를 보여줍니다. 프록시가 조치 명령을
+권할 때(예: `ocx service install`) 선택 가능한 텍스트로 표시합니다. 앱이 대신 실행하지는
+않습니다.
+
+**사용량** — 최근 7일간 요청 수, 토큰, 예상 비용과 일자별 추이입니다. 요청 수 뒤의 `~`는
+일부가 프로바이더 보고값이 아니라 추정치라는 표시입니다.
+
+기본적으로 메뉴 막대 헤드라인은 총 토큰 수를 표시합니다. 요청 수, 비용, 할당량 또는 아이콘만 보고 싶다면 대시보드 Usage의 컴패니언 설정에서 헤드라인 지표를 바꿀 수 있습니다.
+macOS 26에서는 팝오버와 위젯이 Liquid Glass를 사용하며, 이전 macOS 버전은 기본 팝오버 머티리얼을 사용합니다.
+
+**쿼터** — 프로바이더마다 한 줄씩, 가장 압박이 큰 창을 보여줍니다. 5시간 한도를 99% 쓰고
+월 한도는 10%만 쓴 프로바이더라면 5시간 수치를 표시합니다. 지금 막고 있는 쪽이 그것이기
+때문입니다. 창 이름을 아래에 적어두어 `API usage의 42%`와 `한 달의 42%`를 헷갈릴 일이
+없습니다.
+
+**프로바이더** — 펼칠 수 있는 목록이고 프로바이더마다 스위치가 있습니다. 기본 프로바이더는
+켜져 있는 동안 스위치가 잠깁니다. 프록시가 기본 프로바이더 비활성화를 거부하기 때문이며,
+대시보드에서 기본값을 먼저 바꿔야 합니다.
+
+## 무엇을 할 수 있나
+
+- **Dashboard** — 브라우저에서 웹 대시보드를 엽니다.
+- **Stop proxy** — 확인을 거쳐 프록시를 중지합니다. 일부러 "재시작"이라고 부르지 않습니다.
+  중지하면 launchd 서비스도 함께 멈춰서 자동으로 다시 뜨지 않기 때문입니다. 중지 후에는
+  다시 시작하는 명령을 패널에 보여줍니다.
+- **프로바이더 스위치** — 프로바이더를 켜고 끕니다.
+
+계정, 모델 설정, 저장소 관리 같은 나머지는 대시보드에서 합니다.
+
+## 위젯
+
+바탕화면을 우클릭하고 **위젯 편집**을 선택한 다음 **OpenCodex**를 추가하세요. 프록시 상태,
+오늘의 사용량과 쿼터를 표시하며 메뉴바 앱과 동일한 개인정보 보호 스냅샷을 사용합니다. 앱이
+폴링할 때 새로 고침됩니다. macOS 14 이상이 필요하고 API 키나 원시 계정 정보는 전달하지 않습니다.
+
+## 프록시 연결
+
+앱이 알아서 찾습니다. `~/.opencodex/runtime-port.json`(또는
+`$OPENCODEX_HOME/runtime-port.json`)을 읽고, 없으면 `10100` 포트를 씁니다. 이 파일에서
+가져오는 건 포트뿐이고 호스트는 항상 루프백입니다.
+
+프록시가 루프백이 아닌 주소에 바인딩돼 있으면 API 키가 필요합니다. 패널이 그 사실을 알려주고
+대시보드로 가는 버튼을 보여줍니다.
+
+**아직 지원되지 않는 경로입니다.** 앱은 macOS 키체인에서 키를 읽어 한 번 재시도하지만,
+키를 입력하는 화면이 없고 손으로 넣을 방법도 없습니다. 데이터 보호 키체인 항목이라 키체인
+접근으로는 만들 수 없기 때문입니다. 따라서 루프백이 아닌 바인딩에서는 패널이 "Needs API key"
+상태로 남습니다.
+
+기본값인 루프백 프록시는 키가 필요 없습니다. 네이티브 키 입력은 예정돼 있습니다.
+
+## 폴링 주기
+
+앱은 일부러 조용하게 동작합니다. 프록시 생존 확인은 5초마다 하고, 비용이 큰 집계 데이터인
+사용량과 쿼터는 패널이 열려 있을 때만, 그것도 최대 1분에 한 번 가져옵니다. 연속 세 번
+실패하면 30초 간격으로 늘립니다. 사용자가 일부러 끈 프록시를 계속 두드리지 않기 위해서입니다.
+
+## 소스에서 빌드하기
+
+macOS 13 이상, Xcode Command Line Tools, 그리고 [Bun](https://bun.sh)이 필요합니다.
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+bun run prepare-sidecar
+bun run prepare-widget
+bunx tauri build
+```
+
+번들은 Tauri 릴리스 출력에 생성되며, WidgetKit 확장은
+`OpenCodex.app/Contents/PlugIns/` 아래에 포함됩니다.
+
+유니버설 바이너리(`UNIVERSAL=1`)를 만들려면 전체 Xcode가 필요합니다. Command Line Tools
+에는 현재 아키텍처용 Swift 호환 라이브러리만 들어 있어서, 이 경우 링커 오류 대신 그 이유를
+설명하는 메시지가 나옵니다.
+
+키체인에 Developer ID 인증서가 있다면 `MACOS_SIGN_IDENTITY`를 지정해 ad-hoc 대신 하드닝된
+런타임으로 서명할 수 있습니다.
+
+```bash
+MACOS_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" bun run prepare-widget
+```
+
+## 삭제
+
+`OpenCodex.app`을 휴지통으로 옮기면 됩니다. 앱은 환경설정이나 별도 상태 파일을 남기지
+않고, 현재는 키체인에도 아무것도 저장하지 않습니다.
diff --git a/docs-site/src/content/docs/ko/guides/providers.md b/docs-site/src/content/docs/ko/guides/providers.md
index 9e8b372e967..0eea4be4b70 100644
--- a/docs-site/src/content/docs/ko/guides/providers.md
+++ b/docs-site/src/content/docs/ko/guides/providers.md
@@ -182,7 +182,7 @@ Kiro 로그인에는 Kiro CLI가 필요합니다. Unix에서는 `curl -fsSL http
 
 ## 3. API 키 카탈로그
 
-opencodex에는 빌트인 프리셋이 95개 들어 있습니다. 키 방식 79개, OAuth 12개, 로컬 3개,
+opencodex에는 빌트인 프리셋이 96개 들어 있습니다. 키 방식 80개, OAuth 12개, 로컬 3개,
 기본 ChatGPT 포워드 프리셋 1개입니다. 대시보드의 **Add provider** 선택기는 키 발급 페이지를 열고,
 입력한 키를 검증한 뒤 저장합니다(검증은 프로바이더별로 다릅니다). 주요 항목은 다음과 같습니다:
 
@@ -345,6 +345,15 @@ discovery를 256 KiB와 raw 행 256개로 제한합니다. agent 전용 및 dedi
 Project ID가 포함된 URL과 dedicated deployment는 custom provider로 설정하세요. API 키는
 [Scaleway console](https://console.scaleway.com/generative-api)에서 생성합니다.
 
+**Featherless 검색:** 이 프리셋은 고정된 OpenAI 호환 host에 인증하고, 상위에서 chat과 현재 plan으로
+필터링된 인기 모델 100개만 요청합니다. 이후 registry 규칙은 각 행이 plan 사용 가능 여부, Hugging Face
+gate 없음, `features.tool_use: true`를 스스로 보고하지 않으면 fail closed로 제외하고, discovery를
+128 KiB와 raw 행 100개로 제한합니다. 덕분에 수만 개 규모의 catalog를 통째로 내려받거나 캐시하지
+않습니다. `/v1/models`는 인증 없이도 호출할 수 있다고 문서화되어 있어 전달한 키가 유효한지 증명하지
+못합니다. chat 요청에는 설정된 Bearer key를 그대로 사용합니다. Featherless 약관은 개인 plan을 대화형
+및 프로토타이핑 용도로 제한하며, 임의의 애플리케이션에는 Scale plan이 필요합니다. 키는
+[Featherless dashboard](https://featherless.ai/account/api-keys)에서 생성합니다.
+
 **Novita 검색:** 키 기반 프리셋은 `openai-chat` adapter를 사용하며 Bearer key를 Novita의 고정
 OpenAI 호환 host에만 보냅니다. 공개 model list에서 `model_type: chat`과 `chat/completions` endpoint를
 모두 보고하는 행만 유지하고 discovery를 512 KiB와 raw 256행으로 제한합니다. catalog가 공개되어 있으므로
diff --git a/docs-site/src/content/docs/ko/reference/cli/lifecycle.md b/docs-site/src/content/docs/ko/reference/cli/lifecycle.md
index e4f2913c6f6..97048c3768e 100644
--- a/docs-site/src/content/docs/ko/reference/cli/lifecycle.md
+++ b/docs-site/src/content/docs/ko/reference/cli/lifecycle.md
@@ -390,6 +390,8 @@ OpenCodex를 업데이트한 뒤 기존 Windows shim에 이 동작을 적용하
 Windows 상태 트레이 아이콘을 설치하고 제어합니다. Windows 로그인 시 시작되며, 프록시를 원클릭으로
 제어할 수 있습니다. `start`와 `stop`은 아이콘만 제어합니다. 프록시 제어는 메뉴를 사용하세요.
 `--no-start`는 `install`에 적용되며, 트레이를 바로 실행하지 않고 설치합니다.
+지원 중단 예정: OpenCodex 데스크톱 앱이 Windows, macOS, Linux에서 트레이를 제공합니다.
+`ocx tray`는 데스크톱 앱이 없는 설치를 위해 계속 사용할 수 있습니다.
 
 ## 대시보드
 
diff --git a/docs-site/src/content/docs/ko/reference/configuration/providers.md b/docs-site/src/content/docs/ko/reference/configuration/providers.md
index 55e1f4457d4..fdbf9c697a8 100644
--- a/docs-site/src/content/docs/ko/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/ko/reference/configuration/providers.md
@@ -125,11 +125,13 @@ managed map을 활성화하면 privacy-safe selector를 만들고, 이후 계정
 | `noPenaltyModels?` | `string[]` | presence/frequency penalty를 허용하지 않는 모델입니다. |
 | `noStructuredOutputModels?` | `string[]` | `openai-chat` 엔드포인트가 `response_format`을 거부하는 정확한 모델 ID입니다. 요청 모델이 항목과 정확히 일치할 때만 필드를 생략하며, 그 외 `openai-chat` 모델에서는 structured-output 변환을 유지합니다. |
 | `noJsonSchemaModels?` | `string[]` | `openai-chat` 엔드포인트가 `json_schema` 형식은 거부하지만 `json_object`는 받는 정확한 모델 ID입니다. 이런 요청은 필드를 지우는 대신 `json_object`로 낮춰 보내므로, JSON을 요청한 클라이언트가 산문 대신 JSON을 받습니다. 한 모델이 두 목록에 모두 있으면 `noStructuredOutputModels`가 우선합니다. `opencode go`, `opencode zen`, `opencode free` 프리셋이 DeepSeek 경로에 기본으로 싣습니다. |
+| `foldDeveloperRoleToSystem?` | `boolean` | `openai-chat` 목적지가 `developer` 역할을 받는지 기록합니다. `foldDeveloperRoleToSystem`이 없으면 `system`, `true`이면 `system`, `false`이면 `developer`로 보냅니다. 값이 없다는 것은 이 목적지에 대해 기록된 것이 없다는 뜻이고, `true`는 상위 서비스가 역할을 거부한다는 기록, `false`는 받아들인다는 기록입니다. 어느 경우에도 메시지는 대화 안의 원래 위치를 유지하며 역할만 바뀝니다. 역할을 거부하는 목적지는 `400 role 'developer' is not allowed`로 응답해 턴이 시작조차 못 하므로, 기록이 없는 상태의 기본값을 접는 쪽으로 둡니다. |
 | `parallelToolCalls?` | `boolean` | 병렬 도구 호출을 켜거나 끕니다. OpenAI Chat은 기본으로 켜져 있고, 비-chat 어댑터는 명시적으로 `true`일 때만 이를 노출합니다. |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | 기본값이 꺼진 downstream SSE 복구입니다. 정확한 자리표시자 id, 누락된 종료 id, 그리고(`repairInvalidIds`) 정규 `msg_`/`rs_` 접두사가 없는 message/reasoning id를 복구합니다. function-call id는 다시 쓰지 않습니다. 내장 DeepSeek은 마지막 두 가지를 기본으로 켭니다. |
 | `responsesSnapshotRepair?` | `boolean` | 기본값이 꺼진 클라이언트용 복구입니다. SSE와 JSON의 Responses 수명 주기에서 누락된 status, output, 도구 메타데이터를 채우며 raw 검사와 영속화는 변경하지 않습니다. |
 | `retryOn429?` | `{ enabled?: boolean; attempts?: number; intervalMs?: number; maxIntervalMs?: number; respectRetryAfter?: boolean }` | API-key 프로바이더 전용(`authMode: "key"`). 동일 대상 429 재시도: `retryOn429`가 없으면 기능이 꺼져 있고, 객체가 있으면 `enabled: false`가 아닌 한 활성화됩니다. 429 시 대기(업스트림 `Retry-After` 또는 고정 간격) 후 키 장애 조치 전에 동일 키로 동일 요청을 재전송합니다 — 일반 텍스트 턴 복구 루프, Responses passthrough, 이미지/비디오 브리지, web-search 사이드카, 터미널 연속 요청을 모두 포함합니다. 재전송 대상은 프리스트림 HTTP 429 응답뿐이며, 커스텀 `runTurn` 전송은 HTTP 재시도 루프에서 제외됩니다. `attempts`는 첫 429 이후의 동일 키 재전송 횟수(총 전송 = `attempts` + 1)이며, 메인 복구 루프·터미널 가드 연속 요청·브리지 재시도가 공유하는 요청 단위 예산입니다. `attempts`를 모두 소진해도 동일 키 재전송만 중단되며, 이후에는 일반 키 장애 조치 또는 최종 오류 처리가 사용 가능한 대상에 따라 진행됩니다 — 키 인증 passthrough 와이어에는 장애 조치가 없으므로 소진된 429가 그대로 반환됩니다. Codex 자체는 429를 재시도하지 않으므로 단일 키 프로바이더의 유일한 방어선입니다. 기본값: `enabled: true`, `attempts: 3`, `intervalMs: 5000`, `maxIntervalMs: 60000`(단일 대기는 `maxIntervalMs`로 상한, 그 자체는 600000으로 상한), `respectRetryAfter: true`. |
 | `transientRetryOn5xx?` | `{ enabled?: boolean; attempts?: number }` | 키 인증 `openai-chat` 및 `openai-responses` 프로바이더 전용입니다. `authMode: "forward"` 프로바이더(ChatGPT 계정 풀)는 이 옵션을 읽지 않고 기본 재시도 단계를 유지합니다. 스트림 시작 전의 일시적인 업스트림 상태(500, 502, 503, 504, 520, 521, 522)를 선택적으로 재시도합니다. 이 옵션이 없으면 꺼져 있고, 객체가 있으면 `enabled: false`가 아닌 한 활성화됩니다. 최초 Responses 요청, 터미널 가드 연속 요청, 네이티브 `/v1/chat/completions`, 429/계정 복구 재조회를 포함합니다. `attempts`는 최초 전송을 포함하여 요청 하나에 허용되는 업스트림 전송의 총횟수(1..10, 기본값 3)입니다. 연결 재설정 복구와 요청 단위 예산 하나를 공유하므로 `3`이면 실제로 프로바이더에 도달하는 요청은 최대 세 번입니다. 대기에는 400ms로 고정된 지수 백오프를 사용하고 상한은 5초이며 `Retry-After`를 따릅니다. 속도 제한을 처리하는 `retryOn429`와는 별개이며, 스트림 도중의 실패는 절대 재전송하지 않습니다. |
+| `retryOnReset?` | `{ enabled?: boolean; replacements?: number }` | 네이티브 `openai-responses` 프로바이더 전용이며 `authMode: "forward"`도 포함합니다. 호출자가 아무것도 관측하지 못한 채 실패한 전송을 선택적으로 대체합니다. 이 옵션이 없으면 꺼져 있고, 객체가 있으면 `enabled: false`가 아닌 한 활성화됩니다. 응답 헤더가 오기 전에 연결이 끊어진 경우와, 헤더 이후 SSE 본문이 제어 이벤트만 실은 채 끊어진 경우를 모두 다룹니다. 자체 완결된 요청만 대체합니다. `store: false`, 완전한 `input`, `previous_response_id`·`conversation`·`stream_id` 없음, 클라이언트가 실행하는 도구만 해당합니다. `replacements`는 모든 구간과 모든 콤보 자식을 합쳐 논리 요청 하나가 만들 수 있는 대체 전송 횟수입니다(1..2, 기본값 1). 구간별 재시도 횟수도 전송 예산도 아니므로, 대체 전송도 해당 구간이 이미 가진 전송 허용량 안에 들어가야 합니다. 이미 출력이나 도구 호출을 내보낸 요청은 이 값과 무관하게 대체하지 않습니다. 원본 전송이 이미 시작됐다면 대체한 추론도 과금될 수 있어서 기본값은 꺼짐입니다. |
 | `autoToolChoiceOnlyModels?` | `string[]` | `tool_choice`가 `auto` 또는 `none`만 받는 모델입니다. 강제 선택은 낮은 수준으로 바뀝니다. |
 | `preserveReasoningContentModels?` | `string[]` | chat 기록에서 이전 assistant `reasoning_content`가 필요한 모델입니다. |
 | `reasoningDetailsModels?` | `string[]` | thinking을 구조화된 `reasoning_details` 배열로 반환하는 모델(`reasoning_split` 사용 MiniMax M 시리즈). 스트림 델타는 누적 스냅샷이라 prefix-diff로 처리하고, 보존된 reasoning은 `reasoning_content` 문자열 대신 `reasoning_details` 배열로 리플레이합니다. |
diff --git a/docs-site/src/content/docs/reference/cli/lifecycle.md b/docs-site/src/content/docs/reference/cli/lifecycle.md
index e8380c73ca6..3473d3b19cc 100644
--- a/docs-site/src/content/docs/reference/cli/lifecycle.md
+++ b/docs-site/src/content/docs/reference/cli/lifecycle.md
@@ -42,7 +42,7 @@ ocx start --port 10100 --socks5
 ocx start --socks5-off
 ```
 
-### `ocx stop`
+### `ocx stop [--json]`
 
 Stop the running proxy (by PID), remove the PID file, and restore native Codex. If a managed
 background service is installed, `ocx stop` also stops it first so it cannot respawn the proxy.
@@ -65,6 +65,14 @@ It does not enter the forced-stop fallback for a process already observed to hav
 receipt-backed deferral still leaves final restoration and receipt cleanup with the parent;
 failure to restore shared client configuration keeps the stop failed and its receipt outstanding.
 
+`ocx stop --json` runs exactly the same stop path and prints one versioned summary document
+(`schema: "ocx-stop/1"`) on stdout, while the human progress lines move to stderr. The summary
+carries the outcome class (`stopped`, `not-running`, `history-incomplete`, `history-deferred`,
+or `failed`), the service and proxy classifications, whether the runtime is down, and a stable
+one-line message. Exit codes are identical with and without `--json`: 0 on success, 1 on failure,
+79 when only Codex history cleanup did not complete, and 80 when the shared teardown was deferred
+and is still owed.
+
 ### `ocx restart`
 
 When a proxy is running, ask that exact attested PID and port to restart in place, wait for its
@@ -239,6 +247,23 @@ The CLI's own `--json` output is deliberately narrower than the HTTP body: it em
 `unreachable`. Exit codes are 0 for ready; 1 for not-ready, pending, failed, timeout, or
 unreachable; and 64 for invalid arguments.
 
+### `ocx resolve [--json]`
+
+Resolve the runtime facts a shell needs without re-implementing them: the config home, the
+effective port, and the identity-checked liveness verdict. `--json` emits one versioned
+document (`schema: "ocx-resolve/1"`) with `cliVersion`, `configHome`, `port`
+(`effective`, `configured`, and `source`), and `liveness` (`status`, `pid`, `port`,
+`source`, plus `version`, `role`, and `hostname` when the live proxy reports them).
+Liveness has three answers: `live`, `absent-proven` (every recorded and configured endpoint
+definitively refused or answered non-opencodex), and unknown — a timed-out probe or a listener
+that withholds `/healthz` exits 1 rather than reading as absent, so only `absent-proven` may
+authorise starting a new runtime. The port is the live listener's port when a proxy answers,
+otherwise the configured port (default 10100). Exit 0 carries a trustworthy verdict; exit 1 means
+the CLI could not resolve — including an invalid `config.json`, which is never repaired to
+defaults here — and the caller must refuse to guess; any unknown argument exits 64. Discovery uses
+the same ownership-safe probe budget as `ocx start`, because a false "nothing listening" answer
+is how duplicate proxies happen. The verb is read-only and skips the shim auto-restore preflight.
+
 ### `ocx doctor`
 
 The default report includes the native-write coordinator state and exact path using immutable
@@ -423,6 +448,50 @@ On Windows, a bare `ocx service` runs the install path only after both Task Sche
 proven absent. If either status query is inconclusive, it refuses to register anything and asks you
 to run `ocx service status`; use explicit `ocx service install` only after confirming absence.
 
+### Runtime ownership
+
+The OpenCodex desktop app can take the background proxy over from a CLI installation. When it does,
+it records the handover in the shared service install state, and that record is what makes the
+takeover survive a restart. Your service registration is **kept, never deleted** — the record
+supersedes it rather than replacing it.
+
+A state file with no ownership record means the CLI installation owns the runtime, which is what
+every installation made before this feature is in. Nothing changes for you until an app takes over.
+
+While something other than this CLI owns the runtime, the subcommands that would **activate** your
+registration refuse instead:
+
+| Subcommand | Behaviour under a foreign owner |
+| --- | --- |
+| `repair`, `restart` | Refuse before changing anything. The registration is not re-enabled, rewritten or restarted. |
+| `start` | Refuses for the same reason, so an automatic tray start cannot put a second proxy beside the app's. |
+| `stop`, `uninstall` | Unchanged. They deactivate, so they are never gated. |
+| `install` | Takes the runtime back. It clears the ownership record after the registration succeeds, and reports whose it was. |
+
+`ocx update` behaves the same way: it neither stops the running proxy nor refreshes the service
+while the app owns the runtime, because the running server is the app's own bundled binary and the
+refresh would re-enable the launcher the takeover superseded. The app updates its own runtime.
+
+The refusal names the owning installation and the consent generation, for example:
+
+```text
+Background service repair stopped: the desktop app owns the runtime (install <id>, consent generation 2).
+The service registration was left exactly as it is — not re-enabled, not rewritten and not restarted.
+Quit the desktop app and run 'ocx service install' to hand the runtime back to this CLI.
+```
+
+A record that cannot be read or does not parse produces the same refusal with a different first
+line, because an unreadable claim is not the same as no claim — treating it as "nobody owns this"
+is how a permissions error would silently reactivate your service.
+
+**Recovery in every case is `ocx service install`.** It is deliberately the one verb that is never
+gated, so removing the app without handing the runtime back, or a corrupted state file, still leaves
+you a way to take the service back:
+
+```bash
+ocx service install
+```
+
 ```bash
 ocx service
 ocx service install
@@ -611,6 +680,8 @@ file is not part of the injected `env_key` contract; the launching process must
 Install and control the Windows status tray icon. It starts at Windows login and provides one-click
 proxy controls. `start` and `stop` control the icon only; use its menu to control the proxy.
 `--no-start` applies to `install` and installs the tray without launching it immediately.
+Deprecated: the OpenCodex desktop app provides the tray on Windows, macOS, and Linux; `ocx tray`
+remains for installs without the desktop app.
 
 ## Dashboard
 
diff --git a/docs-site/src/content/docs/reference/configuration/providers.md b/docs-site/src/content/docs/reference/configuration/providers.md
index 29f66c70ffa..c7535203297 100644
--- a/docs-site/src/content/docs/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/reference/configuration/providers.md
@@ -141,6 +141,8 @@ Providers can expose a built-in shorthand, such as `agy` for `google-antigravity
 | --- | --- | --- |
 | `adapter` | `string` | One of `openai-chat`, `openai-responses`, `anthropic`, `google`, `kiro`, `cursor`, `ollama-native`, `azure-openai` (or alias `azure`), `codebuddy`, `qoder`. |
 | `baseUrl` | `string` | Upstream API base URL. Most built-in fixed endpoints ignore a mismatch; collision-safe key presets preserve an older same-named custom destination. |
+| `proxy?` | `string \| null` | Per-provider egress route. Omit it to inherit the global proxy decision; use `"direct"` or `null` to force direct egress; or provide an absolute `http://`, `https://`, `socks5://`, or `socks5h://` proxy URL. An empty string is rejected. |
+| `noProxy?` | `string \| string[]` | Destinations this provider reaches directly, using `NO_PROXY` host-pattern syntax. A match bypasses both this provider's own proxy and an inherited global proxy. |
 | `requestPacing?` | `{ enabled, requestsPerMinute?, minIntervalMs?, models? }` | Optional client-side outbound request-start pacing, separate from upstream usage, billing, and rate-limit indicators. RPM is converted to an even interval; `minIntervalMs` may impose a longer interval. Provider limits apply across all models, while `models` entries use exact upstream model IDs (for example `nvidia/llama-3.1-nemotron-ultra-253b-v1`) and can only add delay. Queue waits do not consume the upstream response-header timeout. HTTP, Responses WebSocket, and explicit adapter `fetchResponse`/`runTurn` dispatches are covered. |
 | `upstreamHttpVersion?` | `"auto" \| "http1.1" \| "h1" \| "http2" \| "h2"` | Pin the HTTP version used for upstream requests to this provider. Defaults to `auto`, which lets Bun negotiate. An explicit pin requires an HTTPS target and fails locally when it cannot be honored. Set `http1.1` when a provider's HTTP/2 SSE stream stalls instead of delivering events — the symptom is a long-running streaming request that produces nothing and eventually times out. For Cursor, `http1.1`/`h1` selects its `RunSSE` + `BidiAppend` compatibility transport for inference and also pins live model discovery. Management `POST`/`PATCH` accept `null` to clear it back to `auto`. |
 | `responsesPath?` | `string` | Relative resource path for key-auth `openai-responses` requests. It must start with `/` and contain no scheme, query, or fragment. |
@@ -201,6 +203,7 @@ Providers can expose a built-in shorthand, such as `agy` for `google-antigravity
 | `noPenaltyModels?` | `string[]` | Models that reject presence/frequency penalties. |
 | `noStructuredOutputModels?` | `string[]` | Exact model IDs whose `openai-chat` endpoint rejects `response_format`. Only an exact requested-model match omits the field; structured-output translation stays enabled for every other `openai-chat` model. |
 | `noJsonSchemaModels?` | `string[]` | Exact model IDs whose `openai-chat` endpoint rejects a `json_schema` `response_format` but still accepts `json_object`. Such a request is downgraded to `json_object` instead of being dropped, so a caller asking for JSON still gets JSON. `noStructuredOutputModels` wins when a model is on both lists. The `opencode go`, `opencode zen`, and `opencode free` presets ship this for their DeepSeek routes. |
+| `foldDeveloperRoleToSystem?` | `boolean` | Whether an `openai-chat` destination accepts the `developer` role. `foldDeveloperRoleToSystem` unset sends `system`, `true` sends `system`, and `false` sends `developer`. Unset means nothing has been recorded about this destination; `true` records an upstream that rejects the role; `false` records one that accepts it. The message keeps its position in the conversation in every case — only the role changes. A destination that rejects the role answers `400 role 'developer' is not allowed` and the turn never starts, which is why the unrecorded state is the folded one. |
 | `omitReasoningEffortWithToolsModels?` | `string[]` | Exact `openai-chat` model IDs that accept a reasoning-effort field on an ordinary turn but reject it once function tools are present. The model keeps its advertised effort ladder; OpenCodex omits the wire field for tool-bearing requests only and the upstream default applies. Narrower than `noReasoningModels`, which strips reasoning from every request and costs the model its picker entirely. |
 | `parallelToolCalls?` | `boolean` | Toggle parallel tool calls. OpenAI Chat defaults on; non-chat adapters advertise only on explicit `true`. |
 | `terminalContinuationGuard?` | `boolean` | Opt in an `openai-chat` provider to one bounded internal re-ask when an actionable turn announces work, then cleanly stops without a tool call. Defaults to `false`; explicit `false` behaves like omission. Combo attempts and routed compaction turns are excluded, and non-`openai-chat` adapters ignore this option. |
@@ -209,6 +212,7 @@ Providers can expose a built-in shorthand, such as `agy` for `google-antigravity
 | `webSearchBridge?` | `{ enabled?: boolean; backend?: "ollama" \| "openai" \| "anthropic" \| "xai" \| "gemini" \| "exa"; maxSearches?: number; timeoutMs?: number; endpoint?: string }` | Key-auth `openai-responses` passthrough providers only. Off by default. Codex always declares the hosted `web_search` tool, and the passthrough relays it on the assumption the destination executes it. A gateway that does not run hosted search answers with a `function_call` named `web_search` that nothing runs, and the undeclared-tool guard ends the turn. With `enabled: true` and an explicit `backend` OpenCodex intercepts that call, runs the search itself, feeds the result back to the same upstream, and shows Codex a hosted `web_search_call` cell. Never armed for `authMode: "forward"` (ChatGPT already searches) or for a provider that executes hosted search upstream. `backend` is required; there is no implicit default and a missing credential for the named backend leaves the bridge disarmed rather than falling through to another paid search. `ollama` reuses this provider's own API key on `POST <origin>/api/web_search`, so the origin must be `https://ollama.com` unless the operator names `endpoint` explicitly. `openai` / `anthropic` / `xai` / `gemini` / `exa` reuse the matching sidecar executor and that executor's own credential (`webSearchSidecar.exaApiKey` for Exa). The search model comes from `webSearchSidecar.model` only when `webSearchSidecar.backend` resolves to the same backend this bridge names; otherwise the bridge runs that backend's own default, because a model chosen for one vendor is rejected by another. An unset `webSearchSidecar.backend` resolves to `openai`, so an unset-backend model reaches an `openai` bridge and no other. There is no per-provider bridge model override. Streaming turns only. A turn that mixes `web_search` with another client tool call still fails closed rather than dropping the client's call. Assistant text such as XML-like `<web_search>` prose is not executed. Defaults: `maxSearches: 3` (1..10), `timeoutMs: 60000` (1000..600000). |
 | `retryOn429?` | `{ enabled?: boolean; attempts?: number; intervalMs?: number; maxIntervalMs?: number; respectRetryAfter?: boolean }` | API-key providers only (`authMode: "key"`). Opt-in same-target 429 retry: when `retryOn429` is absent the feature is off; object presence enables it unless `enabled: false`. On 429 the proxy waits (upstream `Retry-After` or the fixed interval) and replays the identical request on the same key before any key failover — across the main text-turn recovery loop, the Responses passthrough wire, the image/video bridge, the web-search sidecar, and terminal continuations. Only pre-stream HTTP 429 responses are eligible for replay; custom `runTurn` transports are outside the HTTP retry loop. `attempts` counts same-key replays after the first 429 (total sends = `attempts` + 1) and is one request-wide budget shared by the main recovery loop, the terminal-guard continuation, and bridge retries. Exhausting `attempts` only stops further same-key replays: normal key failover or final-error handling then applies per the available targets — on the key-auth passthrough wire there is no failover, so the exhausted 429 surfaces as-is. Codex itself never retries 429, so this is the only defense for single-key providers. Defaults: `enabled: true`, `attempts: 3`, `intervalMs: 5000`, `maxIntervalMs: 60000` (any single wait is capped at `maxIntervalMs`, itself capped at 600000), `respectRetryAfter: true`. |
 | `transientRetryOn5xx?` | `{ enabled?: boolean; attempts?: number }` | Key-auth `openai-chat` and `openai-responses` providers only. `authMode: "forward"` providers (the ChatGPT account pool) never read this option and keep the default ladder. Opt-in retry for pre-stream transient upstream statuses (500, 502, 503, 504, 520, 521, 522): absent means off, object presence enables it unless `enabled: false`. Covers the initial Responses request, the Responses passthrough lane and each of its recovery legs (OAuth-401 replay, same-target 429 replay, validated rebuild), the terminal-guard continuation, and native `/v1/chat/completions`. `attempts` is the TOTAL number of upstream sends allowed for one request including the first (1..10, default 3) — it is one budget shared with connection-reset recovery, so `3` means at most three real requests reach the provider. On the Responses passthrough lane the configured value is additionally intersected with the request-wide send allowance, so a value below that allowance narrows the ladder exactly while a value above it does not raise the bound. Waits use a fixed 400 ms exponential backoff capped at 5 s and honor `Retry-After`. Separate from `retryOn429`, which handles rate limiting; mid-stream failures are never replayed. |
+| `retryOnReset?` | `{ enabled?: boolean; replacements?: number }` | Native `openai-responses` providers, including `authMode: "forward"`. Opt-in replacement of a send that failed while the caller had observed nothing: absent means off, object presence enables it unless `enabled: false`. Covers both ambiguous stages — a connection that died before any response header, and an SSE body that died after the header while carrying only control events. Only a self-contained request is ever replaced: `store: false`, complete `input`, no `previous_response_id`, `conversation` or `stream_id`, and only client-executed tools. `replacements` is the number of replacement sends ONE logical request may make across every leg and every combo child (1..2, default 1) — not a per-leg retry count and not a send budget, so a replacement still has to fit inside the send allowance the leg already had. A request that already emitted output or a tool call is never replaced, whatever this is set to. The replacement inference may still be billed if the origin had already started the first one, which is why this is off by default. |
 | `autoToolChoiceOnlyModels?` | `string[]` | Models whose `tool_choice` accepts only `auto` or `none`; forced choices are downgraded. |
 | `preserveReasoningContentModels?` | `string[]` | Models requiring prior assistant `reasoning_content` in chat history. |
 | `reasoningDetailsModels?` | `string[]` | Models whose endpoint returns thinking as a structured `reasoning_details` array (MiniMax M-series with `reasoning_split`); stream deltas are cumulative snapshots that are prefix-diffed, and preserved reasoning replays as a `reasoning_details` array instead of a `reasoning_content` string. |
@@ -247,6 +251,66 @@ nonempty incompatible list falls back to the native default as a single choice.
 belong to the final list. This changes the catalog projection, not stored configuration.
 See [custom native catalog examples](/guides/codex-app-models/).
 
+### Per-provider egress
+
+Set `proxy` on a provider when that upstream needs a different exit from the process-wide proxy:
+
+- Omit `proxy` to inherit the global proxy and `NO_PROXY` decision.
+- Set `proxy` to `"direct"` or `null` to force this provider to connect directly, even when a global proxy is set.
+- Set `proxy` to an absolute `http://` or `https://` URL to use that HTTP proxy for this provider.
+- Set `proxy` to an absolute `socks5://` or `socks5h://` URL to use that SOCKS5 proxy for this provider.
+
+An empty or whitespace-only string is rejected on purpose. A cleared field must not silently change
+from “inherit the global proxy” to “force direct”; remove the field to inherit, or write `"direct"`
+to choose direct egress explicitly.
+
+`noProxy` accepts a comma-separated string or an array of strings in `NO_PROXY` syntax. It is
+evaluated for each request. A matching destination goes direct whether the provider would otherwise
+use its own `proxy` or inherit a global proxy.
+
+#### What the route covers
+
+The route is applied to routed inference, provider discovery and connection tests, and API-key
+quota probes. Some transports cannot carry it, and OpenCodex says so rather than pretending
+otherwise:
+
+- **OAuth token exchange and refresh** keep using the process-wide proxy. These reach fixed vendor
+  endpoints from code that holds no provider configuration, so a provider pinned to its own proxy
+  or to `"direct"` still refreshes its credentials by the global route. OAuth-backed quota probes
+  and API-key validation probes behave the same way.
+- **The Responses WebSocket fast lane** selects its proxy when it dials and cannot carry a
+  per-provider route, so a provider that declares one serves those turns over HTTP/SSE instead and
+  logs a one-time notice.
+- **Cursor's default HTTP/2 transport**, the **CodeBuddy and Qoder subprocess providers** (their
+  child environment omits proxy variables), and the **Compatibility Lab** pinned sender do not
+  apply it.
+- Endpoints that do not route a model — image generation and edits, audio transcription, live and
+  realtime calls, and unqualified `/v1/alpha/search` — have no provider route to apply.
+
+A provider configured with a custom `fetch` executor is refused rather than silently sent by the
+executor's own route.
+
+This example keeps a global proxy for ordinary traffic, sends one provider through a regional HTTP
+proxy, and pins another provider to a direct connection:
+
+```json
+{
+  "proxy": "http://global-proxy.example:8080",
+  "providers": {
+    "regional-gateway": {
+      "adapter": "openai-chat",
+      "baseUrl": "https://regional-api.example/v1",
+      "proxy": "http://regional-proxy.example:3128"
+    },
+    "direct-gateway": {
+      "adapter": "openai-chat",
+      "baseUrl": "https://direct-api.example/v1",
+      "proxy": "direct"
+    }
+  }
+}
+```
+
 ### Operator-pinned reasoning effort
 
 Set `pinnedReasoningEffort` on an existing provider to override incoming effort choices, or
diff --git a/docs-site/src/content/docs/reference/configuration/server.md b/docs-site/src/content/docs/reference/configuration/server.md
index 6deae1998c5..cf317ae8e0c 100644
--- a/docs-site/src/content/docs/reference/configuration/server.md
+++ b/docs-site/src/content/docs/reference/configuration/server.md
@@ -26,6 +26,7 @@ runs helper features around provider requests.
 | `corsAllowOrigins?` | `string[]` | `[]` | Additional exact origins allowed by CORS. Loopback origins are always allowed. Authority-based browser extension origins such as `chrome-extension://<extension-id>` are supported; `*` is not a wildcard. Firefox and Safari regenerate the extension UUID (per install / per browser launch), so update the entry when the origin changes. |
 | `apiKeys?` | `OcxApiKey[]` | `[]` | Generated `ocx_…` data-plane admission credentials on non-loopback binds. They do not authorize management APIs; management access uses the separate credential documented in the [management reference](/reference/management-api/). Dashboard-managed. |
 | `storageCleanupPolicy?` | `StorageCleanupPolicy` | disabled | Opt-in archived-session cleanup policy. Never enabled implicitly. |
+| `usageLedgerMaxBytes?` | `number` | unset | Opt-in ceiling in bytes for `usage.jsonl`. Absent means the request history grows without limit, which stays the default. See [usage history size](#usage-history-size). |
 | `appOwnedMemoryBudgetMb?` | `number` | `256` | Cap in MiB for evictable app-owned logs, caches, blobs, and continuation payloads. Range 64–4096; not an RSS cap. |
 | `metricsExport.enabled?` | `boolean` | `false` | Enable process-local aggregate request metrics at authenticated `GET /api/metrics`. Restart required; disabled mode returns 404 and starts no exporter activity. |
 | `spend?` | `{ root?: { maxTokens?: number }; identity?: { maxTokens?: number }; pool?: { maxTokens?: number }; retentionDays?: number }` | unset | Durable token ceilings, off unless you write one. Each scope bounds settled spend plus in-flight reservations plus unresolved spend: `root` is one task including its whole fan-out, `identity` is one account across every task it serves, and `pool` is one provider pool. They intersect, so a request is admitted only when all three have room — which is what holds a ceiling against a client that mints a new task id per request. A reservation is the request's whole input plus its enforceable output ceiling, counted as if every cached prefix misses. Observe-only mode still journals, so every server owns the state directory's single-writer lease; an explicit sibling must use a separate `OPENCODEX_HOME`. Spend survives an ordinary process restart when its writes reached the filesystem, but the journal does not promise survival across host power loss because each append is not fsynced. Raising or removing the value is what grants more. `maxTokens` must be a positive integer (0 would refuse everything), `retentionDays` is 1–365 and defaults to 7, and an unknown key in this section is rejected rather than ignored. A refusal is a local HTTP 429 carrying `x-opencodex-local-refusal: workflow_spend_exhausted`, and its message names the scope and the ceiling; no provider is contacted. |
@@ -63,10 +64,27 @@ arrives, the proxy cannot tell whether the model already processed the request,
 to send it again and answers HTTP 429 with `upstream_reset_replay_refused`. The status is
 deliberate: a 5xx here is an instruction to most clients, including Codex, to send the whole
 turn again, which is the duplicate the refusal exists to prevent. No `Retry-After` is
-attached, and the proxy performs no key rotation, account failover or same-target replay on
-it, nor does it record the refusal as rate-limit or quota evidence against the credential it
-was holding. Tool-call side requests such as vision and web search are replayed normally, because
-repeating them cannot duplicate a turn.
+attached, and the response carries `x-should-retry: false`, which the official OpenAI and
+Anthropic SDKs read before their own status rules — without it those clients retry a 429 on
+their own schedule and resend the turn anyway. The same replay-refusal behavior applies on
+`/v1/responses` and `/v1/chat/completions`, whether the request is forwarded natively or translated.
+Routed `/v1/messages` requests translate through Responses and project the same status, code, and
+retry headers into an Anthropic-shaped error envelope. The proxy
+performs no key rotation, account failover or same-target replay on it, nor does it record the
+refusal as rate-limit or quota evidence against the credential it was holding. Tool-call side
+requests such as vision and web search are replayed normally, because repeating them cannot
+duplicate a turn.
+
+A native Responses provider can opt into replacing that send with
+[`retryOnReset`](providers.md#provider-entries-ocxproviderconfig). The same grant covers the
+case where the connection survives the header and the SSE body then dies carrying only control
+events, because the caller has observed nothing in either one. A replacement happens only when
+the request is self-contained (`store: false`, complete input, client-executed tools only, no
+server-side continuation state), and one logical request gets the configured number of
+replacements in total — across every recovery leg and every combo child, not one each. The
+refusal returns as soon as that grant is spent, the leg has no send left, or a replacement fails
+for any other reason. A request that already emitted output or a tool call keeps the refusal
+regardless. A caller that cancels mid-replacement gets the cancellation, not the refusal.
 
 `noProxy` accepts either a comma-separated string or an array. Both forms add entries without
 replacing an inherited `NO_PROXY`:
@@ -370,6 +388,26 @@ either `target.reduceToBytes` or `target.removeOldestPercent`. `mode` defaults t
 Configure it on the Storage page or with `GET`/`PUT /api/storage/cleanup-policy`; trigger a manual run
 with `POST /api/storage/cleanup-policy/run`.
 
+## Usage history size
+
+`usageLedgerMaxBytes` is unset by default, and unset means the request history in `usage.jsonl`
+grows without limit. Nothing deletes history you did not ask to have deleted.
+
+Set it to a byte ceiling and the proxy trims the file after an append crosses it, keeping the
+newest whole rows and dropping the oldest. It trims a little below the ceiling rather than exactly
+to it, so the next append does not immediately re-cross the line. The minimum accepted value is
+1 MiB; a smaller number, or one that is not a safe integer, leaves the limit off rather than
+failing the configuration.
+
+Rows are copied byte for byte and never rewritten, so every field survives a trim — including
+fields a newer build wrote that an older one does not understand. The replacement is refused
+outright if anything appended to the ledger while it ran, so a request logged during a trim is
+never lost; the next append tries again. Trimming also refreshes what the dashboard shows, so
+`/api/logs` stops serving rows the ledger no longer has.
+
+There is no dashboard control for this yet; set it in `config.json` or with
+`ocx config set usageLedgerMaxBytes <bytes>`.
+
 ## Quota-reset notifications (`quotaResetNotify`)
 
 Off by default. When the section is absent, no detection runs, no timer starts, and no state
diff --git a/docs-site/src/content/docs/reference/management-api.md b/docs-site/src/content/docs/reference/management-api.md
index 4f47ad8bbc1..9a91de21711 100644
--- a/docs-site/src/content/docs/reference/management-api.md
+++ b/docs-site/src/content/docs/reference/management-api.md
@@ -285,11 +285,19 @@ boundary. Histogram buckets are cumulative and end with `le="+Inf"`, equal to th
 | `opencodex_logical_requests_total` | `protocol`, `result` | One observation per finalized logical request. |
 | `opencodex_physical_sends_total` | `protocol` | Actual upstream sends summed from finalized attempts. |
 | `opencodex_recoveries_total` | `protocol`, `recovery` | Distinct recovery kinds observed per attempt, projected to a closed class. |
+| `opencodex_request_failures_total` | `protocol`, `cause` | Finalized requests that did not deliver an answer, by the cause the recorder derived. Counter only; no histogram carries a cause. |
 | `opencodex_request_duration_seconds` | `protocol`, `result` | Fixed-bucket duration histogram for finalized requests. |
 | `opencodex_ttft_seconds` | `protocol`, `result` | Fixed-bucket TTFT histogram for requests with observed first output. |
 | `opencodex_ttft_missing_total` | `protocol`, `result` | Complementary count for requests without observed TTFT. |
 | `opencodex_metrics_process_start_time_seconds` | none | Process-local reset boundary. |
 
+The `recovery` label takes one of a fixed set of classes: `transient`, `connection`, `credential`,
+`rate_limit`, `quota`, `policy`, `ciphertext`, `payload`, `empty_completion`, `effort_downgrade` and
+`other`. The set is closed, so no model, account, user or request identifier can ever appear in a
+series. `rate_limit`, `quota`, `policy` and `ciphertext` are separate because the operator response
+differs: wait out the limit, move to another account, change the prompt, or drop stale encrypted
+state. A rejected opaque reasoning blob counts as `ciphertext` rather than `payload`.
+
 If a scanned row exceeds the existing parser size limit, `GET /api/usage` and `GET /api/keys`
 keep the readable-row aggregates and add `usageIncomplete: true` with
 `usageIncompleteReason: "oversized_rows"` at response level. This diagnostic survives cached
diff --git a/docs-site/src/content/docs/ru/getting-started/installation.md b/docs-site/src/content/docs/ru/getting-started/installation.md
index a1f3724a4ba..ca0fe20b3e4 100644
--- a/docs-site/src/content/docs/ru/getting-started/installation.md
+++ b/docs-site/src/content/docs/ru/getting-started/installation.md
@@ -45,6 +45,19 @@ ocx --version
 opencodex --version
 ```
 
+## Автономный бинарный файл (без npm)
+
+В релиз входят автономные бинарные файлы `ocx` для поддерживаемых macOS, Linux и Windows.
+Они содержат рантайм Bun и дашборд, поэтому npm, Node и отдельная установка Bun не нужны.
+Скачайте архив для своей платформы, распакуйте его и выполните:
+
+```bash
+./ocx --version
+./ocx start
+```
+
+Чтобы дашборд был доступен, оставьте распакованный каталог `gui/dist` рядом с бинарным файлом.
+
 ### Каналы релизов
 
 Стабильный канал `latest` уже включает поддержку каталога GPT-5.6 Sol/Terra/Luna для маршрутов
diff --git a/docs-site/src/content/docs/ru/getting-started/quickstart.md b/docs-site/src/content/docs/ru/getting-started/quickstart.md
index 1b086c7db2c..750d2fa7476 100644
--- a/docs-site/src/content/docs/ru/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/ru/getting-started/quickstart.md
@@ -5,6 +5,11 @@ description: Настройте первого провайдера и напр
 
 Это руководство проводит от чистой установки до запуска Codex с моделью не от OpenAI.
 
+## Автономный бинарный файл (без npm)
+
+Можно также использовать архив с бинарным файлом `ocx` и рантаймом Bun без npm.
+Распакуйте его, оставив каталог `gui/dist` рядом с бинарным файлом, и выполните `./ocx start`.
+
 ## 1. Запустите мастер настройки
 
 ```bash
@@ -13,7 +18,7 @@ ocx init
 
 `ocx init` проведёт вас по следующим шагам:
 
-1. **Выбор провайдера** — выберите один из 95 встроенных пресетов реестра или `custom`, чтобы
+1. **Выбор провайдера** — выберите один из 96 встроенных пресетов реестра или `custom`, чтобы
    ввести базовый URL и адаптер вручную.
 2. **API-ключ** — вставьте ключ или сошлитесь на переменную окружения вида `${ANTHROPIC_API_KEY}`.
 3. **Модель по умолчанию** — для провайдеров с ключом, локальных и `custom` примите значение из
diff --git a/docs-site/src/content/docs/ru/guides/claude-code.md b/docs-site/src/content/docs/ru/guides/claude-code.md
index 1ceea7da0e8..f82e2e007e4 100644
--- a/docs-site/src/content/docs/ru/guides/claude-code.md
+++ b/docs-site/src/content/docs/ru/guides/claude-code.md
@@ -529,4 +529,4 @@ Responses `web_search_call` в парные блоки Anthropic `server_tool_us
 
 Параметр `claudeCode.stabilizePromptCache: true` в `config.json` переносит поддерживаемые уведомления Claude в конце системных инструкций в последнее пользовательское сообщение на маршрутах с преобразованием. По умолчанию он выключен (`false`). Включайте его только когда такое изменение роли допустимо для ваших клиентов. Примеры в блоках кода и нераспознанный текст сохраняются; нативная передача Anthropic не меняется. Без метаданных ключ кэша рассчитывается по стабилизированным инструкциям. Идентификатор разговора не создаётся, попадания в кэш не гарантируются.
 
-На Chat-маршруте OpenCode Go для `deepseek-v4.1-flash` преобразованные системные напоминания в истории автоматически сохраняют свою позицию и роль system после ожидаемых результатов инструментов. Поэтому добавление новых напоминаний не переписывает начальный системный промпт. Это работает независимо от `stabilizePromptCache`; преобразование для других моделей и адресатов, а также нативная передача Anthropic остаются прежними. Для повторного использования кэша по-прежнему нужны стабильный идентификатор сессии и доступный кэш провайдера. Изменения прежних инструкций или инструментов и сжатие разговора также могут влиять на попадания в кэш; само сохранение порядка напоминаний не гарантирует повторного использования.
+На всех преобразованных Chat-маршрутах напоминания в истории сохраняют свою позицию в разговоре — после ожидаемых результатов инструментов. Поэтому добавление нового напоминания не переписывает начальный системный промпт, а инструкция из середины разговора не оказывается раньше тех ходов, после которых она была написана. Роль этой позиции определяется отдельно: напоминание отправляется как `system`, если провайдер не записал `foldDeveloperRoleToSystem: false` — эта запись означает, что вышестоящий сервис принимает роль `developer`, и тогда она передаётся в той же позиции. Сервис, который её не принимает, отвечает `400 role 'developer' is not allowed`, и ход не начинается, поэтому незаписанное назначение сворачивается. Это работает независимо от `stabilizePromptCache`; нативная передача Anthropic остаётся прежней. Для повторного использования кэша по-прежнему нужны стабильный идентификатор сессии и доступный кэш провайдера. Изменения прежних инструкций или инструментов и сжатие разговора также могут влиять на попадания в кэш; само сохранение порядка напоминаний не гарантирует повторного использования.
diff --git a/docs-site/src/content/docs/ru/guides/codex-integration.md b/docs-site/src/content/docs/ru/guides/codex-integration.md
index 4f318434807..056f4b42917 100644
--- a/docs-site/src/content/docs/ru/guides/codex-integration.md
+++ b/docs-site/src/content/docs/ru/guides/codex-integration.md
@@ -21,7 +21,7 @@ opencodex заставляет Codex маршрутизировать запро
 ```toml
 # root keys, before the first table
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 openai_base_url = "http://127.0.0.1:10100/v1"
 
 # только если fastMode задан; без него таблица [features] не создаётся
@@ -122,7 +122,7 @@ model_provider = "opencodex"
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
 
 # appended at the end of the file
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 [model_providers.opencodex]
 name = "OpenCodex Proxy"
 base_url = "http://your-host:10100/v1"
@@ -413,7 +413,7 @@ ocx restore back # point plain Codex at the running proxy again
 
 ## Защитный отказ для постраничной истории
 
-Если затронутое хранилище поддерживает постраничную историю, смена провайдера может вернуть `history_paginated_requires_native_writer`, в том числе для строк legacy. По этой причине больше не отклоняются конфигурация Codex, опорный профиль и каталог моделей. `ocx sync` и `ocx start` по-прежнему записывают эти файлы и задают `model_catalog_json`, поэтому выбор модели Codex продолжает показывать все модели, маршрутизируемые через OpenCodex. Переразметку истории разговоров останавливает только эта причина: порядковые номера постраничной истории выделяет собственный процесс записи Codex, и повторная попытка этого не меняет. Любая другая причина предварительной проверки истории — нечитаемая база состояния, история со сменившейся идентификацией или проверка, которую не удалось запустить, — по-прежнему отклоняет весь переход и откатывает его, потому что такие случаи могут пройти позже. В этом состоянии OpenCodex не изменяет постраничные файлы истории и строки тредов. Существующие разговоры сохраняют уже назначенного провайдера и не мигрируют; новые разговоры идут через прокси как обычно. Когда переразметка останавливается, таблица `[model_providers.opencodex]`, уже бывшая в домашнем каталоге, сохраняется, а не снимается, в том числе в форме root-override (loopback), чтобы разговоры со строками, помеченными `opencodex`, сохраняли существующий идентификатор провайдера. CLI выводит `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`. `ocx restore` и удаление конфигурации Codex по-прежнему отказывают по `history_paginated_requires_native_writer`. Удаление определения `[model_providers.opencodex]`, пока строки тредов на него ссылаются, сделало бы эти разговоры неразрешимыми, а путь восстановления не умеет оставлять таблицу совместимости провайдера. Домашний каталог, уже переведённый на постраничную историю, сейчас нельзя удалить средствами продукта; это известная открытая задача, а не задуманное поведение.
+Если затронутое хранилище поддерживает постраничную историю, смена провайдера может вернуть `history_paginated_requires_native_writer`, в том числе для строк legacy. По этой причине больше не отклоняются конфигурация Codex, опорный профиль и каталог моделей. `ocx sync` и `ocx start` по-прежнему записывают эти файлы и задают `model_catalog_json`, поэтому выбор модели Codex продолжает показывать все модели, маршрутизируемые через OpenCodex. Переразметку истории разговоров останавливает только эта причина: порядковые номера постраничной истории выделяет собственный процесс записи Codex, и повторная попытка этого не меняет. Любая другая причина предварительной проверки истории — нечитаемая база состояния, история со сменившейся идентификацией или проверка, которую не удалось запустить, — по-прежнему отклоняет весь переход и откатывает его, потому что такие случаи могут пройти позже. В этом состоянии OpenCodex не изменяет постраничные файлы истории и строки тредов. Существующие разговоры сохраняют уже назначенного провайдера и не мигрируют; новые разговоры идут через прокси как обычно. Когда переразметка останавливается, таблица `[model_providers.opencodex]`, уже бывшая в домашнем каталоге, сохраняется, а не снимается, в том числе в форме root-override (loopback), чтобы разговоры со строками, помеченными `opencodex`, сохраняли существующий идентификатор провайдера. CLI выводит `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`. `ocx restore`, `ocx stop` и `ocx uninstall` больше не отказывают по причине `history_paginated_requires_native_writer`. Они убирают все корневые ключи маршрутизации OpenCodex и оставляют определение `[model_providers.opencodex]` на диске, поэтому разговоры, строки которых всё ещё называют этого провайдера, продолжают разрешаться, а обычный `codex` перестаёт указывать на прокси. Результат сообщается как частичное восстановление с перечислением оставленных строк; `ocx restore --remove-codex-provider-table` удаляет и их, после чего такие разговоры перестают открываться. Кроме того, включение интеграции в форме таблицы провайдера в домашнем каталоге, где разговоры с меткой `openai` Codex уже перевёл на постраничную историю, раньше отклонялось целиком с `history_paginated_openai_requires_native_writer`: ничего не записывалось, а интеграция оставалась выключенной. Теперь OpenCodex завершает этот переход, сохраняя управляемое корневое переопределение `openai_base_url` рядом с таблицей `[model_providers.opencodex]`. Codex объединяет это переопределение со своим встроенным провайдером `openai`, поэтому такие разговоры продолжают попадать в прокси без переразметки, а файлы истории и строки тредов не изменяются. Отказ сохраняется только для формы маршрутизации, требующей заголовок допуска `x-opencodex-api-key`, потому что встроенный провайдер Codex не может его нести; в этом случае сообщение называет две настройки, которые решают задачу: направить Codex через loopback-слушатель, чтобы переопределение можно было сохранить, или задать `syncResumeHistory` значение `false`, приняв, что такие разговоры пойдут к собственной конечной точке OpenAI в Codex.
 
 При возврате к режиму переопределения корневого URL OpenCodex сохраняет существующее определение `[model_providers.opencodex]` до фиксации конфигурации, даже если предварительная проверка истории успешна. Поэтому старые разговоры `opencodex` сохраняют доступ к своему провайдеру, если Codex преобразует историю после фиксации или во время запуска фоновой обработки. Новые разговоры используют выбранный корневой провайдер; явное восстановление по-прежнему выполняет отдельные проверки удаления.
 
diff --git a/docs-site/src/content/docs/ru/guides/macos-menu-bar.md b/docs-site/src/content/docs/ru/guides/macos-menu-bar.md
new file mode 100644
index 00000000000..1d264a93c73
--- /dev/null
+++ b/docs-site/src/content/docs/ru/guides/macos-menu-bar.md
@@ -0,0 +1,171 @@
+---
+title: Приложение в строке меню macOS
+description: Нативное приложение, показывающее состояние прокси OpenCodex, расход и квоты провайдеров прямо в строке меню.
+---
+
+Приложение показывает состояние прокси, недавний расход и загрузку квот по провайдерам,
+не требуя открывать панель управления.
+
+Это отдельная программа. `ocx` работает как раньше, а приложение в строке меню —
+клиент, который обращается к локальному management API.
+
+## Настольное приложение (Tauri)
+
+Ту же панель можно открыть в настольном приложении OpenCodex. Панель компаньона показывает
+шаги установки для выбранной ОС, а пункт **Открыть в браузере** открывает текущий экран
+в обычном браузере, когда панель работает внутри desktop shell.
+
+## Установка
+
+Основной способ установки — настольное приложение OpenCodex. На
+[странице релизов](https://github.com/lidge-jun/opencodex/releases) скачайте для macOS
+`OpenCodex-<версия>-macos.dmg`, откройте DMG и перетащите `OpenCodex.app` в «Программы».
+В Windows запустите `OpenCodex-<версия>-windows-x64.msi`, а в Linux используйте AppImage
+или `OpenCodex-<версия>-linux-amd64.deb`.
+
+```bash
+chmod +x OpenCodex-<версия>-linux-x86_64.AppImage
+sudo apt install ./OpenCodex-<версия>-linux-amd64.deb
+```
+
+Windows SmartScreen и macOS Gatekeeper могут показать предупреждение. Приложение подключается
+к существующему `ocx`, а если его нет — запускает встроенный sidecar.
+
+## Первый запуск: Gatekeeper
+
+**Первый запуск будет заблокирован.** macOS покажет:
+
+> Не удаётся открыть «OpenCodex.app», так как не удалось проверить разработчика.
+
+Это ожидаемо, поэтому объясняем причину, а не предлагаем просто нажать дальше. Gatekeeper
+требует подпись Developer ID и билет нотаризации от Apple — и то и другое доступно только
+с платным аккаунтом Apple Developer. У OpenCodex его нет, поэтому приложение выпускается
+с ad-hoc подписью: сам бандл цел и подпись корректна, но Apple не подтверждает издателя.
+
+Чтобы всё-таки открыть:
+
+1. Нажмите правой кнопкой (или Control-клик) на `OpenCodex.app` в Finder.
+2. Выберите **Открыть**.
+3. В появившемся диалоге снова нажмите **Открыть**.
+
+Если в диалоге нет кнопки «Открыть», откройте **Системные настройки → Конфиденциальность и
+безопасность**, найдите уведомление о заблокированной программе и нажмите **Всё равно
+открыть**.
+
+macOS запомнит решение, так что это разовое действие для каждой версии.
+
+Можно также снять атрибут карантина из терминала:
+
+```bash
+xattr -d com.apple.quarantine /Applications/OpenCodex.app
+```
+
+Если ни один вариант не подходит, соберите приложение сами — у локальной сборки атрибута
+карантина нет вовсе. См. [Сборка из исходников](#сборка-из-исходников).
+
+## Что показывает
+
+Иконка в строке меню передаёт состояние формой, а не цветом: в macOS иконки строки меню
+по традиции монохромны.
+
+| Иконка | Значение |
+| --- | --- |
+| Сплошная метка | Работает, маршрутизация защищена |
+| Метка с выемкой | Работает, но защита маршрутизации под угрозой |
+| Контурная метка | Проверка или нештатный ответ |
+| Блёклый контур | Не запущен или нужен API-ключ |
+
+По клику открывается панель с четырьмя разделами.
+
+**Состояние** — работает ли прокси, локальный адрес, который использует приложение, и
+состояние защиты. Если прокси
+рекомендует команду (например, `ocx service install`), она показывается выделяемым
+текстом. Приложение её не выполняет.
+
+**Расход** — запросы, токены и оценочная стоимость за последние 7 дней с дневной
+динамикой. Знак `~` после числа запросов означает, что часть значения оценочная, а не
+сообщённая провайдером.
+
+По умолчанию в заголовке строки меню отображается общее число токенов; если нужны запросы, стоимость, квота или только значок, измените метрику заголовка в настройках Companion раздела Usage на дашборде.
+В macOS 26 всплывающее окно и виджеты используют Liquid Glass; в более ранних версиях macOS используется стандартный материал всплывающего окна.
+
+**Квоты** — по строке на провайдера, показывается окно под наибольшим давлением. Если
+провайдер израсходовал 99% пятичасового лимита и 10% месячного, показывается пятичасовое
+значение — именно оно сейчас блокирует работу. Название окна печатается под провайдером,
+поэтому `42% от API usage` и `42% от месяца` невозможно перепутать.
+
+**Провайдеры** — раскрывающийся список с переключателем для каждого провайдера.
+Переключатель провайдера по умолчанию заблокирован, пока тот включён: прокси отказывается
+отключать провайдера по умолчанию, поэтому сначала смените его в панели управления.
+
+## Что умеет
+
+- **Dashboard** — открывает веб-панель в браузере.
+- **Stop proxy** — останавливает прокси после подтверждения. Намеренно не называется
+  «перезапуск»: остановка также останавливает службу launchd, поэтому прокси не поднимется
+  сам. После остановки панель показывает команду для повторного запуска.
+- **Переключатели провайдеров** — включают и выключают провайдера.
+
+Всё остальное — аккаунты, настройка моделей, хранилище — остаётся в панели управления.
+
+## Виджет
+
+Щёлкните правой кнопкой по рабочему столу, выберите **Изменить виджеты** и добавьте
+**OpenCodex**. Он показывает состояние прокси, расход за сегодня и квоты, используя тот же
+конфиденциальный снимок, что и приложение в строке меню. Виджет обновляется при опросе приложения.
+Требуется macOS 14 или новее; API-ключи и необработанные данные аккаунтов не передаются.
+
+## Подключение к прокси
+
+Приложение находит прокси само. Оно читает `~/.opencodex/runtime-port.json` (или
+`$OPENCODEX_HOME/runtime-port.json`), а при отсутствии использует порт `10100`. Из файла
+берётся только порт; хост всегда локальный.
+
+Если прокси привязан не к локальному адресу, потребуется API-ключ. Панель сообщит об этом
+и предложит перейти в панель управления.
+
+**Этот сценарий пока не поддержан.** Приложение читает ключ из связки ключей macOS и делает
+одну повторную попытку, но интерфейса для ввода ключа нет и нет поддерживаемого способа
+создать его вручную: это элемент data-protection keychain, который «Связка ключей» не
+создаёт. Поэтому при нелокальной привязке панель остаётся в состоянии «Needs API key».
+
+Локальному прокси, который используется по умолчанию, ключ не нужен. Нативный ввод ключа
+запланирован.
+
+## Опрос
+
+Приложение намеренно ведёт себя тихо. Проверка доступности — раз в 5 секунд, а тяжёлые
+агрегаты (расход и квоты) запрашиваются только при открытой панели и не чаще раза в
+минуту. После трёх неудач подряд интервал увеличивается до 30 секунд, чтобы не долбить
+прокси, который вы остановили намеренно.
+
+## Сборка из исходников
+
+Требуются macOS 13 или новее, Xcode Command Line Tools и [Bun](https://bun.sh):
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+bun run prepare-sidecar
+bun run prepare-widget
+bunx tauri build
+```
+
+Бандл появится в выходных файлах Tauri, а расширение WidgetKit будет включено в
+`OpenCodex.app/Contents/PlugIns/`.
+
+Для универсального бинарника (`UNIVERSAL=1`) нужен полный Xcode: в Command Line Tools есть
+только библиотеки совместимости Swift для текущей архитектуры, и сборка сообщит об этом
+вместо ошибки компоновщика.
+
+Если в связке ключей есть сертификат Developer ID, задайте `MACOS_SIGN_IDENTITY`, чтобы
+подписать с hardened runtime вместо ad-hoc:
+
+```bash
+MACOS_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" bun run prepare-widget
+```
+
+## Удаление
+
+Перетащите `OpenCodex.app` в корзину. Приложение не оставляет ни настроек, ни собственных
+файлов состояния и пока ничего не хранит в связке ключей.
diff --git a/docs-site/src/content/docs/ru/guides/providers.md b/docs-site/src/content/docs/ru/guides/providers.md
index a79efd4d6d4..53e86522e2b 100644
--- a/docs-site/src/content/docs/ru/guides/providers.md
+++ b/docs-site/src/content/docs/ru/guides/providers.md
@@ -198,7 +198,7 @@ Inline JSON и лишние позиционные аргументы откло
 
 ## 3. Каталог API-ключей
 
-opencodex поставляется с 95 встроенными пресетами: 79 на основе ключей, 12 OAuth, три локальных и
+opencodex поставляется с 96 встроенными пресетами: 80 на основе ключей, 12 OAuth, три локальных и
 один пресет ChatGPT-форварда по умолчанию. Селектор **Add provider** в дашборде открывает страницу
 выдачи ключей провайдера, проверяет ключ и сохраняет его; проверка зависит от провайдера.
 Наиболее заметные записи:
diff --git a/docs-site/src/content/docs/ru/reference/cli/lifecycle.md b/docs-site/src/content/docs/ru/reference/cli/lifecycle.md
index f338d75388f..6719e9cf2cb 100644
--- a/docs-site/src/content/docs/ru/reference/cli/lifecycle.md
+++ b/docs-site/src/content/docs/ru/reference/cli/lifecycle.md
@@ -395,6 +395,8 @@ ocx codex-shim uninstall
 one-click управление прокси. `start` и `stop` управляют только иконкой; самим прокси нужно
 управлять из её меню. `--no-start` применяется к `install` и устанавливает tray, не запуская её
 немедленно.
+Устарело: приложение OpenCodex для рабочего стола предоставляет трей в Windows, macOS и Linux;
+`ocx tray` остаётся для установок без приложения для рабочего стола.
 
 ## Дашборд
 
diff --git a/docs-site/src/content/docs/ru/reference/configuration/providers.md b/docs-site/src/content/docs/ru/reference/configuration/providers.md
index 21227ef1abd..35de1cf8541 100644
--- a/docs-site/src/content/docs/ru/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/ru/reference/configuration/providers.md
@@ -138,11 +138,13 @@ cross-route credential fallback не существует. Строки API GPT-
 | `noPenaltyModels?` | `string[]` | Модели, отвергающие penalty presence/frequency. |
 | `noStructuredOutputModels?` | `string[]` | Точные идентификаторы моделей, чей endpoint `openai-chat` отклоняет `response_format`. Поле опускается только при точном совпадении запрошенной модели; для остальных моделей `openai-chat` преобразование structured output остаётся включённым. |
 | `noJsonSchemaModels?` | `string[]` | Точные идентификаторы моделей, чей endpoint `openai-chat` отклоняет `response_format` типа `json_schema`, но принимает `json_object`. Такой запрос понижается до `json_object`, а не отбрасывается, поэтому вызывающая сторона всё равно получает JSON. Если модель есть в обоих списках, побеждает `noStructuredOutputModels`. Пресеты `opencode go`, `opencode zen` и `opencode free` включают это для своих маршрутов DeepSeek. |
+| `foldDeveloperRoleToSystem?` | `boolean` | Принимает ли назначение `openai-chat` роль `developer`. Если `foldDeveloperRoleToSystem` не задан, сообщение уходит как `system`; при `true` — как `system`; при `false` — как `developer`. Не задано означает, что об этом назначении ничего не записано; `true` фиксирует вышестоящий сервис, который роль отклоняет; `false` — тот, который её принимает. В любом случае сообщение сохраняет свою позицию в разговоре, меняется только роль. Назначение, отклоняющее роль, отвечает `400 role 'developer' is not allowed`, и ход не начинается — поэтому незаписанное состояние по умолчанию свёрнуто. |
 | `parallelToolCalls?` | `boolean` | Переключатель parallel tool call'ов. Для OpenAI Chat по умолчанию включено; не-chat adapter'ы рекламируют это только при явном `true`. |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | По умолчанию выключенная downstream SSE-repair для exact placeholder-id, отсутствующих terminal-id и (с `repairInvalidIds`) message/reasoning id без канонического префикса `msg_`/`rs_`. Function-call id никогда не переписываются. Встроенный DeepSeek включает последние два по умолчанию. |
 | `responsesSnapshotRepair?` | `boolean` | По умолчанию выключенная клиентская repair для неполных lifecycle snapshot'ов Responses в SSE и JSON. Добавляет отсутствующие status, output и tool metadata, не меняя raw inspection и persistence. |
 | `retryOn429?` | `{ enabled?: boolean; attempts?: number; intervalMs?: number; maxIntervalMs?: number; respectRetryAfter?: boolean }` | Только для провайдеров с API-ключом (`authMode: "key"`). Опциональный повтор при 429 на том же таргете: если `retryOn429` отсутствует, функция выключена; наличие объекта включает её, если только `enabled: false`. При 429: ожидание (`Retry-After` апстрима или фиксированный интервал) и повтор идентичного запроса на том же ключе до любого фейловера ключей — покрывает основной цикл восстановления текстовых ходов, passthrough-канал Responses, мост изображений/видео, sidecar web-search и терминальные продолжения. Повтор допустим только для HTTP 429, полученных до начала потока; пользовательские транспорты `runTurn` не входят в цикл HTTP-повторов. `attempts` — это число повторов на том же ключе после первого 429 (всего отправок = `attempts` + 1) и единый бюджет на запрос, общий для основного цикла восстановления, терминального продолжения и повторов моста. Исчерпание `attempts` лишь останавливает дальнейшие повторы на том же ключе; далее применяется обычный фейловер ключей или финальная обработка ошибки в зависимости от доступных таргетов — на passthrough-канале с ключевой аутентификацией фейловера нет, поэтому исчерпанный 429 возвращается как есть. Codex сам никогда не повторяет 429, поэтому это единственная защита для провайдеров с одним ключом. По умолчанию: `enabled: true`, `attempts: 3`, `intervalMs: 5000`, `maxIntervalMs: 60000` (любое ожидание ограничено `maxIntervalMs`, который сам ограничен 600000), `respectRetryAfter: true`. |
 | `transientRetryOn5xx?` | `{ enabled?: boolean; attempts?: number }` | Только для провайдеров `openai-chat` и `openai-responses` с аутентификацией по ключу. Провайдеры с `authMode: "forward"` (пул аккаунтов ChatGPT) никогда не читают эту настройку и сохраняют число повторов по умолчанию. Опциональный повтор при временных статусах апстрима до начала потока (500, 502, 503, 504, 520, 521, 522): если параметр отсутствует, функция выключена; наличие объекта включает её, если только `enabled: false`. Покрывает исходный запрос `Responses`, продолжение терминального предохранителя, нативный `/v1/chat/completions`, а также повторные запросы при восстановлении после 429 или ошибки учётной записи. `attempts` — ОБЩЕЕ число разрешённых отправок в апстрим для одного запроса, включая первую (1..10, по умолчанию 3). Это единый бюджет на запрос, общий с восстановлением после сброса соединения, поэтому `3` означает, что до провайдера дойдут не более трёх реальных запросов. Ожидание использует экспоненциальную задержку с фиксированной начальной величиной 400 мс, ограниченную 5 с, и учитывает `Retry-After`. Параметр не связан с `retryOn429`, который обрабатывает ограничение частоты запросов; сбои после начала потока никогда не воспроизводятся. |
+| `retryOnReset?` | `{ enabled?: boolean; replacements?: number }` | Только для нативных провайдеров `openai-responses`, включая `authMode: "forward"`. Необязательная замена отправки, которая завершилась неудачей, когда вызывающая сторона ещё ничего не наблюдала: если параметр отсутствует, функция выключена; наличие объекта включает её, если только `enabled: false`. Покрывает обе неоднозначные стадии — обрыв соединения до любого заголовка ответа и обрыв тела SSE после заголовка, когда оно несло только управляющие события. Заменяется только самодостаточный запрос: `store: false`, полный `input`, отсутствие `previous_response_id`, `conversation` и `stream_id`, и только инструменты, исполняемые клиентом. `replacements` — число замещающих отправок, которые ОДИН логический запрос может сделать по всем участкам и всем дочерним запросам комбо (1..2, по умолчанию 1). Это не число повторов на участок и не бюджет отправок, поэтому замена всё равно должна поместиться в уже имеющийся у участка лимит отправок. Запрос, который уже выдал вывод или вызов инструмента, не заменяется никогда, каким бы ни было это значение. Замещающий вывод модели всё равно может быть оплачен, если источник уже начал первый, поэтому параметр выключен по умолчанию. |
 | `autoToolChoiceOnlyModels?` | `string[]` | Модели, у которых `tool_choice` принимает только `auto` или `none`; forced choice понижается. |
 | `preserveReasoningContentModels?` | `string[]` | Модели, которым нужен предыдущий assistant `reasoning_content` в chat history. |
 | `reasoningDetailsModels?` | `string[]` | Модели, чей endpoint возвращает thinking как структурированный массив `reasoning_details` (MiniMax M-series с `reasoning_split`); потоковые дельты — кумулятивные снимки, сравниваемые по префиксу, а сохранённый reasoning воспроизводится массивом `reasoning_details` вместо строки `reasoning_content`. |
diff --git a/docs-site/src/content/docs/tr/getting-started/quickstart.md b/docs-site/src/content/docs/tr/getting-started/quickstart.md
index 6a595544d76..d73cb2bff12 100644
--- a/docs-site/src/content/docs/tr/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/tr/getting-started/quickstart.md
@@ -14,7 +14,7 @@ ocx init
 
 `ocx init` adım adım size rehberlik eder:
 
-1. **Bir sağlayıcı seçin** — yerleşik kayıt defterindeki 95 önayardan birini
+1. **Bir sağlayıcı seçin** — yerleşik kayıt defterindeki 96 önayardan birini
    veya bir temel URL ile adaptör yazmak için `custom` seçeneğini belirleyin.
 2. **API anahtarı** — bir anahtar yapıştırın veya `${ANTHROPIC_API_KEY}` gibi
    bir ortam değişkenine başvurun.
diff --git a/docs-site/src/content/docs/tr/guides/claude-code.md b/docs-site/src/content/docs/tr/guides/claude-code.md
index 4920210639a..d6f5496db14 100644
--- a/docs-site/src/content/docs/tr/guides/claude-code.md
+++ b/docs-site/src/content/docs/tr/guides/claude-code.md
@@ -738,4 +738,4 @@ tutucusu olarak `"haiku"` iletin.
 
 `config.json` içindeki `claudeCode.stabilizePromptCache: true`, dönüştürülen rotalarda sistem talimatlarının sonundaki desteklenen Claude bildirimlerini son kullanıcı mesajına taşır. Varsayılan değer `false` olur. Yalnızca bu rol değişikliği istemcileriniz için uygunsa etkinleştirin. Kod bloklarındaki örnekler ve eşleşmeyen metin korunur; yerel Anthropic aktarımı değişmez. Meta veri yoksa önbellek anahtarı kararlı talimatlardan hesaplanır. Bu seçenek konuşma kimliği oluşturmaz veya üst hizmette önbellek isabeti garanti etmez.
 
-OpenCode Go’nun `deepseek-v4.1-flash` Chat rotasında, dönüştürülen zaman çizelgesi sistem hatırlatmaları bekleyen araç sonuçlarından sonra konumlarını ve system rolünü otomatik olarak korur. Böylece yeni hatırlatmalar eklenmesi, baştaki sistem istemini yeniden yazmaz. Bu davranış `stabilizePromptCache` açık veya kapalıyken geçerlidir; diğer modellerin ve hedeflerin dönüşümü ile yerel Anthropic aktarımı değişmez. Önbelleğin yeniden kullanımı için kararlı bir oturum kimliği ve kullanılabilir üst hizmet önbelleği hâlâ gereklidir. Önceki talimatların veya araçların değişmesi ve konuşmanın sıkıştırılması da önbellek isabetini etkileyebilir; hatırlatma sırasını korumak tek başına yeniden kullanımı garanti etmez.
+Dönüştürülen tüm Chat rotalarında zaman çizelgesi hatırlatmaları, bekleyen araç sonuçlarından sonra konuşmadaki konumlarını korur. Böylece yeni bir hatırlatma eklenmesi baştaki sistem istemini yeniden yazmaz ve konuşmanın ortasındaki bir yönerge, izlemesi gereken turların önüne geçmez. O konumun hangi rolü taşıdığı ayrı bir karardır: sağlayıcı `foldDeveloperRoleToSystem: false` kaydetmedikçe hatırlatma `system` olarak gönderilir; bu kayıt, üst hizmetin `developer` rolünü kabul ettiğini belirtir ve rol aynı konumda iletilir. Kabul etmeyen bir üst hizmet `400 role 'developer' is not allowed` yanıtı verir ve tur hiç başlamaz; kaydı olmayan hedefin katlanmasının nedeni budur. Bu davranış `stabilizePromptCache` açık veya kapalıyken geçerlidir; yerel Anthropic aktarımı değişmez. Önbelleğin yeniden kullanımı için kararlı bir oturum kimliği ve kullanılabilir üst hizmet önbelleği hâlâ gereklidir. Önceki talimatların veya araçların değişmesi ve konuşmanın sıkıştırılması da önbellek isabetini etkileyebilir; hatırlatma sırasını korumak tek başına yeniden kullanımı garanti etmez.
diff --git a/docs-site/src/content/docs/tr/guides/codex-integration.md b/docs-site/src/content/docs/tr/guides/codex-integration.md
index e1ce40af776..a7ccadae455 100644
--- a/docs-site/src/content/docs/tr/guides/codex-integration.md
+++ b/docs-site/src/content/docs/tr/guides/codex-integration.md
@@ -25,7 +25,7 @@ ve bu sağlayıcıyı opencodex'e yönlendirir:
 ```toml
 # kök anahtarlar, ilk tablodan önce
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 openai_base_url = "http://127.0.0.1:10100/v1"
 
 # yalnızca fastMode ayarlandığında; ayarlanmadığında [features] tablosu eklenmez
@@ -134,7 +134,7 @@ model_provider = "opencodex"
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
 
 # dosyanın sonuna eklenir
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 [model_providers.opencodex]
 name = "OpenCodex Proxy"
 base_url = "http://your-host:10100/v1"
@@ -470,7 +470,7 @@ service stop` yerel Codex'i geri yükler.
 
 ## Sayfalanmış geçmiş için güvenlik reddi
 
-Etkilenen geçmiş deposu sayfalamayı destekliyorsa sağlayıcı değişimi `history_paginated_requires_native_writer` döndürebilir; legacy satırlar da buna dahildir. Bu neden artık Codex yapılandırmasını, başvuru profilini veya model kataloğunu reddetmez. `ocx sync` ve `ocx start` bu dosyaları yazmaya ve `model_catalog_json` yolunu ayarlamaya devam eder; böylece Codex model seçicisi OpenCodex üzerinden yönlendirilen her modeli göstermeyi sürdürür. Konuşma geçmişinin yeniden etiketlenmesini durduran yalnızca bu nedendir, çünkü sayfalanmış geçmiş sıra numaralarını Codex’in kendi yerel yazıcısı atar ve yeniden denemek bunu değiştirmez. Okunamayan bir durum veritabanı, kimliği değişmiş bir geçmiş veya çalıştırılamayan bir ön kontrol gibi diğer geçmiş ön kontrol nedenleri, daha sonra başarılı olabilecekleri için hâlâ tüm değişimi reddeder ve geri alır. Bu durumda OpenCodex sayfalanmış geçmiş dosyalarını veya iş parçacığı satırlarını değiştirmez. Mevcut konuşmalar zaten etiketlendikleri sağlayıcıda kalır ve taşınmaz; yeni konuşmalar proxy üzerinden normal şekilde yönlendirilir. Yeniden etiketleme durduğunda, ev dizininde zaten bulunan bir `[model_providers.opencodex]` tablosu kaldırılmaz, kök-override (loopback) biçimde bile tutulur; böylece satırları `opencodex` olarak etiketlenmiş konuşmalar hâlâ var olan bir sağlayıcı kimliğini korur. CLI şunu yazdırır: `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`. `ocx restore` ve Codex yapılandırmasının kaldırılması `history_paginated_requires_native_writer` nedeniyle hâlâ reddedilir. İş parçacığı satırları hâlâ ona başvuruyken `[model_providers.opencodex]` tanımını kaldırmak o konuşmaları çözülemez yapar ve geri yükleme yolu uyumluluk sağlayıcı tablosunu tutamaz. Zaten sayfalanmış bir ev dizini şu anda ürün üzerinden kaldırılamaz; bu amaçlanan davranış değil, bilinen açık iştir.
+Etkilenen geçmiş deposu sayfalamayı destekliyorsa sağlayıcı değişimi `history_paginated_requires_native_writer` döndürebilir; legacy satırlar da buna dahildir. Bu neden artık Codex yapılandırmasını, başvuru profilini veya model kataloğunu reddetmez. `ocx sync` ve `ocx start` bu dosyaları yazmaya ve `model_catalog_json` yolunu ayarlamaya devam eder; böylece Codex model seçicisi OpenCodex üzerinden yönlendirilen her modeli göstermeyi sürdürür. Konuşma geçmişinin yeniden etiketlenmesini durduran yalnızca bu nedendir, çünkü sayfalanmış geçmiş sıra numaralarını Codex’in kendi yerel yazıcısı atar ve yeniden denemek bunu değiştirmez. Okunamayan bir durum veritabanı, kimliği değişmiş bir geçmiş veya çalıştırılamayan bir ön kontrol gibi diğer geçmiş ön kontrol nedenleri, daha sonra başarılı olabilecekleri için hâlâ tüm değişimi reddeder ve geri alır. Bu durumda OpenCodex sayfalanmış geçmiş dosyalarını veya iş parçacığı satırlarını değiştirmez. Mevcut konuşmalar zaten etiketlendikleri sağlayıcıda kalır ve taşınmaz; yeni konuşmalar proxy üzerinden normal şekilde yönlendirilir. Yeniden etiketleme durduğunda, ev dizininde zaten bulunan bir `[model_providers.opencodex]` tablosu kaldırılmaz, kök-override (loopback) biçimde bile tutulur; böylece satırları `opencodex` olarak etiketlenmiş konuşmalar hâlâ var olan bir sağlayıcı kimliğini korur. CLI şunu yazdırır: `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`. `ocx restore`, `ocx stop` ve `ocx uninstall` artık `history_paginated_requires_native_writer` nedeniyle reddetmez. OpenCodex'in yazdığı tüm kök yönlendirme anahtarlarını kaldırır ve `[model_providers.opencodex]` tanımını diskte bırakır; böylece satırları hâlâ o sağlayıcıyı adlandıran konuşmalar çözülmeye devam ederken düz `codex` proxy'yi göstermeyi bırakır. Sonuç, bırakılan satırları adlandıran kısmi bir geri yükleme olarak raporlanır; `ocx restore --remove-codex-provider-table` onları da kaldırır ve ardından o konuşmalar açılmaz. Ayrıca, `openai` etiketli konuşmaları Codex'in zaten sayfaladığı bir ev dizininde entegrasyonu sağlayıcı tablosu biçiminde açmak eskiden `history_paginated_openai_requires_native_writer` ile tümüyle reddediliyordu: hiçbir şey yazılmıyor ve entegrasyon devre dışı kalıyordu. OpenCodex bu geçişi artık yönetilen kök `openai_base_url` geçersiz kılmasını `[model_providers.opencodex]` tablosunun yanında tutarak tamamlar. Codex bu geçersiz kılmayı yerleşik `openai` sağlayıcısıyla birleştirdiği için o konuşmalar yeniden etiketlenmeden proxy'ye ulaşmayı sürdürür ve hiçbir geçmiş baytı veya iş parçacığı satırı değişmez. Yalnızca `x-opencodex-api-key` kabul başlığını gerektiren yönlendirme biçimi hâlâ reddeder, çünkü Codex'in yerleşik sağlayıcısı bu başlığı taşıyamaz; mesajı bunu çözen iki ayarı adlandırır: geçersiz kılmanın korunabilmesi için Codex'i loopback dinleyicisi üzerinden yönlendirin ya da `syncResumeHistory` değerini `false` yaparak o konuşmaların Codex'in kendi OpenAI uç noktasına gitmesini kabul edin.
 
 Kök URL geçersiz kılma biçimine dönülürken OpenCodex, geçmiş ön kontrolü başarılı olsa bile yapılandırmayı kaydetmeden önce mevcut `[model_providers.opencodex]` tanımını korur. Böylece Codex, kayıttan sonra veya arka plan geçmiş işlemi başlarken geçmiş biçimini değiştirirse eski `opencodex` konuşmaları sağlayıcılarını bulmaya devam eder. Yeni konuşmalar seçili kök sağlayıcıyı kullanır; açıkça istenen geri yükleme, mevcut ayrı kaldırma kontrollerini korur.
 
diff --git a/docs-site/src/content/docs/tr/guides/integrations.md b/docs-site/src/content/docs/tr/guides/integrations.md
index c1cc94e2a33..298930cd408 100644
--- a/docs-site/src/content/docs/tr/guides/integrations.md
+++ b/docs-site/src/content/docs/tr/guides/integrations.md
@@ -281,6 +281,34 @@ doğrulanmıştır; neyin ne zaman denetlendiğine ilişkin
 `devlog/_fin/260802_client_toggle_api/002_client_toggle_matrix.md` içindeki
 araştırma notlarına bakın.
 
+## ZCode 3.14 ve sonrası
+
+ZCode 3.14 özel sağlayıcılarını `~/.zcode/v2/provider_config.json` dosyasına taşıdı; bu
+entegrasyonun yazdığı `~/.zcode/v2/config.json` dosyasına artık yalnızca, yeni dosya yokken bir kez
+çalışan bir içe aktarma üzerinden ulaşıyor. ZCode yeni dosyayı ilk çalıştırmada oluşturduğu için,
+bir kez bile başlatılmış her kurulumda bu içe aktarma çoktan tükenmiştir ve `config.json` dosyasına
+yazmak hiçbir şeye ulaşmaz.
+
+opencodex artık mümkün olduğunda `provider_config.json` dosyasını doğrudan yazıyor. Entegrasyonu
+etkinleştirmek bu dosyaya `opencodex` sağlayıcı kuralını ekler, katalog yenilemesi onu günceller ve
+devre dışı bırakmak opencodex'in oraya koyduğu şeyi tam olarak kaldırır. Dosyadaki diğer her kural
+olduğu gibi kalır; buna başka bir sağlayıcının, bizde de bulunan bir model kimliği için tuttuğu
+kural da dahildir. opencodex'in yazmadığı, `opencodex` kimliğini taşıyan bir kural devralınacak bir
+şey değil, bir çakışmadır: ZCode içinde çözün ya da açık üzerine yazmayı kullanın.
+
+İki durum hâlâ yazmak yerine reddeder. ZCode deposunu taşımadan önce opencodex'in yazdığı bir blok,
+entegrasyonu `config.json` üzerinde tutar: önce orada devre dışı bırakın, sonra yeni depoyu yazmak
+için yeniden etkinleştirin. `schemaVersion` değeri opencodex'in gözlemlediklerinden biri olmayan
+bir `provider_config.json` ise birleştirilmez, bildirilir: o dosya ZCode'un tüm sağlayıcılarını
+tutar ve oraya bir şekil dayatmak sessiz bir etkisizliği sessiz bir kayıpla değiştirirdi. Durum
+ekranı, entegrasyon o dosyayı yazmadığı her durumda ZCode'un okuduğu dosyayı adlandırır.
+
+Bu ikinci durumda sağlayıcıyı ZCode'un kendi ayarlarından ekleyin: temel URL
+`http://127.0.0.1:10100/v1` (bağlantı noktasını kendi bağınıza göre ayarlayın), boş olmayan
+herhangi bir anahtar ve `ocx export --client zcode` çıktısındaki model kimlikleri. ZCode'un içe
+aktarmasını yeniden tetiklemek için `provider_config.json` dosyasını silmek desteklenmez: bu,
+ZCode'un orada sakladığı tüm sağlayıcıları yok eder.
+
 ## Cline CLI
 
 Cline CLI providers.json ve models.json kullanır. Değişiklik veya eşitleme öncesinde Cline’ı kapatın, sonra yeniden başlatın. Geri al iki özgün dosyayı geri yükler. Varsayılan sağlayıcı değişmez. Eski VS Code uzantısının depolaması taşınmaz.
diff --git a/docs-site/src/content/docs/tr/guides/providers.md b/docs-site/src/content/docs/tr/guides/providers.md
index abca3a24279..c49040b0960 100644
--- a/docs-site/src/content/docs/tr/guides/providers.md
+++ b/docs-site/src/content/docs/tr/guides/providers.md
@@ -316,7 +316,7 @@ olmayan bir makineden oturum açmak bundan etkilenmez.
 
 ## 3. API anahtarı kataloğu
 
-opencodex 95 yerleşik önayar ile birlikte gelir: 79 anahtar tabanlı, 12
+opencodex 96 yerleşik önayar ile birlikte gelir: 80 anahtar tabanlı, 12
 OAuth, üç yerel ve bir varsayılan ChatGPT iletme önayarı. Kontrol panelinin
 **Sağlayıcı ekle** seçicisi bir anahtar sağlayıcısının kontrol panelini açar,
 anahtarı doğrular ve saklar; doğrulama sağlayıcıya özgüdür. Dikkate değer
diff --git a/docs-site/src/content/docs/tr/reference/cli/lifecycle.md b/docs-site/src/content/docs/tr/reference/cli/lifecycle.md
index ffa5b19df50..f1c30392609 100644
--- a/docs-site/src/content/docs/tr/reference/cli/lifecycle.md
+++ b/docs-site/src/content/docs/tr/reference/cli/lifecycle.md
@@ -470,6 +470,8 @@ Windows durum tepsisi simgesini kurun ve kontrol edin. Windows oturum açılış
 başlar ve tek tıklamayla proxy kontrolleri sağlar. `start` ve `stop` yalnızca
 simgeyi kontrol eder; proxy'yi kontrol etmek için menüsünü kullanın.
 `--no-start`, `install` için geçerlidir ve tepsiyi hemen başlatmadan kurar.
+Kullanımdan kaldırıldı: OpenCodex masaüstü uygulaması Windows, macOS ve Linux'ta tepsi sağlar;
+`ocx tray`, masaüstü uygulaması olmayan kurulumlar için kullanılmaya devam eder.
 
 ## Kontrol Paneli
 
diff --git a/docs-site/src/content/docs/tr/reference/configuration/providers.md b/docs-site/src/content/docs/tr/reference/configuration/providers.md
index 57f5d867189..1fbe43c91d8 100644
--- a/docs-site/src/content/docs/tr/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/tr/reference/configuration/providers.md
@@ -139,11 +139,13 @@ alanlı seçilmiş kimlikleri yalın kimliklere yeniden yazar.
 | `noPenaltyModels?` | `string[]` | Varlık/frekans cezalarını reddeden modeller. |
 | `noStructuredOutputModels?` | `string[]` | `openai-chat` uç noktası `response_format`'ı reddeden tam model kimlikleri. Yalnızca tam bir istenen model eşleşmesi alanı atlar; yapılandırılmış çıktı çevirisi diğer her `openai-chat` modeli için etkin kalır. |
 | `noJsonSchemaModels?` | `string[]` | `openai-chat` uç noktası `json_schema` biçimini reddeden ama `json_object` kabul eden tam model kimlikleri. Böyle bir istek atılmak yerine `json_object` seviyesine düşürülür, böylece JSON isteyen çağıran yine JSON alır. Bir model her iki listede de varsa `noStructuredOutputModels` kazanır. `opencode go`, `opencode zen` ve `opencode free` hazır ayarları bunu DeepSeek rotaları için getirir. |
+| `foldDeveloperRoleToSystem?` | `boolean` | Bir `openai-chat` hedefinin `developer` rolünü kabul edip etmediğini kaydeder. `foldDeveloperRoleToSystem` ayarlanmamışsa `system`, `true` ise `system`, `false` ise `developer` olarak gönderilir. Ayarlanmamış olması bu hedef için hiçbir şey kaydedilmediği anlamına gelir; `true` rolü reddeden bir üst hizmeti, `false` ise kabul edeni kaydeder. Her durumda mesaj konuşmadaki konumunu korur; yalnızca rol değişir. Rolü reddeden bir hedef `400 role 'developer' is not allowed` yanıtı verir ve tur hiç başlamaz; kaydedilmemiş durumun katlanmış olmasının nedeni budur. |
 | `parallelToolCalls?` | `boolean` | Paralel araç çağrılarını açıp kapatın. OpenAI Chat varsayılan olarak açıktır; sohbet harici adaptörler yalnızca açık `true` durumunda bildirir. |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | Tam yer tutucu kimlikleri, eksik terminal kimlikleri ve (`repairInvalidIds` ile) kurallı `msg_`/`rs_` öneki eksik olan mesaj/akıl yürütme kimlikleri için varsayılan olarak devre dışı bırakılmış aşağı akış SSE onarımı. Fonksiyon çağrısı kimlikleri asla yeniden yazılmaz. Yerleşik DeepSeek son ikisini varsayılan olarak etkinleştirir. |
 | `responsesSnapshotRepair?` | `boolean` | SSE ve JSON'daki seyrek Responses yaşam döngüsü anlık görüntüleri için varsayılan olarak devre dışı bırakılmış istemciye yönelik onarım. Ham inceleme ve kalıcılık değişmeden kalırken eksik kurallı durumu, çıktıyı ve araç meta verilerini doldurur. |
 | `retryOn429?` | `{ enabled?: boolean; attempts?: number; intervalMs?: number; maxIntervalMs?: number; respectRetryAfter?: boolean }` | Yalnızca API anahtarı sağlayıcıları (`authMode: "key"`). İsteğe bağlı aynı hedef 429 yeniden denemesi: `retryOn429` olmadığında özellik kapalıdır; nesnenin varlığı `enabled: false` olmadığı sürece özelliği etkinleştirir. 429'da proxy bekler (yukarı akış `Retry-After` veya sabit aralık) ve herhangi bir anahtar yük devretmesinden önce aynı istek üzerinde aynı anahtarla aynı isteği yeniden oynatır — ana metin turu kurtarma döngüsü, Responses doğrudan geçiş hattı, görsel/video köprüsü, web araması sidecar'ı ve terminal devamları genelinde. Yalnızca akış öncesi HTTP 429 yanıtları yeniden oynatma için uygundur; özel `runTurn` aktarımları HTTP yeniden deneme döngüsünün dışındadır. `attempts`, ilk 429'dan sonraki aynı anahtar yeniden oynatmalarını sayar (toplam gönderim = `attempts` + 1) ve ana kurtarma döngüsü, terminal koruma devamı ve köprü yeniden denemeleri tarafından paylaşılan tek bir istek genelinde bütçedir. `attempts`'ı tüketmek yalnızca daha fazla aynı anahtar yeniden oynatmasını durdurur: normal anahtar yük devretmesi veya nihai hata işleme daha sonra kullanılabilir hedeflere göre geçerli olur — anahtar kimlik doğrulamalı doğrudan geçiş hattında yük devretme yoktur, bu nedenle tükenen 429 olduğu gibi görünür. Codex'in kendisi 429'u asla yeniden denemez, bu nedenle tek anahtarlı sağlayıcılar için tek savunma budur. Varsayılanlar: `enabled: true`, `attempts: 3`, `intervalMs: 5000`, `maxIntervalMs: 60000` (tek bir bekleme `maxIntervalMs` ile sınırlandırılır, kendisi de 600000 ile sınırlandırılır), `respectRetryAfter: true`. |
 | `transientRetryOn5xx?` | `{ enabled?: boolean; attempts?: number }` | Yalnızca anahtarla kimlik doğrulanan `openai-chat` ve `openai-responses` sağlayıcıları. `authMode: "forward"` sağlayıcıları (ChatGPT hesap havuzu) bu seçeneği hiç okumaz ve varsayılan merdiveni korur. Akış öncesi geçici yukarı akış durumları (500, 502, 503, 504, 520, 521, 522) için isteğe bağlı yeniden deneme: seçenek belirtilmezse kapalıdır; nesnenin varlığı, `enabled: false` olmadığı sürece özelliği etkinleştirir. İlk Responses isteğini, terminal koruma devamını, yerel `/v1/chat/completions` isteklerini ve 429/hesap kurtarma yeniden getirmelerini kapsar. `attempts`, bir istek için ilk gönderim dahil izin verilen yukarı akış gönderimlerinin TOPLAM sayısıdır (1..10, varsayılan 3) — bağlantı sıfırlama kurtarmasıyla paylaşılan, istek kapsamlı tek bütçedir; dolayısıyla `3`, sağlayıcıya en fazla üç gerçek isteğin ulaşması anlamına gelir. Beklemelerde 400 ms'lik sabit üstel geri çekilme uygulanır, süre 5 sn ile sınırlandırılır ve `Retry-After` dikkate alınır. Hız sınırlamasını işleyen `retryOn429` seçeneğinden ayrıdır; akış ortası hataları hiçbir zaman yeniden oynatılmaz. |
+| `retryOnReset?` | `{ enabled?: boolean; replacements?: number }` | Yalnızca yerel `openai-responses` sağlayıcıları, `authMode: "forward"` dahil. Çağıranın hiçbir şey gözlemlemediği bir anda başarısız olan gönderimin isteğe bağlı olarak değiştirilmesi: seçenek belirtilmezse kapalıdır; nesnenin varlığı, `enabled: false` olmadığı sürece özelliği etkinleştirir. İki belirsiz aşamayı da kapsar: yanıt başlığı gelmeden kopan bağlantı ve başlıktan sonra yalnızca denetim olayları taşırken kopan SSE gövdesi. Yalnızca kendi kendine yeten bir istek değiştirilir: `store: false`, eksiksiz `input`, `previous_response_id`, `conversation` veya `stream_id` bulunmaması ve yalnızca istemcinin yürüttüğü araçlar. `replacements`, BİR mantıksal isteğin tüm bacaklar ve tüm combo alt istekleri boyunca yapabileceği değiştirme gönderimi sayısıdır (1..2, varsayılan 1). Bacak başına yeniden deneme sayısı da gönderim bütçesi de değildir; bu yüzden bir değiştirme gönderimi, ilgili bacağın hâlihazırda sahip olduğu gönderim payına sığmak zorundadır. Halihazırda çıktı veya araç çağrısı üretmiş bir istek, bu değer ne olursa olsun asla değiştirilmez. Kaynak ilk çıkarımı zaten başlatmışsa değiştirilen çıkarım yine ücretlendirilebilir; bu nedenle varsayılan olarak kapalıdır. |
 | `autoToolChoiceOnlyModels?` | `string[]` | `tool_choice`'u yalnızca `auto` veya `none` kabul eden modeller; zorunlu seçimlerin derecesi düşürülür. |
 | `preserveReasoningContentModels?` | `string[]` | Sohbet geçmişinde önceki asistan `reasoning_content`'ini gerektiren modeller. |
 | `reasoningDetailsModels?` | `string[]` | Thinking'i yapılandırılmış bir `reasoning_details` dizisi olarak döndüren modeller (`reasoning_split` ile MiniMax M-serisi); akış deltaları önek farkıyla işlenen kümülatif anlık görüntülerdir ve korunan reasoning, `reasoning_content` dizesi yerine `reasoning_details` dizisi olarak yeniden oynatılır. |
diff --git a/docs-site/src/content/docs/troubleshooting/codex-cannot-sign-in.md b/docs-site/src/content/docs/troubleshooting/codex-cannot-sign-in.md
new file mode 100644
index 00000000000..a5971443b34
--- /dev/null
+++ b/docs-site/src/content/docs/troubleshooting/codex-cannot-sign-in.md
@@ -0,0 +1,99 @@
+---
+title: Codex Cannot Sign In or Load
+description: What to do when Codex fails at sign-in or every request errors after opencodex was applied, and how to hand Codex back to its own account without starting the proxy.
+---
+
+If Codex stops at a sign-in screen, reports that it cannot load sign-in
+requirements, or fails every model request after you set up opencodex, the most
+likely cause is that Codex is still pointed at the opencodex proxy while the
+proxy is not running. This was reported as
+[#5261](https://github.com/lidge-jun/opencodex/issues/5261).
+
+## Why this happens
+
+On the default loopback setup, opencodex does not give Codex a separate
+provider. It points Codex's own built-in `openai` provider at the proxy, by
+writing a root override into `$CODEX_HOME/config.toml` (`%USERPROFILE%\.codex`
+on Windows):
+
+```toml
+model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
+# Auto-injected by opencodex (undo: ocx restore)
+openai_base_url = "http://127.0.0.1:10100/v1"
+# Auto-injected by opencodex (undo: ocx restore)
+experimental_realtime_ws_base_url = "http://127.0.0.1:10100/v1"
+```
+
+Those lines are on disk, so they survive a reboot. If the proxy is not running
+when Codex starts, that address answers nothing, and Codex has no second
+endpoint to fall back to. The screen you get says nothing about opencodex,
+which is why the state is easy to misread as a Codex problem.
+
+The proxy can be absent for ordinary reasons. Applying the Codex integration
+does not install a background service — that is a separate `ocx service install`
+step — so after a restart there may be nothing to bring the proxy back. A
+registered Windows scheduled task starts at logon rather than at boot, and it
+can also be disabled, fail to launch, or lose the port to another process.
+
+## Get Codex working again
+
+Pick whichever outcome you want. Both are safe to run while the proxy is down.
+
+**Hand Codex back to its own account and endpoints:**
+
+```bash
+ocx restore
+```
+
+This removes the injected routing, the realtime override and the opencodex
+catalog pointer, and needs no running proxy, no dashboard session and no
+network. Codex signs in and runs normally afterwards. When you want opencodex
+back, `ocx restore back` re-points Codex at the proxy.
+
+**Or bring the proxy back instead:**
+
+```bash
+ocx start
+ocx service install   # keep it running across restarts
+```
+
+`ocx status` reports whether the proxy is answering and whether Codex is
+currently routed through it. `ocx doctor` explains the same state in more
+detail and names the repair it recommends.
+
+## If ocx is not available
+
+You can undo the routing by hand. Open `$CODEX_HOME/config.toml` and delete
+three things: the `openai_base_url` line, the
+`experimental_realtime_ws_base_url` line, and any `model_catalog_json` line
+ending in `opencodex-catalog.json`. Remove the
+`# Auto-injected by opencodex` comment sitting directly above each of the first
+two along with them.
+
+Go by the key name, not by the comment. opencodex uses the same ownership
+comment above other keys it manages, such as an injected
+`developer_instructions`, and deleting those will not help you sign in while
+costing you configuration you may want back.
+
+Delete the `model_catalog_json` line **with** the routing, not on its own. A
+`model_catalog_json` that names a file which no longer exists makes Codex fail
+to load its configuration at all, which looks like the same lockout for a
+different reason.
+
+## Accounts that would not add or display
+
+Failures adding accounts to the pool, or added accounts not appearing, are a
+separate matter from the lockout above, even when they happen in the same
+session. The account pool is served by the proxy's management API, so both the
+`ocx account login openai` flow and the dashboard list need a running proxy
+before anything else can work. The browser sign-in also returns to
+`http://localhost:1455/auth/callback`, a fixed address that cannot move to
+another port. If something else holds port 1455, or a browser cannot be
+launched, use the device flow instead:
+
+```bash
+ocx account login openai --device
+```
+
+See [Codex Integration](/guides/codex-integration/) for what the injection
+writes and how routing is chosen.
diff --git a/docs-site/src/content/docs/zh-cn/getting-started/installation.md b/docs-site/src/content/docs/zh-cn/getting-started/installation.md
index eb5b02ec948..335debd845d 100644
--- a/docs-site/src/content/docs/zh-cn/getting-started/installation.md
+++ b/docs-site/src/content/docs/zh-cn/getting-started/installation.md
@@ -42,6 +42,18 @@ ocx --version
 opencodex --version
 ```
 
+## 独立二进制文件（无需 npm）
+
+发布包还包含适用于 macOS、Linux 和 Windows 的独立 `ocx` 二进制文件。
+它内置 Bun 运行时和仪表盘，因此无需安装 npm、Node 或单独的 Bun。下载适合你平台的压缩包，解压后运行：
+
+```bash
+./ocx --version
+./ocx start
+```
+
+为了让仪表盘可用，请将解压后的 `gui/dist` 目录保留在二进制文件旁边。
+
 ### 发布渠道
 
 稳定的 `latest` 渠道已经包含 ChatGPT、OpenAI API key、OpenRouter 以及实验性 Cursor 路由所需的
diff --git a/docs-site/src/content/docs/zh-cn/getting-started/quickstart.md b/docs-site/src/content/docs/zh-cn/getting-started/quickstart.md
index e965b159a6b..14f76c58cb9 100644
--- a/docs-site/src/content/docs/zh-cn/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/zh-cn/getting-started/quickstart.md
@@ -5,6 +5,11 @@ description: 配置你的第一个 provider，并在三条命令内让 OpenAI Co
 
 本指南将带你从全新安装，一路走到用一个非 OpenAI 模型运行 Codex。
 
+## 独立二进制文件（无需 npm）
+
+你也可以使用包含 Bun 运行时的发布压缩包中的 `ocx`，无需 npm。
+解压时将 `gui/dist` 目录保留在二进制文件旁边，然后运行 `./ocx start`。
+
 ## 1. 运行设置向导
 
 ```bash
@@ -13,7 +18,7 @@ ocx init
 
 `ocx init` 会引导你完成：
 
-1. **选择 provider** — 从内置 registry 的 95 个预设中选择一个，或选择 `custom` 手动输入 base URL 和 adapter。
+1. **选择 provider** — 从内置 registry 的 96 个预设中选择一个，或选择 `custom` 手动输入 base URL 和 adapter。
 2. **API key** — 粘贴一个 key，或引用一个环境变量，例如 `${ANTHROPIC_API_KEY}`。
 3. **默认模型** — 对于 key、本地和 custom provider，接受预设值或输入模型 id。
 4. **代理端口** — 默认为 `10100`。
diff --git a/docs-site/src/content/docs/zh-cn/guides/claude-code.md b/docs-site/src/content/docs/zh-cn/guides/claude-code.md
index db814d3aef7..746eeba39f4 100644
--- a/docs-site/src/content/docs/zh-cn/guides/claude-code.md
+++ b/docs-site/src/content/docs/zh-cn/guides/claude-code.md
@@ -467,4 +467,4 @@ Claude 模型时自动加载。对于原生透传，这是正常现象；对于
 
 在 `config.json` 中设置 `claudeCode.stabilizePromptCache: true`，可在转换路由上将系统指令末尾受支持的 Claude 提示移到最后一条用户消息。默认值为 `false`。仅在客户端允许这种角色变化时启用。代码围栏内的示例和不匹配的文本会保留，Anthropic 原生透传不变。没有元数据时，缓存键按稳定后的指令计算。该选项不会生成会话标识，也不保证上游缓存命中。
 
-在 OpenCode Go 的 `deepseek-v4.1-flash` Chat 路由上，转换后的时间线系统提醒会自动保留原有位置和 system 角色，并排在尚待返回的工具结果之后。因此，追加提醒不会重写开头的系统提示。无论 `stabilizePromptCache` 是否启用，该行为都会生效；其他模型、目标地址的转换方式以及 Anthropic 原生透传保持不变。缓存复用仍需要稳定的会话标识和可用的上游缓存。修改较早的指令或工具、压缩对话也可能影响缓存命中；仅保留提醒顺序并不保证缓存复用。
+在所有转换后的 Chat 路由上，时间线提醒都会保留在对话中的原有位置（排在尚待返回的工具结果之后）。因此，追加提醒不会重写开头的系统提示，对话中途的指令也不会被挪到它本应跟随的轮次之前。该位置携带哪个角色是单独决定的：除非提供方记录了 `foldDeveloperRoleToSystem: false`，否则提醒以 `system` 发送；该记录表示上游接受 `developer` 角色，此时提醒在同一位置按原样转发。不接受该角色的上游会返回 `400 role 'developer' is not allowed`，这一轮根本无法开始，所以未记录的目的地采用折叠。无论 `stabilizePromptCache` 是否启用，该行为都会生效；Anthropic 原生透传保持不变。缓存复用仍需要稳定的会话标识和可用的上游缓存。修改较早的指令或工具、压缩对话也可能影响缓存命中；仅保留提醒顺序并不保证缓存复用。
diff --git a/docs-site/src/content/docs/zh-cn/guides/codex-integration.md b/docs-site/src/content/docs/zh-cn/guides/codex-integration.md
index 4643248dfe3..94a00079d97 100644
--- a/docs-site/src/content/docs/zh-cn/guides/codex-integration.md
+++ b/docs-site/src/content/docs/zh-cn/guides/codex-integration.md
@@ -20,7 +20,7 @@ Codex 内置的 `openai` provider id，并将该 provider 指向 opencodex：
 ```toml
 # root keys, before the first table
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 openai_base_url = "http://127.0.0.1:10100/v1"
 
 # 仅在设置了 fastMode 时写入；未设置则不会创建 [features] 表
@@ -110,7 +110,7 @@ model_provider = "opencodex"
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
 
 # appended at the end of the file
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 [model_providers.opencodex]
 name = "OpenCodex Proxy"
 base_url = "http://your-host:10100/v1"
@@ -356,7 +356,7 @@ ocx restore back # point plain Codex at the running proxy again
 
 ## 分页历史记录安全拒绝
 
-如果受影响的历史存储支持分页，提供商切换可能返回 `history_paginated_requires_native_writer`。该原因不再拒绝写入 Codex 配置、参考配置档和模型目录。`ocx sync` 与 `ocx start` 仍会写入这些文件并设置 `model_catalog_json`，因此 Codex 模型选择器会继续显示所有经 OpenCodex 路由的模型。只有这一条原因会让会话历史的重新标记停手，因为分页历史序号由 Codex 自己的写入器分配，重试也不会改变。无法读取的状态数据库、身份已变的历史文件、未能运行的预检等其他历史预检原因仍会拒绝整个切换并回滚，因为那些情况以后可能成功。在此状态下，OpenCodex 不会修改分页历史文件或线程行。现有会话保留已标记的提供商，不会被迁移；新会话仍正常经代理路由。重新标记停手时，主目录里已有的 `[model_providers.opencodex]` 表会保留而不是撤下，即便是 root-override（loopback）形式也一样，这样行上标记为 `opencodex` 的会话仍能对应到还存在的提供商 id。可迁移存储中的 legacy 记录也适用。CLI 会打印 `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`。`ocx restore` 和移除 Codex 配置仍会因 `history_paginated_requires_native_writer` 被拒绝。线程行仍在引用时撤掉 `[model_providers.opencodex]` 定义会使这些会话无法解析，而恢复路径没有办法留下兼容提供商表。已经分页的主目录目前无法通过产品卸载；这是已知的未完成工作，而非预期行为。
+如果受影响的历史存储支持分页，提供商切换可能返回 `history_paginated_requires_native_writer`。该原因不再拒绝写入 Codex 配置、参考配置档和模型目录。`ocx sync` 与 `ocx start` 仍会写入这些文件并设置 `model_catalog_json`，因此 Codex 模型选择器会继续显示所有经 OpenCodex 路由的模型。只有这一条原因会让会话历史的重新标记停手，因为分页历史序号由 Codex 自己的写入器分配，重试也不会改变。无法读取的状态数据库、身份已变的历史文件、未能运行的预检等其他历史预检原因仍会拒绝整个切换并回滚，因为那些情况以后可能成功。在此状态下，OpenCodex 不会修改分页历史文件或线程行。现有会话保留已标记的提供商，不会被迁移；新会话仍正常经代理路由。重新标记停手时，主目录里已有的 `[model_providers.opencodex]` 表会保留而不是撤下，即便是 root-override（loopback）形式也一样，这样行上标记为 `opencodex` 的会话仍能对应到还存在的提供商 id。可迁移存储中的 legacy 记录也适用。CLI 会打印 `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`。`ocx restore`、`ocx stop` 和 `ocx uninstall` 不再因 `history_paginated_requires_native_writer` 被拒绝。它们会移除 OpenCodex 写入的全部根路由键，并把 `[model_providers.opencodex]` 定义保留在磁盘上，因此行上仍指向该提供商的会话依旧可以解析，而裸 `codex` 不再指向代理。结果会报告为部分恢复并列出保留的行；`ocx restore --remove-codex-provider-table` 会连这些行一并删除，之后那些会话将无法打开。另外，在 Codex 已把 `openai` 标记会话迁移为分页历史的主目录上启用提供商表形式的集成，过去会以 `history_paginated_openai_requires_native_writer` 整体拒绝：什么都不写，集成保持关闭。现在 OpenCodex 会保留受管的根 `openai_base_url` 覆盖，与 `[model_providers.opencodex]` 表并存，从而完成这次切换。Codex 会把该覆盖合并到内置 `openai` 提供商上，所以那些会话无需重新标记即可继续到达代理，历史文件与线程行都不会被改动。只有需要 `x-opencodex-api-key` 准入标头的路由形式仍会拒绝，因为 Codex 内置提供商无法携带该标头；此时消息会点名两个可行设置——让 Codex 走回环监听器以便保留该覆盖，或把 `syncResumeHistory` 设为 `false`，接受那些会话转向 Codex 自己的 OpenAI 端点。
 
 返回根 URL 覆盖模式时，即使历史预检通过，OpenCodex 也会在提交配置前保留已有的 `[model_providers.opencodex]` 定义。这样，即使 Codex 在提交后或后台历史任务启动时迁移历史格式，旧的 `opencodex` 对话仍能找到其提供商。新对话继续使用所选的根提供商；显式恢复仍执行原有的独立删除检查。
 
diff --git a/docs-site/src/content/docs/zh-cn/guides/macos-menu-bar.md b/docs-site/src/content/docs/zh-cn/guides/macos-menu-bar.md
new file mode 100644
index 00000000000..2f3dc02616e
--- /dev/null
+++ b/docs-site/src/content/docs/zh-cn/guides/macos-menu-bar.md
@@ -0,0 +1,150 @@
+---
+title: macOS 菜单栏应用
+description: 在菜单栏中查看 OpenCodex 代理状态、用量和各提供商配额的原生应用。
+---
+
+菜单栏应用让你无需打开仪表板，就能看到代理状态、近期用量和各提供商的配额压力。
+
+它与代理是两个独立的程序。`ocx` 照常运行，菜单栏应用只是连接本地管理 API 的客户端。
+
+## 桌面应用（Tauri）
+
+同一个仪表板也可以在 OpenCodex 桌面应用中运行。用量面板会显示匹配操作系统的安装步骤；
+在桌面壳中选择**在浏览器中打开**，即可在普通浏览器中打开当前页面。
+
+## 安装
+
+推荐使用 OpenCodex 桌面应用安装。从[发布页面](https://github.com/lidge-jun/opencodex/releases)下载 macOS 的
+`OpenCodex-<version>-macos.dmg`，打开 DMG 后将 `OpenCodex.app` 拖到「应用程序」文件夹。
+Windows 运行 `OpenCodex-<version>-windows-x64.msi`，Linux 使用 AppImage 或
+`OpenCodex-<version>-linux-amd64.deb`。
+
+```bash
+chmod +x OpenCodex-<version>-linux-x86_64.AppImage
+sudo apt install ./OpenCodex-<version>-linux-amd64.deb
+```
+
+Windows SmartScreen 或 macOS Gatekeeper 可能显示警告。应用会连接现有的 `ocx` 代理；
+找不到代理时则启动内置 sidecar。
+
+## 首次启动：Gatekeeper
+
+**首次启动会被阻止。** macOS 会提示：
+
+> 无法打开“OpenCodex.app”，因为无法验证开发者。
+
+这是预期行为，所以这里说明原因而不是直接略过。Gatekeeper 需要 Apple 的 Developer ID 签名和
+公证（notarization）票据，两者都需要付费的 Apple Developer 账号。OpenCodex 没有该账号，因此
+应用以 ad-hoc 签名发布：程序包本身完整、签名有效，但 Apple 并未为发布者背书。
+
+仍要打开：
+
+1. 在 Finder 中右键点击（或按住 Control 点击）`OpenCodex.app`。
+2. 选择**打开**。
+3. 在弹出的对话框中再次点击**打开**。
+
+如果对话框没有「打开」按钮，请前往**系统设置 → 隐私与安全性**，找到被拦截的提示并点击
+**仍要打开**。
+
+macOS 会记住这个选择，因此每个版本只需操作一次。
+
+也可以在终端移除隔离属性：
+
+```bash
+xattr -d com.apple.quarantine /Applications/OpenCodex.app
+```
+
+如果两种方式都不想用，可以自行构建——本地构建不会带有隔离属性。参见[从源码构建](#从源码构建)。
+
+## 显示的内容
+
+菜单栏图标用形状而非颜色表示状态，因为 macOS 菜单栏图标按惯例是单色的：
+
+| 图标 | 含义 |
+| --- | --- |
+| 实心标记 | 运行中，路由受保护 |
+| 带缺口的实心标记 | 运行中，但路由保护存在风险 |
+| 轮廓标记 | 正在检查，或响应异常 |
+| 淡色轮廓 | 未运行，或需要 API 密钥 |
+
+点击图标会打开包含四个部分的面板。
+
+**状态** — 代理是否运行、应用正在使用的回环地址以及保护状态。当代理给出修复命令（例如
+`ocx service install`）时，会以可选中的文本显示。应用不会替你执行。
+
+**用量** — 最近 7 天的请求数、令牌数和预估成本，以及每日趋势。请求数后的 `~` 表示其中一部分
+是估算值，而非提供商上报的数据。
+
+默认情况下，菜单栏标题显示令牌总数；如果您更想查看请求数、成本、配额，或只显示图标，可在控制台 Usage 的 Companion 设置中更改标题指标。
+在 macOS 26 中，弹出面板和小组件采用 Liquid Glass；更早版本的 macOS 使用标准弹出面板材质。
+
+**配额** — 每个提供商一行，显示压力最大的那个窗口。如果某个提供商 5 小时额度用了 99%、月度
+额度只用了 10%，会显示 5 小时的数值，因为真正卡住你的是它。窗口名称标注在提供商下方，因此
+`API usage 的 42%` 和`一个月的 42%` 不会混淆。
+
+**提供商** — 可展开的列表，每个提供商带一个开关。默认提供商在启用状态下开关是锁定的，因为
+代理会拒绝停用默认提供商；请先在仪表板中更换默认值。
+
+## 可以做什么
+
+- **Dashboard** — 在浏览器中打开 Web 仪表板。
+- **Stop proxy** — 确认后停止代理。这里刻意不叫「重启」：停止会同时停掉 launchd 服务，代理不会
+  自动恢复。停止后面板会显示重新启动的命令。
+- **提供商开关** — 启用或停用某个提供商。
+
+账号、模型配置、存储等其余操作仍在仪表板中完成。
+
+## 小组件
+
+在桌面上右键点击，选择**编辑小组件**，然后添加 **OpenCodex**。它显示代理状态、今日用量和
+配额，并使用与菜单栏应用相同的隐私安全快照。应用轮询时小组件会刷新。需要 macOS 14 或更高
+版本；它不会接收 API 密钥或原始账户信息。
+
+## 连接到代理
+
+应用会自动查找。它读取 `~/.opencodex/runtime-port.json`（或
+`$OPENCODEX_HOME/runtime-port.json`），找不到则使用端口 `10100`。该文件只提供端口，主机始终
+为回环地址。
+
+如果代理绑定在非回环地址上，就需要 API 密钥。面板会说明这一点并提供前往仪表板的按钮。
+
+**该路径尚未支持。** 应用会从 macOS 钥匙串读取密钥并重试一次，但没有输入密钥的界面，也没有
+手动写入的办法——它是数据保护钥匙串条目，「钥匙串访问」无法创建。因此在非回环绑定下，面板会
+一直停在「Needs API key」。
+
+默认的回环代理不需要密钥。原生密钥输入已在计划中。
+
+## 轮询
+
+应用刻意保持安静。存活检查每 5 秒一次；开销较大的聚合数据（用量和配额）只在面板打开时获取，
+且最多每分钟一次。连续三次失败后会退避到 30 秒一次，以免不断敲打你主动停掉的代理。
+
+## 从源码构建
+
+需要 macOS 13 或更高版本、Xcode Command Line Tools 以及 [Bun](https://bun.sh)：
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+bun run prepare-sidecar
+bun run prepare-widget
+bunx tauri build
+```
+
+程序包会生成在 Tauri 的发布输出中，WidgetKit 扩展位于
+`OpenCodex.app/Contents/PlugIns/`。
+
+构建通用二进制（`UNIVERSAL=1`）需要完整的 Xcode。Command Line Tools 只包含当前架构的 Swift
+兼容库，此时构建会给出说明信息，而不是抛出链接器错误。
+
+如果钥匙串中有 Developer ID 证书，可以设置 `MACOS_SIGN_IDENTITY`，以 hardened runtime 签名
+替代 ad-hoc 签名：
+
+```bash
+MACOS_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" bun run prepare-widget
+```
+
+## 卸载
+
+把 `OpenCodex.app` 拖到废纸篓即可。应用不会留下偏好设置或其他状态文件，目前也不会在钥匙串中
+保存任何内容。
diff --git a/docs-site/src/content/docs/zh-cn/guides/providers.md b/docs-site/src/content/docs/zh-cn/guides/providers.md
index d2f4d1b5f5e..d799f306705 100644
--- a/docs-site/src/content/docs/zh-cn/guides/providers.md
+++ b/docs-site/src/content/docs/zh-cn/guides/providers.md
@@ -101,7 +101,7 @@ ocx logout <provider>
 | --- | --- | --- | --- |
 | `xai` | `openai-chat` | `https://cli-chat-proxy.grok.com/v1` | OAuth 使用独立的 Grok CLI 订阅网关。API 密钥覆盖模式使用 `https://api.x.ai/v1`，并可能注入 Priority Processing。优先使用实时 Grok 目录；回退默认模型为 `grok-4.5`。 |
 | `anthropic` | `anthropic` | `https://api.anthropic.com` | Claude 模型；实时模型列表从 `/v1/models` 获取。 |
-| `kimi` | `openai-chat` | `https://api.kimi.com/coding/v1` | Kimi K2.7/K2.6/K2.5 编程模型。 |
+| `kimi` | `openai-chat` | `https://api.kimi.com/coding/v1` | Kimi Code Plan 编程模型。默认使用稳定的 `kimi-for-coding` 别名（当前指向 K2.8 Preview）：100 万 token 上下文、可调 `low`/`high`/`max` 思考档（默认 `max`）、支持文本 + 图片输入。已下架的 `kimi-k2.x` 选择会在升级时自动迁移到该别名。 |
 | `nous` | `openai-chat` | `https://inference-api.nousresearch.com/v1` | Nous Research 订阅网关（与 Hermes Agent 使用同一后端）。通过设备授权登录 `portal.nousresearch.com`；access 令牌是每个请求的 inference JWT。付费 + `:free` 模型混合目录（`tencent/hy3:free`、`stepfun/step-3.7-flash:free` 等）会从已登录账户实时发现。Refresh 令牌是单次使用，每次刷新都会轮换。 |
 | `kiro` | `kiro` | `https://runtime.us-east-1.kiro.dev` | 首次登录会导入已安装并已登录的 Kiro CLI 会话（Unix 使用 `curl -fsSL https://cli.kiro.dev/install` &#124; `bash`；Windows PowerShell 使用 `irm 'https://cli.kiro.dev/install.ps1'` &#124; `iex`；然后运行 `kiro-cli login`）。**添加账户**会先退出 `kiro-cli`，再启动新的浏览器登录，从而切换 `kiro-cli` 自身使用的账户，并保存账户范围的配置文件元数据。现有 OpenCodex 账户会保留；如果取消或失败，则恢复之前的 `kiro-cli` 会话。 |
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | 通过 Cloud Code Assist 协议使用 Google OAuth。实时发现调用已认证的 CCA `v1internal:fetchAvailableModels` 端点，并仅发布当前登录账户可用的 agent 模型；维护中的目录仍作为回退。 |
@@ -173,7 +173,7 @@ Kiro 登录需要 Kiro CLI：Unix 使用 `curl -fsSL https://cli.kiro.dev/instal
 
 ## 3. API 密钥目录
 
-opencodex 内置 95 个预设：79 个密钥预设、12 个 OAuth 预设、3 个本地预设，以及 1 个默认的
+opencodex 内置 96 个预设：80 个密钥预设、12 个 OAuth 预设、3 个本地预设，以及 1 个默认的
 ChatGPT 转发预设。仪表盘的 **Add provider** 选择器会打开密钥提供商的控制台，验证并保存密钥。
 验证因提供商而异。主要条目包括：
 
diff --git a/docs-site/src/content/docs/zh-cn/reference/cli/lifecycle.md b/docs-site/src/content/docs/zh-cn/reference/cli/lifecycle.md
index 30687e2b81e..b1fdef059a3 100644
--- a/docs-site/src/content/docs/zh-cn/reference/cli/lifecycle.md
+++ b/docs-site/src/content/docs/zh-cn/reference/cli/lifecycle.md
@@ -259,6 +259,7 @@ ocx codex-shim uninstall
 ### `ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`
 
 安装并控制 Windows 状态托盘图标。它会在 Windows 登录时启动，并提供一键代理控制。`start` 和 `stop` 只控制图标本身；要控制代理，请使用其菜单。`--no-start` 适用于 `install`，会安装托盘但不会立即启动。
+已弃用：OpenCodex 桌面应用在 Windows、macOS 和 Linux 上提供托盘；没有桌面应用的安装仍可使用 `ocx tray`。
 
 ## 仪表盘
 
diff --git a/docs-site/src/content/docs/zh-cn/reference/configuration/providers.md b/docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
index e0e61490a1d..85a12fa08ba 100644
--- a/docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
@@ -125,11 +125,13 @@ selector，而不是分配一个新名称。
 | `noPenaltyModels?` | `string[]` | 会拒绝 presence/frequency penalty 的模型。 |
 | `noStructuredOutputModels?` | `string[]` | `openai-chat` 端点拒绝 `response_format` 的精确模型 ID。仅当请求模型与条目完全匹配时才省略该字段；其他 `openai-chat` 模型仍启用 structured-output 转换。 |
 | `noJsonSchemaModels?` | `string[]` | `openai-chat` 端点拒绝 `json_schema` 形式但仍接受 `json_object` 的精确模型 ID。这类请求会降级为 `json_object` 而不是被丢弃，因此请求 JSON 的调用方仍能拿到 JSON。同一模型同时出现在两个列表时，以 `noStructuredOutputModels` 为准。`opencode go`、`opencode zen`、`opencode free` 预设已为其 DeepSeek 路由内置该项。 |
+| `foldDeveloperRoleToSystem?` | `boolean` | 记录某个 `openai-chat` 目的地是否接受 `developer` 角色。`foldDeveloperRoleToSystem` 未设置时按 `system` 发送，`true` 时按 `system` 发送，`false` 时按 `developer` 发送。未设置表示尚未记录该目的地的情况；`true` 记录上游拒绝该角色；`false` 记录其接受该角色。无论哪种情况，消息都保留在对话中的原有位置，只有角色改变。拒绝该角色的目的地会返回 `400 role 'developer' is not allowed`，这一轮根本无法开始，这就是未记录状态默认折叠的原因。 |
 | `parallelToolCalls?` | `boolean` | 切换并行工具调用。OpenAI Chat 默认开启；非 chat 适配器只有显式 `true` 时才会声明支持。 |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | 默认关闭的下游 SSE 修复，用于精确占位 id、缺失的终止 id，以及（`repairInvalidIds`）缺少规范 `msg_`/`rs_` 前缀的 message/reasoning id。function-call id 永远不会被重写。内置 DeepSeek 默认启用后两项。 |
 | `responsesSnapshotRepair?` | `boolean` | 默认关闭的客户端修复，用于补全 SSE 与 JSON 中稀疏 Responses 生命周期快照缺失的 status、output 和工具元数据；原始检查与持久化保持不变。 |
 | `retryOn429?` | `{ enabled?: boolean; attempts?: number; intervalMs?: number; maxIntervalMs?: number; respectRetryAfter?: boolean }` | 仅限 API-key 提供商（`authMode: "key"`）。可选的同目标 429 重试：未配置 `retryOn429` 时功能关闭；对象存在即启用，除非 `enabled: false`。收到 429 时等待（上游 `Retry-After` 或固定间隔）后在相同 key 上重放完全相同请求，再进入任何 key 故障转移——覆盖主文本恢复循环、Responses passthrough、图像/视频桥、web-search 侧车与终结续接。重放仅适用于流开始前的 HTTP 429 响应；自定义 `runTurn` 传输不在 HTTP 重试循环范围内。`attempts` 是首个 429 之后的同 key 重放次数（总发送次数 = `attempts` + 1），是主恢复循环、终结守卫续接与桥接重试共享的按请求统一预算；`attempts` 耗尽只会停止进一步的同 key 重放：随后按可用目标进行正常的 key 故障转移或最终错误处理——key 认证的 passthrough 线路上没有故障转移，因此耗尽的 429 会原样透出。Codex 自身从不重试 429，因此这是单 key 提供商唯一的防线。默认值：`enabled: true`、`attempts: 3`、`intervalMs: 5000`、`maxIntervalMs: 60000`（单次等待以 `maxIntervalMs` 为上限，其本身上限 600000）、`respectRetryAfter: true`。 |
 | `transientRetryOn5xx?` | `{ enabled?: boolean; attempts?: number }` | 仅限使用 key 认证的 `openai-chat` 与 `openai-responses` 提供商。`authMode: "forward"` 的提供商（ChatGPT 账号池）从不读取此选项，保持默认重试次数。可选的流开始前上游瞬态状态码（500、502、503、504、520、521、522）重试：未配置时关闭；对象存在即启用，除非 `enabled: false`。覆盖初始 Responses 请求、终结守卫续接、原生 `/v1/chat/completions`，以及 429/账户恢复重新获取。`attempts` 是单个请求允许向上游发送的总次数，包含首次发送（1..10，默认 3）；它是与连接重置恢复共享的按请求预算，因此 `3` 表示最多只有三个实际请求到达提供商。等待采用固定 400 毫秒的指数退避，上限为 5 秒，并遵循 `Retry-After`。此选项独立于处理速率限制的 `retryOn429`；流开始后的故障绝不会重放。 |
+| `retryOnReset?` | `{ enabled?: boolean; replacements?: number }` | 仅限原生 `openai-responses` 提供商，包含 `authMode: "forward"`。可选地替换一次在调用方尚未观察到任何内容时就失败的发送：未配置时关闭；对象存在即启用，除非 `enabled: false`。涵盖两个不确定阶段——响应头到达前连接断开，以及响应头之后 SSE 正文只承载控制事件时断开。只有自包含的请求才会被替换：`store: false`、完整的 `input`、没有 `previous_response_id`／`conversation`／`stream_id`，且只使用由客户端执行的工具。`replacements` 是单个逻辑请求在所有环节和所有组合子请求中可以进行的替换发送次数（1..2，默认 1）；它既不是按环节的重试次数，也不是发送预算，因此替换发送仍必须落在该环节已有的发送额度之内。已经产生输出或工具调用的请求，无论此值为何都不会被替换。如果上游已经开始了第一次推理，被替换的推理仍可能计费，因此该选项默认关闭。 |
 | `autoToolChoiceOnlyModels?` | `string[]` | `tool_choice` 只接受 `auto` 或 `none` 的模型；强制选择会被降级。 |
 | `preserveReasoningContentModels?` | `string[]` | 需要在聊天历史中保留先前 assistant `reasoning_content` 的模型。 |
 | `reasoningDetailsModels?` | `string[]` | 以结构化 `reasoning_details` 数组返回思考内容的模型（启用 `reasoning_split` 的 MiniMax M 系列）；流式增量为累积快照，按前缀差分处理，保留的推理以 `reasoning_details` 数组而非 `reasoning_content` 字符串回放。 |
diff --git a/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md b/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md
index 3af31658c5a..a0e17af51a2 100644
--- a/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md
+++ b/docs-site/src/content/docs/zh-tw/getting-started/quickstart.md
@@ -13,7 +13,7 @@ ocx init
 
 `ocx init` 會引導你完成:
 
-1. **選擇 provider** —— 從內建 registry 的 95 個預設中選擇一個，或選擇 `custom` 手動輸入
+1. **選擇 provider** —— 從內建 registry 的 96 個預設中選擇一個，或選擇 `custom` 手動輸入
    base URL 和 adapter。
 2. **API key** —— 貼上一個 key,或引用一個環境變數,例如 `${ANTHROPIC_API_KEY}`。
 3. **預設模型** —— 對於 API key、本機和 custom provider，可接受預設值或輸入模型 id。
diff --git a/docs-site/src/content/docs/zh-tw/guides/claude-code.md b/docs-site/src/content/docs/zh-tw/guides/claude-code.md
index 493aeea9a5b..fc35c52b399 100644
--- a/docs-site/src/content/docs/zh-tw/guides/claude-code.md
+++ b/docs-site/src/content/docs/zh-tw/guides/claude-code.md
@@ -538,4 +538,4 @@ Claude 模型時自動載入。對於原生透傳，這是正常現象；對於
 
 在 `config.json` 中設定 `claudeCode.stabilizePromptCache: true`，可在轉換路由上將系統指令末尾支援的 Claude 提示移到最後一則使用者訊息。預設值為 `false`。僅在用戶端允許這種角色變更時啟用。程式碼圍欄中的範例和不符合的文字會保留，Anthropic 原生轉送不變。沒有中繼資料時，快取鍵依穩定後的指令計算。此選項不會產生對話識別碼，也不保證上游快取命中。
 
-在 OpenCode Go 的 `deepseek-v4.1-flash` Chat 路由上，轉換後的時間線系統提醒會自動保留原有位置和 system 角色，並排在尚待傳回的工具結果之後。因此，新增提醒不會重寫開頭的系統提示。無論 `stabilizePromptCache` 是否啟用，此行為都會生效；其他模型、目標位址的轉換方式以及 Anthropic 原生轉送維持不變。快取重用仍需要穩定的工作階段識別碼和可用的上游快取。修改較早的指令或工具、壓縮對話也可能影響快取命中；僅保留提醒順序並不保證快取重用。
+在所有轉換後的 Chat 路由上，時間線提醒都會保留在對話中的原有位置（排在尚待傳回的工具結果之後）。因此，新增提醒不會重寫開頭的系統提示，對話中途的指令也不會被移到它原本應跟隨的輪次之前。該位置攜帶哪個角色是另外決定的：除非提供者記錄了 `foldDeveloperRoleToSystem: false`，否則提醒以 `system` 傳送；該記錄表示上游接受 `developer` 角色，此時提醒在相同位置照原樣轉送。不接受該角色的上游會回應 `400 role 'developer' is not allowed`，該回合根本無法開始，所以未記錄的目的地採用摺疊。無論 `stabilizePromptCache` 是否啟用，此行為都會生效；Anthropic 原生轉送維持不變。快取重用仍需要穩定的工作階段識別碼和可用的上游快取。修改較早的指令或工具、壓縮對話也可能影響快取命中；僅保留提醒順序並不保證快取重用。
diff --git a/docs-site/src/content/docs/zh-tw/guides/codex-integration.md b/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
index 274ae984599..15b740e5743 100644
--- a/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
+++ b/docs-site/src/content/docs/zh-tw/guides/codex-integration.md
@@ -19,7 +19,7 @@ bearer。這些路徑不會彼此 fallback。shipped v1 設定會遷移到 marke
 ```toml
 # 根級鍵，必須位於第一個 table 之前
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 openai_base_url = "http://127.0.0.1:10100/v1"
 
 # 僅在設定 fastMode 時寫入；未設定時不新增 [features] table
@@ -107,7 +107,7 @@ model_provider = "opencodex"
 model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
 
 # 追加到檔案末尾
-# Auto-injected by opencodex
+# Auto-injected by opencodex (undo: ocx restore)
 [model_providers.opencodex]
 name = "OpenCodex Proxy"
 base_url = "http://your-host:10100/v1"
@@ -363,7 +363,7 @@ ocx restore back # 讓普通 Codex 再次指向仍在執行的 proxy
 
 ## 分頁歷史記錄安全拒絕
 
-如果受影響的歷史儲存區支援分頁，提供者切換可能傳回 `history_paginated_requires_native_writer`。此原因不再拒絕寫入 Codex 設定、參考設定檔與模型目錄。`ocx sync` 與 `ocx start` 仍會寫入這些檔案並設定 `model_catalog_json`，因此 Codex 模型選擇器會繼續顯示所有經 OpenCodex 路由的模型。只有這一條原因會讓對話歷史的重新標記停手，因為分頁歷史序號由 Codex 自己的寫入器分配，重試也不會改變。無法讀取的狀態資料庫、身分已變的歷史檔案、未能執行的預檢等其他歷史預檢原因仍會拒絕整個切換並回復，因為那些情況以後可能成功。在此狀態下，OpenCodex 不會修改分頁歷史檔案或執行緒列。既有對話保留已標記的提供者，不會被遷移；新對話仍正常經代理路由。重新標記停手時，家目錄裡既有的 `[model_providers.opencodex]` 表會保留而不是撤下，即便是 root-override（loopback）形式也一樣，這樣列上標記為 `opencodex` 的對話仍能對應到還存在的提供者 id。可遷移儲存區中的 legacy 記錄也適用。CLI 會印出 `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`。`ocx restore` 與移除 Codex 設定仍會因 `history_paginated_requires_native_writer` 被拒絕。執行緒列仍在參照時撤掉 `[model_providers.opencodex]` 定義會使這些對話無法解析，而復原路徑沒有辦法留下相容提供者表。已經分頁的家目錄目前無法透過產品解除安裝；這是已知的未完成工作，而非預期行為。
+如果受影響的歷史儲存區支援分頁，提供者切換可能傳回 `history_paginated_requires_native_writer`。此原因不再拒絕寫入 Codex 設定、參考設定檔與模型目錄。`ocx sync` 與 `ocx start` 仍會寫入這些檔案並設定 `model_catalog_json`，因此 Codex 模型選擇器會繼續顯示所有經 OpenCodex 路由的模型。只有這一條原因會讓對話歷史的重新標記停手，因為分頁歷史序號由 Codex 自己的寫入器分配，重試也不會改變。無法讀取的狀態資料庫、身分已變的歷史檔案、未能執行的預檢等其他歷史預檢原因仍會拒絕整個切換並回復，因為那些情況以後可能成功。在此狀態下，OpenCodex 不會修改分頁歷史檔案或執行緒列。既有對話保留已標記的提供者，不會被遷移；新對話仍正常經代理路由。重新標記停手時，家目錄裡既有的 `[model_providers.opencodex]` 表會保留而不是撤下，即便是 root-override（loopback）形式也一樣，這樣列上標記為 `opencodex` 的對話仍能對應到還存在的提供者 id。可遷移儲存區中的 legacy 記錄也適用。CLI 會印出 `Codex resume history: left to Codex's native writer (history_paginated_requires_native_writer)`。`ocx restore`、`ocx stop` 與 `ocx uninstall` 不再因 `history_paginated_requires_native_writer` 被拒絕。它們會移除 OpenCodex 寫入的所有根路由鍵，並把 `[model_providers.opencodex]` 定義留在磁碟上，因此列上仍指向該提供者的對話依舊可以解析，而純 `codex` 不再指向代理。結果會回報為部分復原並列出保留的列；`ocx restore --remove-codex-provider-table` 會連這些列一併刪除，之後那些對話將無法開啟。另外，在 Codex 已把 `openai` 標記對話遷移為分頁歷史的家目錄上啟用提供者表形式的整合，過去會以 `history_paginated_openai_requires_native_writer` 整體拒絕：什麼都不寫，整合維持關閉。現在 OpenCodex 會保留受管的根 `openai_base_url` 覆寫，與 `[model_providers.opencodex]` 表並存，藉此完成這次切換。Codex 會把該覆寫合併到內建 `openai` 提供者上，所以那些對話無需重新標記即可繼續抵達代理，歷史檔案與執行緒列都不會被更動。只有需要 `x-opencodex-api-key` 准入標頭的路由形式仍會拒絕，因為 Codex 內建提供者無法攜帶該標頭；此時訊息會點名兩個可行設定——讓 Codex 走回送監聽器以便保留該覆寫，或把 `syncResumeHistory` 設為 `false`，接受那些對話轉向 Codex 自己的 OpenAI 端點。
 
 返回根 URL 覆寫模式時，即使歷史預檢通過，OpenCodex 也會在提交設定前保留既有的 `[model_providers.opencodex]` 定義。如此一來，即使 Codex 在提交後或背景歷史工作啟動時遷移歷史格式，舊的 `opencodex` 對話仍能找到其提供者。新對話繼續使用所選的根提供者；明確要求的還原仍執行原有的獨立刪除檢查。
 
diff --git a/docs-site/src/content/docs/zh-tw/guides/integrations.md b/docs-site/src/content/docs/zh-tw/guides/integrations.md
index c0f9ef2bf82..83f5cc7cf6a 100644
--- a/docs-site/src/content/docs/zh-tw/guides/integrations.md
+++ b/docs-site/src/content/docs/zh-tw/guides/integrations.md
@@ -165,6 +165,27 @@ OAuth 或 API key，並拒絕 `--api-key`、`--base-url` 與 `--region` 覆寫
 
 客戶端細節是針對各專案自己的設定格式驗證過的；檢查了什麼、何時檢查，請見 `devlog/_fin/260802_client_toggle_api/002_client_toggle_matrix.md` 中的研究筆記。
 
+## ZCode 3.14 以後
+
+ZCode 3.14 把自訂供應商移到 `~/.zcode/v2/provider_config.json`，而本整合原本寫入的
+`~/.zcode/v2/config.json` 只剩下一次性匯入會讀取，而那次匯入只在新檔案不存在時執行。ZCode 首次啟動
+就會建立新檔案，因此只要曾經啟動過的安裝，匯入早已用掉，之後寫入 `config.json` 不會被任何東西讀到。
+
+在可行的情況下，opencodex 現在直接寫入 `provider_config.json`。啟用整合會把 `opencodex` 供應商規則
+加進該檔案，目錄重新整理會更新它，停用則精確移除 opencodex 放進去的內容。檔案中其他規則一律保持原樣，
+包含其他供應商為某個同樣出現在我們這裡的模型 ID 所保留的規則。帶有 `opencodex` ID 但不是 opencodex
+寫入的規則屬於衝突，而不是可以接管的東西：請在 ZCode 中處理，或使用明確的覆寫。
+
+仍有兩種情況會拒絕而不寫入。ZCode 搬移儲存位置之前由 opencodex 寫入的區塊，會讓整合留在
+`config.json`：請先在那裡停用，再重新啟用以寫入新的儲存檔。至於 `schemaVersion` 不是 opencodex
+曾觀察過的 `provider_config.json`，則只會被回報而不會合併：該檔案存放 ZCode 的所有供應商，對它斷言
+一種結構等於把靜默的無效果換成靜默的資料遺失。只要整合不是在寫那個檔案，狀態頁就會指出 ZCode 實際
+讀取的檔案。
+
+在第二種情況下，請在 ZCode 自己的設定中新增供應商：base URL 為 `http://127.0.0.1:10100/v1`
+（請依實際繫結調整連接埠）、任意非空白金鑰，以及 `ocx export --client zcode` 列出的模型 ID。不支援
+刪除 `provider_config.json` 來重新觸發 ZCode 的匯入：那會丟掉 ZCode 存放在其中的所有供應商。
+
 ## Cline CLI
 
 Cline CLI 使用 providers.json 與 models.json。修改或同步前請結束 Cline，完成後重新啟動。復原會還原兩個原始檔案，預設供應商保持不變。此整合不會遷移舊版 VS Code 擴充功能的儲存資料。
diff --git a/docs-site/src/content/docs/zh-tw/guides/providers.md b/docs-site/src/content/docs/zh-tw/guides/providers.md
index 47594ee2578..44263dc002f 100644
--- a/docs-site/src/content/docs/zh-tw/guides/providers.md
+++ b/docs-site/src/content/docs/zh-tw/guides/providers.md
@@ -239,7 +239,7 @@ database 並移除目前的 WAL、SHM 與 journal sidecar，再發布先前的 s
 
 ## 3. API 金鑰目錄
 
-opencodex 內建 95 個 preset：79 個 key-based、12 個 OAuth、3 個 local，以及 1 個預設 ChatGPT-forward
+opencodex 內建 96 個 preset：80 個 key-based、12 個 OAuth、3 個 local，以及 1 個預設 ChatGPT-forward
 preset。儀表板的 **Add provider** picker 會開啟 key provider 的 dashboard、驗證金鑰並儲存；驗證方式
 依 provider 而異。主要條目如下。
 
diff --git a/docs-site/src/content/docs/zh-tw/reference/cli/lifecycle.md b/docs-site/src/content/docs/zh-tw/reference/cli/lifecycle.md
index d9c104d3c91..4317ef37b30 100644
--- a/docs-site/src/content/docs/zh-tw/reference/cli/lifecycle.md
+++ b/docs-site/src/content/docs/zh-tw/reference/cli/lifecycle.md
@@ -244,6 +244,7 @@ ocx codex-shim uninstall
 ### `ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`
 
 安裝並控制 Windows 狀態列圖示。它在 Windows 登入時啟動並提供一鍵代理控制。`start` 與 `stop` 僅控制圖示；請用其選單控制代理。`--no-start` 適用於 `install`，並在不立即啟動它的情況下安裝 tray。
+已淘汰：OpenCodex 桌面應用程式在 Windows、macOS 與 Linux 提供系統匣；沒有桌面應用程式的安裝仍可使用 `ocx tray`。
 
 ## 儀表板
 
diff --git a/docs-site/src/content/docs/zh-tw/reference/configuration/providers.md b/docs-site/src/content/docs/zh-tw/reference/configuration/providers.md
index 395ec06ec77..cdbd005d00f 100644
--- a/docs-site/src/content/docs/zh-tw/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/zh-tw/reference/configuration/providers.md
@@ -99,9 +99,11 @@ ocx models provider openrouter on
 | `noPenaltyModels?` | `string[]` | 拒絕 presence/frequency penalty 的模型。 |
 | `noStructuredOutputModels?` | `string[]` | 其 `openai-chat` 端點拒絕 `response_format` 的精確模型 ID。僅精確符合的請求模型會省略該欄位；structured-output 轉譯對其他每個 `openai-chat` 模型保持啟用。 |
 | `noJsonSchemaModels?` | `string[]` | 其 `openai-chat` 端點拒絕 `json_schema` 形式但仍接受 `json_object` 的精確模型 ID。這類請求會降級為 `json_object` 而非被丟棄，因此要求 JSON 的呼叫端仍會拿到 JSON。同一模型同時列在兩份清單時，以 `noStructuredOutputModels` 為準。`opencode go`、`opencode zen`、`opencode free` 預設已為其 DeepSeek 路由內建。 |
+| `foldDeveloperRoleToSystem?` | `boolean` | 記錄某個 `openai-chat` 目的地是否接受 `developer` 角色。`foldDeveloperRoleToSystem` 未設定時以 `system` 傳送，`true` 時以 `system` 傳送，`false` 時以 `developer` 傳送。未設定表示尚未記錄該目的地的情況；`true` 記錄上游拒絕該角色；`false` 記錄其接受該角色。無論何者，訊息都保留在對話中的原有位置，只有角色改變。拒絕該角色的目的地會回應 `400 role 'developer' is not allowed`，該回合根本無法開始，這就是未記錄狀態預設摺疊的原因。 |
 | `parallelToolCalls?` | `boolean` | 切換平行工具呼叫。OpenAI Chat 預設開啟；非 chat adapter 僅在明確 `true` 時廣告。 |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean }` | 預設停用的下游 SSE 修復，用於精確佔位 id 與缺失的終端 id。Function-call id 永不被重寫。 |
 | `transientRetryOn5xx?` | `{ enabled?: boolean; attempts?: number }` | 僅限使用金鑰認證的 `openai-chat` 與 `openai-responses` 供應商。`authMode: "forward"` 的供應商（ChatGPT 帳號池）從不讀取此選項，維持預設重試次數。選擇性重試串流開始前的暫時性上游狀態（500、502、503、504、520、521、522）：未設定時停用；只要有此物件即啟用，除非 `enabled: false`。涵蓋初始 `Responses` 請求、終止防護續接、原生 `/v1/chat/completions`，以及 429／帳號復原的重新擷取。`attempts` 是單一請求允許傳送至上游的總次數，包含第一次（1..10，預設 3）；這是與連線重設復原共用的單一請求範圍預算，因此 `3` 表示最多只有三個實際請求會送達供應商。等待採固定 400 毫秒、上限 5 秒的指數退避，並遵循 `Retry-After`。此機制獨立於處理速率限制的 `retryOn429`；串流中的失敗絕不重播。 |
+| `retryOnReset?` | `{ enabled?: boolean; replacements?: number }` | 僅限原生 `openai-responses` 供應商，包含 `authMode: "forward"`。可選擇性地替換一次在呼叫端尚未觀察到任何內容時就失敗的傳送：未設定時停用；只要有此物件即啟用，除非 `enabled: false`。涵蓋兩個不確定階段——回應標頭抵達前連線中斷，以及標頭之後 SSE 內文只載有控制事件時中斷。只有自我完備的請求才會被替換：`store: false`、完整的 `input`、沒有 `previous_response_id`／`conversation`／`stream_id`，且僅使用由用戶端執行的工具。`replacements` 是單一邏輯請求在所有環節與所有組合子請求中可進行的替換傳送次數（1..2，預設 1）；它既不是各環節的重試次數，也不是傳送預算，因此替換傳送仍必須落在該環節既有的傳送額度之內。已經產生輸出或工具呼叫的請求，無論此值為何都不會被替換。若上游已經開始第一次推論，被替換的推論仍可能計費，因此此選項預設停用。 |
 | `autoToolChoiceOnlyModels?` | `string[]` | 其 `tool_choice` 僅接受 `auto` 或 `none` 的模型；強制選擇被降級。 |
 | `preserveReasoningContentModels?` | `string[]` | 需要在 chat 歷史中保留先前 assistant `reasoning_content` 的模型。 |
 | `reasoningDetailsModels?` | `string[]` | 以結構化 `reasoning_details` 陣列回傳思考內容的模型（啟用 `reasoning_split` 的 MiniMax M 系列）；串流增量為累積快照，以前綴差分處理，保留的推理以 `reasoning_details` 陣列而非 `reasoning_content` 字串重播。 |
diff --git a/docs/design-system/foundations.md b/docs/design-system/foundations.md
index a3b38f9eae5..c3f3dbb39f7 100644
--- a/docs/design-system/foundations.md
+++ b/docs/design-system/foundations.md
@@ -24,7 +24,7 @@
 
 ### Font families
 
-- `--font-ui`: 일반 UI, 제목, 본문, 버튼, 입력. Pretendard/Noto Sans KR/Apple SD Gothic Neo/Malgun Gothic을 포함해 한글 fallback을 보장한다.
+- `--font-ui`: 일반 UI, 제목, 본문, 버튼, 입력. 제품 서체를 우선하고, 그 뒤에는 시스템 UI 폰트를 영문도 지원하는 한글 fallback보다 먼저 선언한다. 그래야 한글 fallback이 시스템 UI 폰트의 영문·숫자 글리프까지 대신 표시하지 않는다. 한글은 앞선 서체의 지원 여부에 따라 시스템의 언어별 fallback 또는 뒤에 선언된 한글 글꼴로 표시한다.
 - `--font-code`: 모델 ID, URL, 버전, 토큰 수, 로그, 코드. 숫자는 tabular 형태로 정렬한다.
 
 외부 CDN 폰트를 사용하지 않는다. 프록시 관리 화면은 오프라인에서도 열려야 하고, 폰트
diff --git a/gui/public/favicon.png b/gui/public/favicon.png
index 3a50bfa241d..8827b1fdc27 100644
Binary files a/gui/public/favicon.png and b/gui/public/favicon.png differ
diff --git a/gui/public/provider-icons/stepfun-color.svg b/gui/public/provider-icons/stepfun-color.svg
new file mode 100644
index 00000000000..7d04a37bc80
--- /dev/null
+++ b/gui/public/provider-icons/stepfun-color.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><title>Stepfun</title><path d="M22.012 0h1.032v.927H24v.968h-.956V3.78h-1.032V1.896h-1.878v-.97h1.878V0zM2.6 12.371V1.87h.969v10.502h-.97zm10.423.66h10.95v.918h-6.208v9.579h-4.742V13.03zM5.629 3.333v12.356H0v4.51h10.386V8L20.859 8l-.003-4.668-15.227.001z" fill="url(#stepfun-gradient)" fill-rule="evenodd"/><defs><linearGradient id="stepfun-gradient" x1="1.646" y1="1.916" x2="18.342" y2="22.091" gradientUnits="userSpaceOnUse"><stop stop-color="#01A9FF"/><stop offset="1" stop-color="#0160FF"/></linearGradient></defs></svg>
diff --git a/gui/src/App.tsx b/gui/src/App.tsx
index b7ec8f9db04..9a3c448074c 100644
--- a/gui/src/App.tsx
+++ b/gui/src/App.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useKeyedClientResource } from "./client-resource";
 import Dashboard from "./pages/Dashboard";
 import Providers from "./pages/Providers";
@@ -15,7 +15,7 @@ import ErrorBoundary from "./components/ErrorBoundary";
 import { SidebarGithubRow } from "./components/sidebar-github-row";
 import { IconGrid, IconServer, IconBoxes, IconBot, IconList, IconActivity, IconHardDrive, IconCodex, IconMenu, IconSun, IconMoon, IconMonitor, IconGlobe, IconPower, IconX, IconRefresh} from "./icons";
 import { useI18n, useT, LOCALES, localeDisplayName, type Locale, type TKey } from "./i18n/shared";
-import { Select } from "./ui";
+import { Select, ToastNotice, type NoticeTone } from "./ui";
 import { configureApiTargets, hasApiSession, installApiAuthFetch, installApiSessionFromHtml, logoutApiSession, SESSION_UNAVAILABLE_EVENT } from "./api";
 import { apiBaseForPlane, discoverApiTargets, isConnectedRuntime, standaloneApiTargets, type ApiTargets } from "./api-targets";
 import { ConnectPairingForm } from "./connect-pairing";
@@ -24,6 +24,8 @@ import { readModelsTab, type ModelsTab } from "./pages/models-tab";
 import { useAppRouteState } from "./use-app-route-state";
 import { requestProxyStop } from "./stop-proxy";
 import { useCodexRestart } from "./use-codex-restart";
+import { confirmAction } from "./action-dialogs";
+import { isDesktopShell, isExternalLink } from "./lib/desktop-shell";
 
 type Theme = "light" | "dark" | "system";
 
@@ -116,6 +118,18 @@ export default function App() {
   const [sharedSessionReady, setSharedSessionReady] = useState(() => hasApiSession("shared"));
   const [sharedSessionEpoch, setSharedSessionEpoch] = useState(0);
   const [sessionLoggingOut, setSessionLoggingOut] = useState(false);
+  /*
+   * Results from the two sidebar orbs used to be `alert()`, which the app's webview draws
+   * nowhere, so a refused stop and a completed one looked identical: nothing happened.
+   * The toast is portaled, so reporting from the shell costs the page no layout.
+   */
+  const [actionFeedback, setActionFeedback] = useState<{ tone: NoticeTone; text: string } | null>(null);
+  /** Bumped on every report so a repeated identical message restarts the dismiss timer. */
+  const [feedbackRevision, setFeedbackRevision] = useState(0);
+  const report = useCallback((text: string, tone: NoticeTone) => {
+    setActionFeedback({ tone, text });
+    setFeedbackRevision(revision => revision + 1);
+  }, []);
 
   useEffect(() => {
     const unavailable = (event: Event) => {
@@ -172,12 +186,37 @@ export default function App() {
     };
   }, []);
 
+  useEffect(() => {
+    if (!isDesktopShell()) return;
+    const interceptExternalLinks = (event: MouseEvent) => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+      const anchor = target.closest("a[href]");
+      if (!(anchor instanceof HTMLAnchorElement)) return;
+      const href = anchor.href;
+      if (!isExternalLink(href)) return;
+      event.preventDefault();
+      // Rust denies external HTTP(S) navigation and opens it in the system browser.
+      window.location.assign(href);
+    };
+    document.addEventListener("click", interceptExternalLinks, true);
+    return () => document.removeEventListener("click", interceptExternalLinks, true);
+  }, []);
+
   useEffect(() => {
     const el = document.documentElement;
     if (theme === "system") { el.removeAttribute("data-theme"); localStorage.removeItem(THEME_KEY); }
     else { el.setAttribute("data-theme", theme); localStorage.setItem(THEME_KEY, theme); }
   }, [theme]);
 
+  // Success expires on its own; a failure and a degraded result stay until the user
+  // dismisses them, because those are the two the user has to act on.
+  useEffect(() => {
+    if (actionFeedback?.tone !== "ok") return;
+    const timer = window.setTimeout(() => setActionFeedback(null), 4500);
+    return () => window.clearTimeout(timer);
+  }, [actionFeedback, feedbackRevision]);
+
   const healthPoll = useKeyedClientResource(
     `app-healthz:${machineBase}`,
     [machineBase, targetsSettled],
@@ -230,21 +269,35 @@ export default function App() {
   const [codexRestartEpoch, setCodexRestartEpoch] = useState(0);
   const { restarting: codexRestarting, restart: handleCodexRestart } = useCodexRestart(sharedBase, {
     onSettled: () => setCodexRestartEpoch(epoch => epoch + 1),
+    report,
   });
 
   const handleStop = async () => {
-    if (!confirm(t(targets.connected ? "connection.disconnectConfirm" : "dash.stopConfirm"))) return;
+    const consented = await confirmAction({
+      message: t(targets.connected ? "connection.disconnectConfirm" : "dash.stopConfirm"),
+      confirmLabel: t(targets.connected ? "connection.disconnect" : "dash.stop"),
+      tone: "danger",
+    });
+    if (!consented) return;
     setStopping(true);
     const outcome = await requestProxyStop(machineBase, {
       formatFailure: status => t("dash.stopFailed", { status: String(status) }),
+      formatStillRunning: () => t("dash.stopStillRunning"),
+      formatUnknown: () => t("dash.stopUnknown"),
       mode: targets.connected ? "client" : "standalone",
     });
-    // Refusals and restore failures return normally instead of dropping the connection.
-    // In both cases the proxy did not reach a clean-stop result, so re-enable the control
-    // and surface the server's remediation instead of leaving "stopping…" stuck forever.
-    if (!outcome.accepted) {
+    /*
+     * Only an accepted stop leaves the control pending, because the page is about to go
+     * away with the server. A refusal and an unknown both mean the user is still here and
+     * still looking at a running dashboard, so the control comes back either way.
+     *
+     * They are not reported the same, though. A refusal is the server's own answer and
+     * reads as a failure; an unknown is the absence of an answer, and claiming either
+     * success or failure there is the thing this lane exists to stop.
+     */
+    if (outcome.status !== "accepted") {
       setStopping(false);
-      alert(outcome.message);
+      report(outcome.message, outcome.status === "rejected" ? "err" : "warn");
     }
   };
 
@@ -254,7 +307,7 @@ export default function App() {
     const loggedOut = await logoutApiSession("shared");
     setSessionLoggingOut(false);
     if (loggedOut) setSharedSessionReady(false);
-    else alert(t("connection.sessionLogoutFailed"));
+    else report(t("connection.sessionLogoutFailed"), "err");
   };
 
   /*
@@ -285,6 +338,11 @@ export default function App() {
 
   return (
     <div className="app">
+      {actionFeedback && (
+        <ToastNotice tone={actionFeedback.tone} onDismiss={() => setActionFeedback(null)} dismissLabel={t("common.close")}>
+          {actionFeedback.text}
+        </ToastNotice>
+      )}
       {/* inert while the drawer is open: keeps focus and assistive tech inside the drawer */}
       <header className="mobile-topbar" inert={navOpen}>
         <button ref={menuBtnRef} type="button" className="menu-toggle" onClick={() => setNavOpen(o => !o)}
@@ -445,7 +503,7 @@ export default function App() {
                   authenticationPending={targets.connected && !sharedSessionReady} refreshEpoch={sharedSessionEpoch} />}
                 {page === "startup" && <Startup apiBase={sharedBase} machineApiBase={machineBase} connected={targets.connected} />}
                 {page === "providers" && <Providers apiBase={sharedBase} />}
-                {page === "models" && <Models key={sharedBase} apiBase={sharedBase} restartEpoch={codexRestartEpoch} catalogSyncedAt={targets.catalogSyncedAt} />}
+                {page === "models" && <Models key={sharedBase} apiBase={sharedBase} restartEpoch={codexRestartEpoch} catalogSyncedAt={targets.catalogSyncedAt} reportRestart={report} />}
                 {page === "subagents" && <Subagents key={sharedBase} apiBase={sharedBase} />}
                 {page === "logs" && <Logs apiBase={sharedBase} />}
                 {page === "usage" && <Usage apiBase={sharedBase} connected={targets.connected} apiKeyId={targets.apiKeyId} />}
diff --git a/gui/src/action-dialogs.ts b/gui/src/action-dialogs.ts
new file mode 100644
index 00000000000..d1e53c7c25b
--- /dev/null
+++ b/gui/src/action-dialogs.ts
@@ -0,0 +1,331 @@
+/**
+ * In-page replacements for the three platform dialogs the desktop app cannot draw.
+ *
+ * wry implements exactly three `WKUIDelegate` methods — the file open panel, the media
+ * capture permission request, and window creation for a navigation action — and WKWebView
+ * draws no JavaScript dialog when its UI delegate does not implement the matching panel
+ * method. Inside the app `confirm()` therefore returns false without drawing anything,
+ * `alert()` draws nothing at all, and `prompt()` cannot collect input. Every consent gate
+ * and every result report written against those three was silently declined or silently
+ * swallowed while the same dashboard worked in a browser, which is why the failure read as
+ * "the app is broken" rather than "the dashboard is broken".
+ * See devlog/_plan/260921_app_runtime_ownership/050_webview_dialogs.md.
+ *
+ * These helpers keep the call-site shape the platform dialogs had — ask, await an answer,
+ * act on it — so the surrounding control flow survives the replacement unchanged, above
+ * all the part that matters: a refusal still issues no request. They are built
+ * imperatively rather than as React components because the callers are hooks, inline event
+ * handlers and a shared restart controller rather than one subtree. `admin-token-dialog.ts`
+ * already answers the same problem the same way, and this reuses its dismissal, focus and
+ * validation behaviour along with the modal classes in `styles.css`.
+ */
+import { DICTS, getActiveLocale, type Locale } from "./i18n/shared";
+
+/** Keeps element ids unique when two dialogs are opened in one document. */
+let dialogSequence = 0;
+
+export interface ConfirmActionOptions {
+  /** The question. Blank lines separate paragraphs, the way `confirm()` rendered them. */
+  message: string;
+  /** Label of the accepting button. Defaults to the shared OK label. */
+  confirmLabel?: string;
+  /** `danger` marks an action that destroys, interrupts or disconnects something. */
+  tone?: "default" | "danger";
+  /**
+   * Withdraws the question. A consent names a subject, and a dialog that outlives its
+   * subject — the surface unmounted, the backend target changed — is no longer asking about
+   * the thing the user would be approving. Aborting resolves it as a refusal.
+   */
+  signal?: AbortSignal;
+  /** Overrides the active locale; these dialogs open outside the React provider. */
+  locale?: Locale;
+}
+
+export interface RequestTextValueOptions {
+  /** Field label — the string the platform `prompt()` showed above its input. */
+  message: string;
+  /** Pre-filled value, matching `prompt()`'s second argument. */
+  initialValue?: string;
+  /** Label of the accepting button. Defaults to the shared Save label. */
+  confirmLabel?: string;
+  /** Longest accepted value, when the route states one. */
+  maxLength?: number;
+  /**
+   * Mirrors a server contract for immediate feedback. Returns the message to show, or
+   * null to accept. A rejected value keeps the dialog open and issues no request.
+   */
+  validate?: (value: string) => string | null;
+  /** Withdraws the question; see `ConfirmActionOptions.signal`. */
+  signal?: AbortSignal;
+  locale?: Locale;
+}
+
+/** Renders a multi-paragraph consent message as separate paragraphs. */
+function paragraphsOf(message: string): string[] {
+  const paragraphs = message.split(/\n{2,}/).map(part => part.trim()).filter(part => part.length > 0);
+  return paragraphs.length > 0 ? paragraphs : [message];
+}
+
+interface ModalShell<T> {
+  form: HTMLFormElement;
+  bodyId: string;
+  /** Resolves the dialog exactly once, restoring focus to whatever opened it. */
+  finish: (value: T) => void;
+}
+
+/**
+ * Opens a modal `<dialog>` that resolves exactly once.
+ *
+ * `cancelValue` answers every dismissal the user did not spell out — Escape, the backdrop,
+ * the Cancel button — because a surface that cannot say how it was closed is precisely how
+ * the undrawn `confirm()` became indistinguishable from a deliberate refusal.
+ */
+function openModal<T>(
+  locale: Locale,
+  cancelValue: T,
+  resolve: (value: T) => void,
+  signal?: AbortSignal,
+): ModalShell<T> {
+  const messages = DICTS[locale];
+  const id = `opencodex-action-dialog-${++dialogSequence}`;
+  /*
+   * Duck-typed rather than `instanceof HTMLElement`. These helpers are reached from a dozen
+   * components, and a constructor identity check binds every one of their callers to a
+   * realm that happens to expose the global — which is not true of a document handed in
+   * from elsewhere, and is not true of most of this package's DOM tests.
+   */
+  const active = document.activeElement as { focus?: unknown; isConnected?: boolean } | null;
+  const previouslyFocused = typeof active?.focus === "function" ? (active as HTMLElement) : null;
+  let settled = false;
+
+  const dialog = document.createElement("dialog");
+  dialog.id = id;
+  dialog.className = "modal-overlay";
+  dialog.setAttribute("aria-labelledby", `${id}-body`);
+
+  const backdrop = document.createElement("button");
+  backdrop.type = "button";
+  backdrop.className = "modal-backdrop-dismiss";
+  backdrop.tabIndex = -1;
+  backdrop.setAttribute("aria-label", messages["common.close"]);
+
+  const form = document.createElement("form");
+  form.className = "modal-card";
+
+  const finish = (value: T): void => {
+    if (settled) return;
+    settled = true;
+    window.removeEventListener("hashchange", dismissOnNavigation);
+    window.removeEventListener("popstate", dismissOnNavigation);
+    document.removeEventListener("keydown", dismissOnEscape);
+    signal?.removeEventListener("abort", dismissOnNavigation);
+    // The caller is answered whatever the teardown does. A dialog left connected is a
+    // cosmetic fault; a promise that never settles hangs the handler that awaited it.
+    try {
+      if (dialog.open && typeof dialog.close === "function") dialog.close();
+      dialog.remove();
+      // Only when the trigger is still in the document: a dismissal that removed the row
+      // the button lived on would otherwise throw on the way out.
+      if (previouslyFocused?.isConnected) previouslyFocused.focus();
+    } finally {
+      resolve(value);
+    }
+  };
+
+  /*
+   * A dialog mounted on <body> outlives the React subtree that opened it. Navigating with
+   * Back/Forward while one is open would leave it on screen, and accepting it afterwards
+   * would resume a closed-over handler against a page the user has already left — removing
+   * an account or revoking a device from a surface they cannot see. Navigation is therefore
+   * a refusal, using the same two events the shell already treats as leaving a page.
+   */
+  function dismissOnNavigation(): void {
+    finish(cancelValue);
+  }
+
+  /*
+   * Escape at the document, not just at the dialog. With `showModal` the dialog reports its
+   * own "cancel" event and this never fires; without it the element is merely open, so a
+   * dialog-level listener would miss Escape as soon as focus sat anywhere else.
+   */
+  function dismissOnEscape(event: KeyboardEvent): void {
+    if (event.key === "Escape") finish(cancelValue);
+  }
+
+  backdrop.addEventListener("click", () => finish(cancelValue));
+  // A native <dialog> fires "cancel" on Escape and would close without an answer.
+  dialog.addEventListener("cancel", (event) => {
+    event.preventDefault();
+    finish(cancelValue);
+  });
+  window.addEventListener("hashchange", dismissOnNavigation);
+  window.addEventListener("popstate", dismissOnNavigation);
+  signal?.addEventListener("abort", dismissOnNavigation);
+
+  dialog.append(backdrop, form);
+  document.body.append(dialog);
+  if (typeof dialog.showModal === "function") {
+    dialog.showModal();
+  } else {
+    /*
+     * This path exists for DOM implementations without `showModal` — this package's test
+     * DOM is one. It is not a modality boundary: setting `open` neither makes the rest of
+     * the document inert nor traps focus, and pretending otherwise would be worse than
+     * saying so. Every browser surface the dashboard ships to implements `showModal`, and
+     * takes the branch above. Escape is still answered, at the document.
+     */
+    dialog.setAttribute("open", "");
+    document.addEventListener("keydown", dismissOnEscape);
+  }
+
+  return { form, bodyId: `${id}-body`, finish };
+}
+
+/** Appends the message paragraphs and returns the element that names the dialog. */
+function appendMessage(form: HTMLFormElement, bodyId: string, message: string, tag = "div"): HTMLElement {
+  const body = document.createElement(tag);
+  body.id = bodyId;
+  for (const paragraph of paragraphsOf(message)) {
+    const element = document.createElement("p");
+    element.className = "modal-desc";
+    element.textContent = paragraph;
+    body.append(element);
+  }
+  form.append(body);
+  return body;
+}
+
+/**
+ * Asks for consent and resolves true only when the user accepted.
+ *
+ * Every other outcome — Cancel, Escape, the backdrop — resolves false, so a caller written
+ * as `if (!await confirmAction(...)) return;` keeps the refusal path it already had.
+ */
+export function confirmAction(options: ConfirmActionOptions): Promise<boolean> {
+  const locale = options.locale ?? getActiveLocale();
+  const messages = DICTS[locale];
+  const danger = options.tone === "danger";
+
+  return new Promise<boolean>((resolve) => {
+    // Already withdrawn: answer without ever drawing the question.
+    if (options.signal?.aborted) { resolve(false); return; }
+    const { form, bodyId, finish } = openModal<boolean>(locale, false, resolve, options.signal);
+    appendMessage(form, bodyId, options.message);
+
+    const actions = document.createElement("div");
+    actions.className = "modal-actions";
+
+    const cancel = document.createElement("button");
+    cancel.type = "button";
+    cancel.className = "btn btn-ghost";
+    cancel.textContent = messages["common.cancel"];
+    cancel.addEventListener("click", () => finish(false));
+
+    const accept = document.createElement("button");
+    accept.type = "submit";
+    accept.className = danger ? "btn btn-danger" : "btn btn-primary";
+    accept.textContent = options.confirmLabel ?? messages["common.ok"];
+
+    form.addEventListener("submit", (event) => {
+      event.preventDefault();
+      finish(true);
+    });
+
+    actions.append(cancel, accept);
+    form.append(actions);
+    // A destructive action does not get to be the thing Enter reaches first.
+    queueMicrotask(() => (danger ? cancel : accept).focus());
+  });
+}
+
+/**
+ * Collects one line of text and resolves it, or null when the user declined.
+ *
+ * Null is the same answer `prompt()` returned on cancel, so callers keep their
+ * `if (entered === null) return;` guard and still issue no request on a refusal.
+ */
+export function requestTextValue(options: RequestTextValueOptions): Promise<string | null> {
+  const locale = options.locale ?? getActiveLocale();
+  const messages = DICTS[locale];
+
+  return new Promise<string | null>((resolve) => {
+    if (options.signal?.aborted) { resolve(null); return; }
+    const { form, bodyId, finish } = openModal<string | null>(locale, null, resolve, options.signal);
+    const input = document.createElement("input");
+    const inputId = `${bodyId}-input`;
+    // A real <label for> rather than aria-describedby: the message IS the field's name, and
+    // the platform prompt() showed it the same way.
+    const label = appendMessage(form, bodyId, options.message, "label");
+    label.className = "field-label";
+    label.setAttribute("for", inputId);
+
+    input.id = inputId;
+    input.className = "input";
+    input.type = "text";
+    input.value = options.initialValue ?? "";
+    input.spellcheck = false;
+    input.autocapitalize = "none";
+    if (options.maxLength !== undefined) input.maxLength = options.maxLength;
+
+    // Mounted up front so role="alert" has a stable target, and kept empty while hidden so
+    // the two halves of "there is no error" cannot drift apart — same rule as the
+    // admin-token dialog's notice.
+    const validationError = document.createElement("div");
+    const errorId = `${bodyId}-error`;
+    validationError.id = errorId;
+    validationError.className = "notice notice-err";
+    validationError.setAttribute("role", "alert");
+    validationError.hidden = true;
+
+    const setValidationError = (text: string | null): void => {
+      validationError.textContent = text ?? "";
+      validationError.hidden = text === null;
+      if (text === null) {
+        input.removeAttribute("aria-invalid");
+        input.removeAttribute("aria-describedby");
+      } else {
+        input.setAttribute("aria-invalid", "true");
+        input.setAttribute("aria-describedby", errorId);
+      }
+    };
+
+    const actions = document.createElement("div");
+    actions.className = "modal-actions";
+
+    const cancel = document.createElement("button");
+    cancel.type = "button";
+    cancel.className = "btn btn-ghost";
+    cancel.textContent = messages["common.cancel"];
+    cancel.addEventListener("click", () => finish(null));
+
+    const accept = document.createElement("button");
+    accept.type = "submit";
+    accept.className = "btn btn-primary";
+    accept.textContent = options.confirmLabel ?? messages["common.save"];
+
+    form.addEventListener("submit", (event) => {
+      event.preventDefault();
+      const entered = input.value;
+      const rejection = options.validate?.(entered) ?? null;
+      setValidationError(rejection);
+      if (rejection !== null) {
+        // The dialog stays open and nothing is sent: a rejected value is not an answer.
+        accept.disabled = true;
+        input.focus();
+        return;
+      }
+      finish(entered);
+    });
+
+    // Re-enable on the next edit rather than on a timer, so the button state always
+    // describes the value currently in the field.
+    input.addEventListener("input", () => {
+      if (accept.disabled) accept.disabled = false;
+      if (!validationError.hidden) setValidationError(null);
+    });
+
+    actions.append(cancel, accept);
+    form.append(input, validationError, actions);
+    queueMicrotask(() => input.focus());
+  });
+}
diff --git a/gui/src/codex-restart.ts b/gui/src/codex-restart.ts
index cda041e7e84..fd46a30bfcd 100644
--- a/gui/src/codex-restart.ts
+++ b/gui/src/codex-restart.ts
@@ -11,12 +11,15 @@ export type { CodexRestartCode, CodexRestartResponse };
 // rewrites the catalog first, so this is slower than an ordinary management call.
 const DEFAULT_TIMEOUT_MS = 30_000;
 
-export interface CodexRestartOutcome {
-  ok: boolean;
-  result?: CodexRestartResponse;
-  /** Localized by the caller through the format* options. */
-  message?: string;
-}
+/**
+ * Success carries the response, failure carries the reason, and neither carries both.
+ * Stated as a union so the reporting surface never has to invent a message for a failure
+ * it was handed without one — which is the shape `alert()` let through unnoticed.
+ */
+export type CodexRestartOutcome =
+  | { ok: true; result: CodexRestartResponse; message?: undefined }
+  /** `message` is localized by the caller through the format* options. */
+  | { ok: false; result?: undefined; message: string };
 
 export interface CodexRestartOptions {
   fetchFn?: typeof fetch;
diff --git a/gui/src/components/CodexAccountPool.tsx b/gui/src/components/CodexAccountPool.tsx
index e9be8f96970..2b30f20194f 100644
--- a/gui/src/components/CodexAccountPool.tsx
+++ b/gui/src/components/CodexAccountPool.tsx
@@ -2,6 +2,8 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import { useT } from "../i18n/shared";
 import { IconPlus } from "../icons";
 import { EmptyState, type NoticeTone } from "../ui";
+import { confirmAction, requestTextValue } from "../action-dialogs";
+import { credentialAliasRejection, CREDENTIAL_ALIAS_MAX_LENGTH } from "../credential-alias";
 import AddCodexAccountModal from "./AddCodexAccountModal";
 import { useCodexAccountPool, type CodexAccountPoolController } from "../hooks/useCodexAccountPool";
 import { useMainDeviceReauth } from "./use-main-device-reauth";
@@ -72,7 +74,7 @@ export default function CodexAccountPool({ apiBase, accountModeState = null, ban
   // but stays inert (no load, no polling) whenever a shared controller was injected.
   const ownController = useCodexAccountPool(apiBase, !injectedController);
   const controller = injectedController ?? ownController;
-  const { accounts, activeId, loadState, switchingId, pauseUpdatingId, priorityUpdatingId, pausingExhausted, activePinnedId, load } = controller;
+  const { accounts, activeId, loadState, refreshFailed, switchingId, pauseUpdatingId, priorityUpdatingId, pausingExhausted, activePinnedId, load } = controller;
   // #3898: the native-main device reauth drives the dedicated namespace; a
   // completed flow refreshes the account list so the card leaves reauth state.
   const mainReauth = useMainDeviceReauth(apiBase, () => { void load(); });
@@ -232,7 +234,12 @@ export default function CodexAccountPool({ apiBase, accountModeState = null, ban
   };
 
   const editAlias = async (account: CodexAccountEntry) => {
-    const entered = window.prompt(t("prov.aliasPrompt"), account.alias ?? "");
+    const entered = await requestTextValue({
+      message: t("prov.aliasPrompt"),
+      initialValue: account.alias ?? "",
+      maxLength: CREDENTIAL_ALIAS_MAX_LENGTH,
+      validate: value => credentialAliasRejection(value, t),
+    });
     if (entered === null) return;
     const result = await controller.saveAlias(account.id, entered);
     showActionFeedback(t(result.ok ? "prov.aliasSaved" : "prov.aliasSaveFailed"), result.ok ? "ok" : "err");
@@ -268,7 +275,7 @@ export default function CodexAccountPool({ apiBase, accountModeState = null, ban
 
   const remove = async (id: string) => {
     const label = accounts.find(account => account.id === id)?.email ?? t("pws.accountOrdinal", { count: "1" });
-    if (!window.confirm(t("codexAuth.removeConfirm", { id: label }))) return;
+    if (!(await confirmAction({ message: t("codexAuth.removeConfirm", { id: label }), confirmLabel: t("common.remove"), tone: "danger" }))) return;
     const result = await controller.removeAccount(id);
     if (!result.ok) {
       showActionFeedback(t("codexAuth.removeFailed"), "err");
@@ -476,6 +483,7 @@ export default function CodexAccountPool({ apiBase, accountModeState = null, ban
       <CodexAccountPoolLoadStates
         t={t}
         loadState={loadState}
+        refreshFailed={refreshFailed}
         accountsCount={accounts.length}
         onRetry={() => { void load(); }}
       />
diff --git a/gui/src/components/CompactionRoutingPanel.tsx b/gui/src/components/CompactionRoutingPanel.tsx
index e2285891447..6875b7ab3fa 100644
--- a/gui/src/components/CompactionRoutingPanel.tsx
+++ b/gui/src/components/CompactionRoutingPanel.tsx
@@ -4,6 +4,7 @@ import { IconAlert } from "../icons";
 import { Select } from "../ui";
 import { createBoundedFetch } from "../bounded-fetch";
 import { requireJson, type ModelInfo } from "../pages/dashboard-shared";
+import { comboModelId, parseComboList } from "../combo-workspace-data";
 import { formatNamespacedModelId } from "../provider-icons";
 
 type Setting = { model: string; reasoningEffort?: string; triggers?: string[] } | null;
@@ -32,17 +33,22 @@ function choiceToTriggers(choice: string): string[] | undefined {
   return undefined;
 }
 
-function readComboProviders(payload: unknown): Record<string, string[]> {
-  const combos = (payload as { combos?: unknown })?.combos;
-  if (!Array.isArray(combos)) return {};
-  const result: Record<string, string[]> = {};
-  for (const combo of combos) {
-    if (!combo || typeof combo !== "object" || typeof (combo as { id?: unknown }).id !== "string") continue;
-    const targets = (combo as { targets?: unknown }).targets;
-    const providers = Array.isArray(targets)
-      ? targets.map(target => (target as { provider?: unknown })?.provider).filter((value): value is string => typeof value === "string")
-      : [];
-    result[(combo as { id: string }).id] = [...new Set(providers)];
+/**
+ * Target providers keyed by the selector a client actually requests.
+ *
+ * Keyed by the combo's public model id rather than its raw id, because a combo reached through
+ * an alias carries no `combo/` prefix: the panel used to test for that prefix, fail to
+ * recognize an aliased combo, and describe it as an ordinary provider while naming none of its
+ * targets (#5216). `parseComboList` is the same reader the combo workspace uses, so the
+ * selector rule lives in one place instead of being spelled out again here.
+ */
+function readComboProviders(payload: unknown): Map<string, string[]> {
+  // A Map, not an object: the key is a combo's public model id, which is caller-configured and
+  // free-form. Writing that into an object literal is a prototype-pollution sink, and reading it
+  // back would return an inherited member for an alias of `constructor` or `toString`.
+  const result = new Map<string, string[]>();
+  for (const combo of parseComboList(payload)) {
+    result.set(combo.model, [...new Set(combo.targets.flatMap(target => target.provider ? [target.provider] : []))]);
   }
   return result;
 }
@@ -79,7 +85,7 @@ function CompactionRoutingControls({ apiBase, models }: { apiBase: string; model
   const [busy, setBusy] = useState(false);
   const [loadError, setLoadError] = useState(false);
   const [feedback, setFeedback] = useState<"saved" | "failed" | null>(null);
-  const [comboProviders, setComboProviders] = useState<Record<string, string[]>>({});
+  const [comboProviders, setComboProviders] = useState<Map<string, string[]>>(() => new Map());
   const active = useRef(false);
   const pending = useRef<ReturnType<typeof createBoundedFetch> | null>(null);
 
@@ -99,7 +105,8 @@ function CompactionRoutingControls({ apiBase, models }: { apiBase: string; model
       const response = await fetch(`${apiBase}/api/settings`, { signal: request.signal });
       const value = readSetting(await requireJson(response));
       if (active.current && pending.current === request) accept(value);
-      const combos = await fetch(`${apiBase}/api/combos`, { signal: request.signal }).then(requireJson).then(readComboProviders).catch(() => ({}));
+      const combos = await fetch(`${apiBase}/api/combos`, { signal: request.signal })
+        .then(requireJson).then(readComboProviders).catch(() => new Map<string, string[]>());
       if (active.current && pending.current === request) setComboProviders(combos);
     } catch {
       if (active.current && pending.current === request) setLoadError(true);
@@ -163,10 +170,16 @@ function CompactionRoutingControls({ apiBase, models }: { apiBase: string; model
   const dirty = model !== (saved?.model ?? "")
     || effort !== (saved?.reasoningEffort ?? "")
     || triggers !== triggersToChoice(saved?.triggers);
+  // Ask what the selection resolves to instead of reading its name. An aliased combo answers
+  // here exactly like a prefixed one (#5216).
+  const comboTargets = comboProviders.get(model);
+  // The canonical prefix stays a combo signal of its own. It is the only one left when
+  // /api/combos has not answered yet or failed, and losing it there would describe a combo as
+  // an ordinary provider named "combo" — worse than the alias gap this fixes.
+  const isCombo = comboTargets !== undefined || model.startsWith(comboModelId(""));
   const namespace = model.slice(0, Math.max(model.indexOf("/"), 0));
-  const combo = namespace === "combo" ? model.slice(namespace.length + 1) : "";
-  const provider = namespace && !combo ? namespace : model;
-  const providers = comboProviders[combo]?.join(", ") || t("compactionRouting.comboProvidersUnknown");
+  const provider = isCombo ? "" : (namespace || model);
+  const providers = comboTargets?.join(", ") || t("compactionRouting.comboProvidersUnknown");
   const routesAutomatic = triggers !== "manual";
 
   return (
@@ -195,10 +208,10 @@ function CompactionRoutingControls({ apiBase, models }: { apiBase: string; model
           </button>
         </div>
       </div>
-      {provider && <div className="notice-warn" role="note" style={{ marginTop: 12 }}><IconAlert width={14} /> {combo
+      {model && <div className="notice-warn" role="note" style={{ marginTop: 12 }}><IconAlert width={14} /> {isCombo
         ? t("compactionRouting.comboWarning", { combo: model, providers })
         : t("compactionRouting.providerWarning", { provider })}</div>}
-      {provider && routesAutomatic && <div className="notice-warn" role="note" style={{ marginTop: 12 }}><IconAlert width={14} /> {t("compactionRouting.autoNotice")}</div>}
+      {model && routesAutomatic && <div className="notice-warn" role="note" style={{ marginTop: 12 }}><IconAlert width={14} /> {t("compactionRouting.autoNotice")}</div>}
       {loadError && <div className="notice notice-err" role="alert" style={{ marginTop: 12, marginBottom: 0 }}>{t("compactionRouting.loadFailed")} <button type="button" className="btn btn-ghost btn-sm" onClick={() => { void load(); }}>{t("common.retry")}</button></div>}
       {feedback === "failed" && <div className="notice notice-err" role="alert" style={{ marginTop: 12, marginBottom: 0 }}>{t("compactionRouting.saveFailed")}</div>}
       {feedback === "saved" && <div className="muted setting-hint" role="status">{t("compactionRouting.saved")}</div>}
diff --git a/gui/src/components/MemoryObservabilityCard.tsx b/gui/src/components/MemoryObservabilityCard.tsx
index ebf12a4ad70..8bea5857ca1 100644
--- a/gui/src/components/MemoryObservabilityCard.tsx
+++ b/gui/src/components/MemoryObservabilityCard.tsx
@@ -3,6 +3,7 @@ import { formatUptime } from "../formatUptime";
 import { IconActivity } from "../icons";
 import { useI18n, type Locale, type TFn } from "../i18n/shared";
 import { createBoundedFetch, type BoundedFetch } from "../bounded-fetch";
+import { confirmAction } from "../action-dialogs";
 import { startVisibilityPoll } from "../visibility-poll";
 
 /**
@@ -355,27 +356,26 @@ export default function MemoryObservabilityCard({ apiBase }: { apiBase: string }
     };
   }, [apiBase, restartPhase, restartFromPid, t]);
 
-  const confirmRestart = () => {
+  const confirmRestart = async () => {
     const count = data?.activeTurnCount ?? 0;
     const lines = [
       t("dash.mem.restartConfirm", { count, seconds: DRAIN_TIMEOUT_S }),
     ];
     if (noSupervisor) lines.push(t("dash.mem.restartNoSupervisor"));
-    if (!window.confirm(lines.join("\n\n"))) return;
-    void (async () => {
-      setRestartError(null);
-      setRestartFromPid(typeof data?.pid === "number" ? data.pid : null);
-      setRestartPhase("draining");
-      try {
-        const res = await fetch(`${apiBase}/api/system/restart`, { method: "POST" });
-        if (!res.ok) throw new Error("restart_failed");
-        // Proxy will drain then exit; memory poll will trip reconnecting or pid change.
-      } catch {
-        setRestartPhase("error");
-        setRestartFromPid(null);
-        setRestartError(t("dash.mem.restartFailed"));
-      }
-    })();
+    // Blank lines still separate the paragraphs; the dialog renders each as its own <p>.
+    if (!(await confirmAction({ message: lines.join("\n\n"), tone: "danger" }))) return;
+    setRestartError(null);
+    setRestartFromPid(typeof data?.pid === "number" ? data.pid : null);
+    setRestartPhase("draining");
+    try {
+      const res = await fetch(`${apiBase}/api/system/restart`, { method: "POST" });
+      if (!res.ok) throw new Error("restart_failed");
+      // Proxy will drain then exit; memory poll will trip reconnecting or pid change.
+    } catch {
+      setRestartPhase("error");
+      setRestartFromPid(null);
+      setRestartError(t("dash.mem.restartFailed"));
+    }
   };
 
   if (unavailable && !data && restartPhase === "idle") {
@@ -432,7 +432,7 @@ export default function MemoryObservabilityCard({ apiBase }: { apiBase: string }
               type="button"
               className="btn btn-ghost btn-sm"
               disabled={busy}
-              onClick={confirmRestart}
+              onClick={() => { void confirmRestart(); }}
             >
               {t("dash.mem.restart")}
             </button>
diff --git a/gui/src/components/codex-account-pool-main-card.tsx b/gui/src/components/codex-account-pool-main-card.tsx
index 25af1eb49f9..051424184f5 100644
--- a/gui/src/components/codex-account-pool-main-card.tsx
+++ b/gui/src/components/codex-account-pool-main-card.tsx
@@ -3,7 +3,7 @@ import { IconLock, IconPause, IconPlay, IconPlus, IconRefresh, IconTicket } from
 import AccountPriorityControl, { AccountPriorityBadge } from "./AccountPriorityControl";
 import QuotaBars from "./QuotaBars";
 import { CodexPauseToggleLabel, CodexTicketBadge } from "./codex-account-pool-helpers";
-import type { CodexAccountEntry } from "./codex-account-pool-types";
+import type { CodexAccountEntry, CodexAccountLoadState } from "./codex-account-pool-types";
 import type { CodexAccountModeState } from "../codex-multi-state";
 import type { TFn } from "../i18n/shared";
 import type { MainDeviceReauthState } from "./use-main-device-reauth";
@@ -359,11 +359,13 @@ export function CodexAccountPoolActions(props: {
 export function CodexAccountPoolLoadStates({
   t,
   loadState,
+  refreshFailed,
   accountsCount,
   onRetry,
 }: {
   t: TFn;
-  loadState: "loading" | "ready" | "error";
+  loadState: CodexAccountLoadState;
+  refreshFailed: boolean;
   accountsCount: number;
   onRetry: () => void;
 }): ReactNode {
@@ -419,5 +421,16 @@ export function CodexAccountPoolLoadStates({
       </div>
     );
   }
+  // Rows survived a failed refresh, so they are still worth showing — but they are the ones from
+  // before it, and an account added since is simply not among them. A status rather than an alert:
+  // nothing on screen is wrong, it is just older than it looks.
+  if (refreshFailed && accountsCount > 0) {
+    return (
+      <div className="pwi-auth-state pwi-auth-state--stale" role="status">
+        <span>{t("codexAuth.accountsRefreshFailed")}</span>
+        <button type="button" className="btn btn-ghost btn-sm" onClick={onRetry}>{t("pws.retryAccounts")}</button>
+      </div>
+    );
+  }
   return null;
 }
diff --git a/gui/src/components/codex-account-pool-types.ts b/gui/src/components/codex-account-pool-types.ts
index 679350fa23f..0e16acca880 100644
--- a/gui/src/components/codex-account-pool-types.ts
+++ b/gui/src/components/codex-account-pool-types.ts
@@ -1 +1 @@
-export type { CodexAccountEntry } from "../hooks/useCodexAccountPool";
+export type { CodexAccountEntry, CodexAccountLoadState } from "../hooks/useCodexAccountPool";
diff --git a/gui/src/components/provider-workspace/ProviderModels.tsx b/gui/src/components/provider-workspace/ProviderModels.tsx
index 944e6a0cb5c..e8a10189520 100644
--- a/gui/src/components/provider-workspace/ProviderModels.tsx
+++ b/gui/src/components/provider-workspace/ProviderModels.tsx
@@ -2,6 +2,7 @@
 import { useEffect, useRef, useState } from "react";
 import { useT } from "../../i18n/shared";
 import { Switch } from "../../ui";
+import { confirmAction } from "../../action-dialogs";
 import type { WorkspaceItem } from "../../provider-workspace/catalog";
 import { filterFreeModelRows, freeOnlyInForce, modelPricingKnown, type ModelRow } from "../../pages/models-shared";
 import { putModelVisibility } from "../../model-visibility";
@@ -190,8 +191,21 @@ function ProviderModelInventory({ item, apiBase, availableModels, selectedModels
   const removeModel = async (row: ModelRow, button: HTMLButtonElement) => {
     const action = actionFor(row);
     if (actionsBlocked || flight.current || !action) return;
-    if (!window.confirm(t(action === "delete" ? "models.customDeleteConfirm" : "models.hideConfirm", { name: row.namespaced }))) return;
+    /*
+     * The single flight is claimed BEFORE consent is awaited. The gate used to be the
+     * synchronous `window.confirm()`, which nothing could interleave with; an in-page dialog
+     * yields, so without this a second row's button could open its own dialog while this one
+     * is still open and two removals would run against one revision. A browser's modal
+     * dialog makes the page inert, but that is the platform's courtesy, not this
+     * component's invariant.
+     */
     flight.current = true;
+    const consented = await confirmAction({
+      message: t(action === "delete" ? "models.customDeleteConfirm" : "models.hideConfirm", { name: row.namespaced }),
+      confirmLabel: t(action === "delete" ? "common.delete" : "common.ok"),
+      tone: "danger",
+    });
+    if (!consented) { flight.current = false; return; }
     setRequestPending(true);
     setMutation(null);
     focusIntent.current = { button, retained: document.activeElement === button };
diff --git a/gui/src/components/provider-workspace/ProviderSettings.tsx b/gui/src/components/provider-workspace/ProviderSettings.tsx
index 847fe7e7122..ebfa5a20e02 100644
--- a/gui/src/components/provider-workspace/ProviderSettings.tsx
+++ b/gui/src/components/provider-workspace/ProviderSettings.tsx
@@ -10,6 +10,7 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { baseUrlForChoice, matchChoiceId, resolvedBaseUrlForChoice } from "../../base-url-choice";
 import { readJsonIfOk } from "../../fetch-json";
+import { confirmAction } from "../../action-dialogs";
 import { createBoundedFetch } from "../../bounded-fetch";
 import { startVisibilityPoll } from "../../visibility-poll";
 import { useT } from "../../i18n/shared";
@@ -295,6 +296,23 @@ export default function ProviderSettings({
     }
   };
 
+  /**
+   * Asks before switching, because flipping modes rebinds running threads and changes quota
+   * accounting. Written as a named async function rather than a promise chain inside the
+   * handler: a floating `.then` in a JSX handler has no rejection path and is what
+   * `no-floating-then-in-jsx-handler` exists to catch.
+   */
+  const requestAccountMode = async (next: "pool" | "direct", select: HTMLSelectElement) => {
+    if (await confirmAction({ message: t("pws.accountModeConfirm") })) {
+      await applyAccountMode(next);
+      return;
+    }
+    // Keep the visible choice aligned with the applied mode. React re-renders this
+    // controlled <select> only when `accountMode` changes, and a refusal leaves it
+    // unchanged, so the declined option would otherwise stay shown.
+    select.value = accountMode;
+  };
+
   const discard = () => {
     setAdapter(item.adapter); setBaseUrl(item.baseUrl);
     setDefaultModel(item.defaultModel ?? ""); setAuthMode(initialAuth);
@@ -415,14 +433,8 @@ export default function ProviderSettings({
             onChange={e => {
               const next = e.target.value as "pool" | "direct";
               if (next === accountMode) return;
-              // Flipping modes rebinds running threads and changes quota accounting,
-              // so the PATCH only fires after an explicit confirmation.
-              if (!window.confirm(t("pws.accountModeConfirm"))) {
-                // Keep the visible choice aligned with the applied mode.
-                e.target.value = accountMode;
-                return;
-              }
-              void applyAccountMode(next);
+              // currentTarget is read here: it is null once the handler resumes after an await.
+              void requestAccountMode(next, e.currentTarget);
             }}
           >
             <option value="pool">{t("codexAuth.accountModePool")}</option>
diff --git a/gui/src/credential-alias.ts b/gui/src/credential-alias.ts
new file mode 100644
index 00000000000..c107ec41014
--- /dev/null
+++ b/gui/src/credential-alias.ts
@@ -0,0 +1,35 @@
+import type { TFn } from "./i18n/shared";
+
+/**
+ * Mirrors the alias contract both credential routes enforce — src/codex/auth-api/routes.ts
+ * and src/server/management/oauth-account-routes.ts each trim the submitted value and then
+ * reject it when it exceeds 80 characters or carries a control character.
+ *
+ * The platform `prompt()` could not check anything, so an over-long or pasted control
+ * character reached the route and came back as an opaque 400 the user had to interpret.
+ * Checking the same rule in the dialog turns that into a message beside the field, and the
+ * rule is stated once here so the two cannot drift apart silently.
+ */
+export const CREDENTIAL_ALIAS_MAX_LENGTH = 80;
+
+/**
+ * Written as a code-point scan rather than a character-class regex, matching
+ * `containsDisplayNameControlCharacter` in pages/models-shared.ts. A literal control range
+ * in a regex is what `no-control-regex` exists to catch, and the escape form would only
+ * hide the same characters from the reader.
+ */
+function hasControlCharacter(value: string): boolean {
+  return [...value].some((character) => {
+    const codePoint = character.codePointAt(0)!;
+    return codePoint <= 0x1f || codePoint === 0x7f;
+  });
+}
+
+/** Returns the message to show, or null when the route would accept the value. */
+export function credentialAliasRejection(value: string, t: TFn): string | null {
+  const alias = value.trim();
+  if (alias.length > CREDENTIAL_ALIAS_MAX_LENGTH || hasControlCharacter(alias)) {
+    return t("prov.aliasInvalid");
+  }
+  return null;
+}
diff --git a/gui/src/hooks/useCodexAccountPool.ts b/gui/src/hooks/useCodexAccountPool.ts
index cb5fce92968..fe4cdaa155b 100644
--- a/gui/src/hooks/useCodexAccountPool.ts
+++ b/gui/src/hooks/useCodexAccountPool.ts
@@ -97,6 +97,11 @@ export interface CodexAccountPoolController {
    * `ready` during a refresh so rows survive; this is what makes that wait visible.
    */
   refreshing: boolean;
+  /**
+   * The most recent account read failed. The rows it could not replace are still on screen, so
+   * this is the only thing that tells a surface they are no longer known to be current.
+   */
+  refreshFailed: boolean;
   /** True until the first load attempt settles, whether it succeeds or fails. */
   initialLoading: boolean;
   switchingId: string | null;
@@ -160,6 +165,13 @@ export function useCodexAccountPool(apiBase: string, enabled = true): CodexAccou
   );
   const [activeId, setActiveId] = useState<string | null>(() => seed?.activeId ?? null);
   const [loadState, setLoadState] = useState<CodexAccountLoadState>(() => (seed != null ? "ready" : "loading"));
+  // Deliberately beside `loadState` rather than inside it. `loadState` answers what the surface
+  // can draw, and a warm refresh failure keeps the rows drawable — folding the failure in would
+  // mean either flashing the cold skeleton over good data or, as before, saying nothing at all.
+  // Saying nothing is the defect: the rows on screen are the ones from before the refresh, so an
+  // account the user has just added is simply absent while the older ones look current (#5261).
+  // `refreshing` already set the precedent that a fact about the read lives next to loadState.
+  const [refreshFailed, setRefreshFailed] = useState(false);
   const [switchingId, setSwitchingId] = useState<string | null>(null);
   const [pauseUpdatingId, setPauseUpdatingId] = useState<string | null>(null);
   const [priorityUpdatingId, setPriorityUpdatingId] = useState<string | null>(null);
@@ -277,6 +289,10 @@ export function useCodexAccountPool(apiBase: string, enabled = true): CodexAccou
             hasLoadedRef.current = true;
             // Progressive: paint account/quota boxes as soon as /accounts returns.
             setLoadState("ready");
+            // Cleared here rather than at the settle below, because the rows it qualifies are
+            // painted here. Waiting for /active to finish would leave the just-replaced rows
+            // labelled as pre-refresh ones for as long as that read's budget allows.
+            setRefreshFailed(false);
           }
           return true;
         } catch {
@@ -329,9 +345,11 @@ export function useCodexAccountPool(apiBase: string, enabled = true): CodexAccou
         });
         return activeOk;
       }
-      // Cold failure only: after a successful load (including empty), keep rows and stay ready
-      // so a soft poll miss does not flash the skeleton / wipe the pool.
+      // A cold failure has nothing to show, so it replaces the surface. A warm one keeps its rows
+      // — flashing the skeleton on a soft poll miss is its own defect — and says so instead of
+      // continuing to present them as current.
       if (!hasLoadedRef.current) setLoadState("error");
+      setRefreshFailed(true);
       return false;
     } finally {
       bounded.clear();
@@ -623,6 +641,7 @@ export function useCodexAccountPool(apiBase: string, enabled = true): CodexAccou
     activeId,
     loadState,
     refreshing: inflightCount > 0,
+    refreshFailed,
     initialLoading: !firstAttemptSettled,
     switchingId,
     pauseUpdatingId,
diff --git a/gui/src/hooks/useProviderAccountPools.ts b/gui/src/hooks/useProviderAccountPools.ts
index 393727d094e..2a1e7234cdc 100644
--- a/gui/src/hooks/useProviderAccountPools.ts
+++ b/gui/src/hooks/useProviderAccountPools.ts
@@ -2,6 +2,8 @@ import { parseQuotaFailureCode } from "../../../src/providers/quota-types";
 import { useCallback, useEffect, useMemo, useRef, useState, type MutableRefObject } from "react";
 import type { AccountLoadState, AccountQuotaReading } from "../components/provider-workspace/types";
 import { createBoundedFetch } from "../bounded-fetch";
+import { confirmAction, requestTextValue } from "../action-dialogs";
+import { credentialAliasRejection, CREDENTIAL_ALIAS_MAX_LENGTH } from "../credential-alias";
 import { accountNeedsReauth } from "../oauth-health-display";
 import { oauthAccountDisplayLabel } from "../provider-workspace/auth";
 
@@ -427,7 +429,12 @@ export function useProviderAccountPools(deps: {
   };
 
   const removeApiKey = async (provider: string, entry: ApiKeyEntry) => {
-    if (!window.confirm(t("prov.keyRemoveConfirm", { key: entry.label ?? entry.masked }))) return;
+    const consented = await confirmAction({
+      message: t("prov.keyRemoveConfirm", { key: entry.label ?? entry.masked }),
+      confirmLabel: t("common.remove"),
+      tone: "danger",
+    });
+    if (!consented) return;
     const res = await fetch(`${apiBase}/api/providers/keys?name=${encodeURIComponent(provider)}&id=${encodeURIComponent(entry.id)}`, { method: "DELETE" });
     if (res.ok) {
       notify(t("prov.keyRemoved", { key: entry.label ?? entry.masked }), true);
@@ -466,7 +473,12 @@ export function useProviderAccountPools(deps: {
   };
 
   const editCredentialAlias = async (provider: string, type: "oauth" | "api-key", id: string, current?: string) => {
-    const entered = window.prompt(t("prov.aliasPrompt"), current ?? "");
+    const entered = await requestTextValue({
+      message: t("prov.aliasPrompt"),
+      initialValue: current ?? "",
+      maxLength: CREDENTIAL_ALIAS_MAX_LENGTH,
+      validate: value => credentialAliasRejection(value, t),
+    });
     if (entered === null) return;
     const alias = entered.trim();
     const response = await fetch(type === "oauth" ? `${apiBase}/api/oauth/accounts/alias` : `${apiBase}/api/providers/keys/alias`, {
@@ -485,7 +497,12 @@ export function useProviderAccountPools(deps: {
 
   const removeAccount = async (provider: string, account: OAuthAccount) => {
     const label = oauthAccountDisplayLabel(accountSets[provider]?.accounts ?? [account], account, t);
-    if (!window.confirm(t("prov.accountRemoveConfirm", { email: label }))) return;
+    const consented = await confirmAction({
+      message: t("prov.accountRemoveConfirm", { email: label }),
+      confirmLabel: t("common.remove"),
+      tone: "danger",
+    });
+    if (!consented) return;
     try {
       const res = await fetch(`${apiBase}/api/oauth/accounts?provider=${encodeURIComponent(provider)}&id=${encodeURIComponent(account.id)}`, { method: "DELETE" });
       if (!res.ok) { notify(t("prov.accountRemoveFail", { email: label }), false); return; }
diff --git a/gui/src/i18n/de.ts b/gui/src/i18n/de.ts
index 1f75761045e..53d81dbce0c 100644
--- a/gui/src/i18n/de.ts
+++ b/gui/src/i18n/de.ts
@@ -322,6 +322,8 @@ export const de: Record<TKey, string> = {
   "dash.stop": "Proxy stoppen",
   "dash.stopConfirm": "Proxy stoppen und natives Codex wiederherstellen?",
   "dash.stopFailed": "Proxy konnte nicht gestoppt werden (HTTP {status}).",
+  "dash.stopStillRunning": "Der Proxy antwortet weiterhin und wurde nicht gestoppt.",
+  "dash.stopUnknown": "Der Stopp wurde nicht bestätigt. Prüfen Sie vor einem erneuten Versuch, ob der Proxy noch läuft.",
   "dash.maSwitchFailed": "Moduswechsel fehlgeschlagen (HTTP {status}).",
   "dash.maNetworkError": "Netzwerkfehler — läuft der Proxy?",
   "dash.stopping": "Wird gestoppt…",
@@ -366,7 +368,7 @@ export const de: Record<TKey, string> = {
   "compactionRouting.dataNotice": "Eine abgedeckte Komprimierungsanfrage sendet das gesamte Gespräch zur Zusammenfassung an den Anbieter des gewählten Modells, auch wenn das Gespräch bei einem anderen Anbieter läuft.",
   "compactionRouting.autoNotice": "Automatische Komprimierung läuft von selbst, daher kann ein langes Gespräch an diesen Anbieter gehen, ohne dass du es angefordert hast.",
   "compactionRouting.providerWarning": "Mit dieser Einstellung sendet jede abgedeckte Komprimierungsanfrage den vollständigen Gesprächsinhalt zur Zusammenfassung an {provider}.",
-  "compactionRouting.comboWarning": "Mit dieser Einstellung sendet jede abgedeckte Komprimierungsanfrage den vollständigen Gesprächsinhalt zur Zusammenfassung an jedes Ziel der Combo {combo} ({providers}), einschließlich Failover-Zielen.",
+  "compactionRouting.comboWarning": "Mit dieser Einstellung sendet jede abgedeckte Komprimierungsanfrage den vollständigen Gesprächsinhalt zur Zusammenfassung an die Combo {combo}. Die Combo versucht ihre Ziele ({providers}) der Reihe nach und verwendet das erste, das antwortet, sodass jedes davon das Gespräch erhalten kann.",
   "compactionRouting.comboProvidersUnknown": "ihre konfigurierten Zielanbieter",
   "compactionRouting.loadFailed": "Komprimierungseinstellungen konnten nicht geladen werden.",
   "compactionRouting.saved": "Komprimierungseinstellungen gespeichert.",
@@ -461,6 +463,7 @@ export const de: Record<TKey, string> = {
   "prov.aliasPrompt": "Anzeigename (leer lassen zum Entfernen)",
   "prov.aliasSaved": "Alias gespeichert",
   "prov.aliasSaveFailed": "Alias konnte nicht gespeichert werden",
+  "prov.aliasInvalid": "Höchstens 80 Zeichen, ohne Steuerzeichen.",
   "prov.accountId": "ID",
   "prov.pasteRedirect": "Redirect-URL oder Code einfügen",
   "prov.pasteRedirectHint": "Zeigt der Browser einen localhost-Fehler, kopiere die vollständige URL aus der Adressleiste und füge sie hier ein (oder den Autorisierungscode).",
@@ -873,7 +876,47 @@ export const de: Record<TKey, string> = {
   "logs.detail.attempt.recovery.image413": "Bildnutzlast zu groß (413)",
   "logs.detail.attempt.recovery.emptyCompletion": "Wiederholung nach leerer Antwort",
   "logs.detail.attempt.recovery.consoleGoUpload": "Console-Upload erneut versucht",
+  "logs.detail.attempt.recovery.key401": "API-Schlüssel erneut authentifiziert",
+  "logs.detail.attempt.recovery.oauthAccount429": "Konto rate-limitiert (429)",
+  "logs.detail.attempt.recovery.opaqueBlobRejection": "Veralteter verschlüsselter Zustand verworfen",
+  "logs.detail.attempt.recovery.reasoningEffortDowngrade": "Reasoning-Aufwand reduziert",
+  "logs.detail.outcome.label": "Ergebnis",
+  "logs.detail.outcome.completed": "Abgeschlossen",
+  "logs.detail.outcome.failed": "Fehlgeschlagen",
+  "logs.detail.outcome.incomplete": "Unvollständig",
+  "logs.detail.outcome.aborted": "Abgebrochen",
+  "logs.detail.sends.label": "Upstream-Sendungen",
+  "logs.detail.sends.unresolved": "ungeklärt",
   "logs.detail.attempt.recovery.unknown": "Unbekannter Wiederherstellungsgrund",
+  "logs.detail.cause.label": "Fehlerursache",
+  "logs.detail.stage.label": "erreicht",
+  "logs.detail.resend.label": "Erneut senden",
+  "logs.detail.cause.transportUnsent": "Nie an Upstream gesendet",
+  "logs.detail.cause.transportAmbiguous": "Verbindung verloren, Upstream-Status unbekannt",
+  "logs.detail.cause.upstreamDeclined": "Upstream lehnte den Start ab",
+  "logs.detail.cause.rateLimit": "Ratenlimit erreicht",
+  "logs.detail.cause.quotaExhausted": "Kontingent aufgebraucht",
+  "logs.detail.cause.credentialRejected": "Anmeldedaten abgelehnt",
+  "logs.detail.cause.policyRefusal": "Von der Inhaltsrichtlinie abgelehnt",
+  "logs.detail.cause.parameterRejected": "Anfrageparameter abgelehnt",
+  "logs.detail.cause.ciphertextRefusal": "Verschlüsselter Zustand abgelehnt",
+  "logs.detail.cause.payloadTooLarge": "Nutzlast zu groß",
+  "logs.detail.cause.payloadRejected": "Nutzlast abgelehnt",
+  "logs.detail.cause.upstreamFault": "Upstream-Fehler",
+  "logs.detail.cause.emptyOutput": "Keine verwertbare Ausgabe",
+  "logs.detail.cause.clientCancelled": "Vom Client abgebrochen",
+  "logs.detail.cause.localRefusal": "Von diesem Proxy abgelehnt",
+  "logs.detail.stage.preHeader": "kein Antwortkopf",
+  "logs.detail.stage.headersOnly": "nur Kopfzeilen",
+  "logs.detail.stage.protocolPrelude": "Protokollvorspann",
+  "logs.detail.stage.semanticOutput": "Ausgabe zugestellt",
+  "logs.detail.stage.sideEffect": "Nebenwirkung ausgelöst",
+  "logs.detail.stage.terminal": "Antwort zugestellt",
+  "logs.detail.resend.permitted": "Erneut sendbar",
+  "logs.detail.resend.permittedAfterRepair": "Nach Korrektur erneut sendbar",
+  "logs.detail.resend.refusedAmbiguous": "Nicht erneut gesendet: Upstream-Status unbekannt",
+  "logs.detail.resend.refusedCommitted": "Nicht erneut gesendet: Aufrufer sah bereits Ausgabe",
+  "logs.detail.resend.refusedFutile": "Nicht erneut gesendet: dieselbe Anfrage scheitert erneut",
   "logs.detail.reason.usage_missing": "Nutzung wurde nicht gemeldet.",
   "logs.detail.reason.usage_unsupported": "Dieser Anbieter meldet keine Nutzung.",
   "logs.detail.reason.output_missing": "Es wurden keine positiven Ausgabe-Tokens gemeldet.",
@@ -970,6 +1013,82 @@ export const de: Record<TKey, string> = {
   "usage.section.models": "Modelle",
   "usage.section.providers": "Anbieter",
   "usage.section.coverage": "Abdeckungs-Aufschlüsselung",
+  "usage.section.companion": "Menüleiste & Widget",
+  "usage.companion.title": "Menüleiste & Widget",
+  "usage.companion.description": "Diese Einstellungen steuern die OpenCodex Desktop-/Menüleisten-App und ihr Widget.",
+  "usage.companion.installGuide": "Installationsanleitung",
+  "usage.companion.loading": "Zeitachse wird geladen…",
+  "usage.companion.timelineUnavailable": "Zeitachse nicht verfügbar",
+  "usage.companion.empty": "Keine Nutzung in den letzten {hours} Std.",
+  "usage.companion.chartLabel": "Nutzungszeitachse",
+  "usage.companion.olderRecordsSkipped": "Ältere Einträge wurden übersprungen",
+  "usage.companion.settingsUnavailable": "Begleiteinstellungen nicht verfügbar",
+  "usage.companion.corrupt": "Die Datei mit den Begleiteinstellungen ist beschädigt. Die Steuerelemente zeigen Standardwerte; das Speichern ist pausiert, bis Sie die Datei ersetzen.",
+  "usage.companion.corruptReset": "Durch Standardwerte ersetzen",
+  "usage.companion.connected": "Menüleisten-App verbunden · {age}",
+  "usage.companion.connectedDesktop": "Desktop-App verbunden · {age}",
+  "usage.companion.installTitle": "Desktop-App installieren",
+  "usage.companion.installOs": "Betriebssystem",
+  "usage.companion.osMac": "macOS",
+  "usage.companion.osWindows": "Windows",
+  "usage.companion.osLinux": "Linux",
+  "usage.companion.runningInDesktop": "Du bist in der OpenCodex-Desktop-App {version}",
+  "usage.companion.openInBrowser": "Im Browser öffnen",
+  "usage.companion.installMacStep1": "Laden Sie OpenCodex-<version>-macos.dmg aus der neuesten Veröffentlichung herunter und ziehen Sie OpenCodex.app in Programme.",
+  "usage.companion.installMacStep2": "Erster Start: Klicken Sie mit der rechten Maustaste auf OpenCodex.app → Öffnen (Gatekeeper fragt einmal, bis die App notariell signiert ist).",
+  "usage.companion.installMacStep3": "Die App findet diesen Proxy selbst; das Widget erscheint in der Widget-Galerie, sobald die App ausgeführt wurde.",
+  "usage.companion.installWinStep1": "Laden Sie OpenCodex-<version>-windows-x64.msi aus der neuesten Veröffentlichung herunter und führen Sie es aus.",
+  "usage.companion.installWinStep2": "Wenn SmartScreen warnt, wählen Sie Weitere Informationen → Trotzdem ausführen (der Installer ist noch nicht signiert).",
+  "usage.companion.installWinStep3": "OpenCodex erscheint in der Taskleiste und verbindet sich mit diesem Proxy oder startet den gebündelten Proxy.",
+  "usage.companion.installLinuxStep1": "Laden Sie OpenCodex-<version>-linux-x86_64.AppImage (oder die .deb-Datei) aus der neuesten Veröffentlichung herunter.",
+  "usage.companion.installLinuxStep2": "Führen Sie chmod +x für das AppImage aus und starten Sie es; ein Tray-Symbol benötigt einen AppIndicator-fähigen Desktop.",
+  "usage.companion.installLinuxStep3": "Die App verbindet sich mit diesem Proxy oder startet den gebündelten Proxy.",
+  "usage.companion.notConnected": "Noch keine Menüleisten-App hat sich mit diesem Proxy verbunden.",
+  "usage.companion.lastSeen": "Zuletzt gesehen {age}",
+  "usage.companion.installAnother": "Auf einem anderen Gerät installieren",
+  "usage.companion.saved": "Gespeichert · {time}",
+  "usage.companion.saveFailed": "Speichern fehlgeschlagen: {error}",
+  "usage.companion.reset": "Auf Standardwerte zurücksetzen",
+  "usage.companion.footer": "Das Widget zeigt die heutigen Anfragen, Tokens und Kosten sowie das hier konfigurierte Diagramm und wird beim Abruf der App aktualisiert.",
+  "usage.companion.menuBarShows": "Menüleiste zeigt",
+  "usage.companion.menuRequests": "Anfragen",
+  "usage.companion.menuTokens": "Token",
+  "usage.companion.menuCost": "Kosten",
+  "usage.companion.menuQuota": "Kontingent",
+  "usage.companion.menuNone": "Nur Symbol",
+  "usage.companion.window": "Zeitraum",
+  "usage.companion.window6": "6 Std.",
+  "usage.companion.window24": "24 Std.",
+  "usage.companion.window72": "3 Tage",
+  "usage.companion.window168": "7 Tage",
+  "usage.companion.style": "Stil",
+  "usage.companion.styleLine": "Linie",
+  "usage.companion.styleStacked": "Gestapelt",
+  "usage.companion.metric": "Kennzahl",
+  "usage.companion.metricTotal": "Gesamt",
+  "usage.companion.metricInput": "Eingabe",
+  "usage.companion.metricOutput": "Ausgabe",
+  "usage.companion.metricCached": "Gecacht",
+  "usage.companion.groupBy": "Gruppieren nach",
+  "usage.companion.groupModel": "Modell",
+  "usage.companion.groupAccount": "Modell + Konto",
+  "usage.companion.popoverSections": "Popover-Bereiche",
+  "usage.companion.sectionToday": "Heute",
+  "usage.companion.sectionChart": "Diagramm",
+  "usage.companion.sectionModels": "Modelle",
+  "usage.companion.sectionCost": "Kosten",
+  "usage.companion.sectionAccounts": "Konten",
+  "usage.companion.advanced": "Erweitert",
+  "usage.companion.aggregation": "Aggregation",
+  "usage.companion.aggregationSum": "Summe",
+  "usage.companion.aggregationAverage": "Durchschnitt",
+  "usage.companion.aggregationMax": "Maximum",
+  "usage.companion.menuText": "Menüleistentext",
+  "usage.companion.placeholders": "Platzhalter:",
+  "usage.companion.modelsOnChart": "Modelle im Diagramm",
+  "usage.companion.modelsCount": "{selected} von {total} im Diagramm",
+  "usage.companion.modelsShowAll": "Alle anzeigen",
+  "usage.companion.hideProviders": "Provider ausblenden",
   "usage.workspace.report": "Nutzungsbericht",
   "usage.workspace.sections": "Nutzungsabschnitte",
   "usage.coverage.measured": "Gemessen",
@@ -980,6 +1099,14 @@ export const de: Record<TKey, string> = {
   "usage.col.requests": "Anfragen",
   "usage.col.measured": "Gemessen",
   "usage.col.reported": "Gemeldet",
+  "usage.col.inputTokens": "Eingabe-Tokens",
+  "usage.col.outputTokens": "Ausgabe-Tokens",
+  "usage.col.cacheHits": "Cache-Treffer",
+  "usage.col.cacheWrites": "Cache-Schreibvorgänge",
+  "usage.col.cacheHitRate": "Trefferquote",
+  "usage.cacheHitRate.partial": "Gemittelt über {measured} von insgesamt {total} Eingabe-Tokens; für die übrigen Anfragen wurden keine Cache-Details gemeldet.",
+  "usage.cacheHitRate.unmeasured": "Für keine Anfrage in dieser Zeile wurden Cache-Details gemeldet, daher kann keine durchschnittliche Trefferquote berechnet werden.",
+  "usage.unavailable": "—",
   "usage.col.tokens": "Tokens",
   "usage.col.apiListPrice": "API-Listenpreis",
   "usage.col.share": "Anteil",
@@ -1309,6 +1436,7 @@ export const de: Record<TKey, string> = {
   "integrations.status.installed": "Installiert",
   "integrations.status.notInstalled": "Nicht installiert",
   "integrations.status.appliedAt": "Angewendet",
+  "integrations.status.supersededStore": "Dieser Client liest seine Provider jetzt aus {path}, und opencodex schreibt diese Datei nicht. Ein Aktivieren hier ändert nichts an dem, was der Client lädt.",
   "integrations.status.backup": "Sicherung",
   "integrations.status.lastRestore": "Letzte Wiederherstellung",
   "integrations.status.unknown": "Unbekannt",
@@ -1369,6 +1497,7 @@ export const de: Record<TKey, string> = {
   "integrations.plan.refusal.conflict": "Die verwalteten Einstellungen stehen im Konflikt mit der aktuellen Datei. Prüfe die Datei oder verwende Ersetzen, wenn diese Aktion verfügbar ist.",
   "integrations.plan.refusal.unsafe": "Die Client-Konfiguration kann nicht sicher geändert werden. Repariere oder ersetze die Datei und versuche es erneut.",
   "integrations.plan.refusal.nonLoopback": "Dieser Client benötigt eine Loopback-Proxyadresse. Verwende localhost, einen Tunnel oder eine lokale Weiterleitung.",
+  "integrations.plan.refusal.supersededStore": "Dieser Client liest seine Provider aus einer Datei, die opencodex nicht schreibt. Dieser Vorgang würde nichts an dem ändern, was der Client lädt.",
   "integrations.plan.refusal.driftRequiresConfirm": "Die Datei wurde nach diesem Rollback-Punkt geändert. Prüfe vor der Wiederherstellung den Drift-Plan.",
   "integrations.plan.refusal.snapshotExpired": "Die Sicherung für diesen Rollback-Punkt ist abgelaufen und kann nicht mehr wiederhergestellt werden.",
   "integrations.plan.refusal.writeFailed": "Der Server konnte keinen sicheren Schreibvorgang vorbereiten. Aktualisiere den Integrationsstatus und versuche es erneut.",
@@ -1577,6 +1706,7 @@ export const de: Record<TKey, string> = {
   "accountPool.priorityUpdateFailed": "Die Auswahlreihenfolge für {email} konnte nicht gespeichert werden. Der zuletzt bestätigte Wert wird angezeigt.",
   "codexAuth.switched": "{email} ist für die nächste Anfrage ausgewählt",
   "codexAuth.loadFailed": "Die Codex-Kontoeinstellungen konnten nicht geladen werden.",
+  "codexAuth.accountsRefreshFailed": "Die letzte Kontoaktualisierung ist fehlgeschlagen. Unten stehen die zuletzt bestätigten Konten.",
   "codexAuth.switchFailed": "Das Konto konnte nicht gewechselt werden. Die vorherige Auswahl bleibt erhalten.",
   "codexAuth.removeConfirm": "{id} entfernen?",
   "codexAuth.removeFailed": "Das Konto konnte nicht entfernt werden. Es wurde nichts geändert.",
@@ -2616,6 +2746,19 @@ export const de: Record<TKey, string> = {
   "claudeDesktop.status.notActiveProfile": "Desktop nutzt ein anderes Profil — erneut anwenden",
   "claudeDesktop.status.disabled": "Die Claude-Desktop-Integration ist deaktiviert. Beende Desktop nach dem Aktivieren vollständig und öffne es erneut.",
   "claudeDesktop.enableApply": "Aktivieren und anwenden",
+  "claudeDesktop.switchModeApply": "Modus wechseln & anwenden",
+  "claudeDesktop.status.appliedFirstParty": "First-Party: Code-Tab läuft über den lokalen Proxy",
+  "claudeDesktop.mode.legend": "Verbindungsmodus",
+  "claudeDesktop.mode.firstParty": "First-Party",
+  "claudeDesktop.mode.gateway": "Gateway (Drittanbieter)",
+  "claudeDesktop.mode.defaultBadge": "Standard",
+  "claudeDesktop.mode.current": "aktuell",
+  "claudeDesktop.mode.firstPartyHint": "Desktop bleibt bei claude.ai angemeldet (Chat, Connectors, Remote Control). Nur der Code-Tab, seine Subagenten und die Claude Code CLI laufen über OpenCodex.",
+  "claudeDesktop.mode.gatewayHint": "Die ganze App wechselt auf OpenCodex als Gateway. Chat läuft lokal; claude.ai-Funktionen sind nicht verfügbar.",
+  "claudeDesktop.mode.switchNote": "Der Wechsel ersetzt die Konfiguration des anderen Modus. Desktop danach vollständig beenden und neu öffnen.",
+  "claudeDesktop.firstParty.proxyRunning": "Lokaler Proxy auf 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "Lokaler Proxy 127.0.0.1:{port} läuft nicht — OpenCodex neu starten",
+  "claudeDesktop.firstParty.interceptDisabled": "Intercept-Proxy ist in der Konfiguration deaktiviert (claudeCode.intercept.enabled)",
   "claudeDesktop.health.lastRequest": "Letzte Anfrage",
   "claudeDesktop.health.stats": "{count} Anf. / {errors} Fehl.",
   "claudeDesktop.effort.supported": "effort",
diff --git a/gui/src/i18n/en.ts b/gui/src/i18n/en.ts
index 4146debb96d..d6fe0a55785 100644
--- a/gui/src/i18n/en.ts
+++ b/gui/src/i18n/en.ts
@@ -334,6 +334,8 @@ export const en = {
   "dash.stop": "Stop Proxy",
   "dash.stopConfirm": "Stop the proxy and restore native Codex?",
   "dash.stopFailed": "Failed to stop proxy (HTTP {status}).",
+  "dash.stopStillRunning": "The proxy is still answering, so it did not stop.",
+  "dash.stopUnknown": "The proxy did not confirm the stop. Check whether it is still running before trying again.",
   "dash.maSwitchFailed": "Mode switch failed (HTTP {status}).",
   "dash.maNetworkError": "Network error — is the proxy running?",
   "dash.stopping": "Stopping…",
@@ -384,7 +386,7 @@ export const en = {
   "compactionRouting.dataNotice": "A covered compaction request sends the entire conversation to the selected model's provider for summarization, even when the conversation runs on another provider.",
   "compactionRouting.autoNotice": "Automatic compaction runs on its own, so a long conversation can be sent to that provider without you asking for it.",
   "compactionRouting.providerWarning": "With this setting, every covered compaction request sends the full conversation contents to {provider} for summarization.",
-  "compactionRouting.comboWarning": "With this setting, every covered compaction request sends the full conversation contents to every target of combo {combo} ({providers}), including failover targets, for summarization.",
+  "compactionRouting.comboWarning": "With this setting, every covered compaction request sends the full conversation contents to combo {combo} for summarization. The combo attempts its targets ({providers}) in order and uses the first that answers, so any one of them can receive the conversation.",
   "compactionRouting.comboProvidersUnknown": "its configured target providers",
   "compactionRouting.loadFailed": "Could not load compaction settings.",
   "compactionRouting.saved": "Compaction settings saved.",
@@ -484,6 +486,7 @@ export const en = {
   "prov.aliasPrompt": "Display name (leave empty to clear)",
   "prov.aliasSaved": "Alias saved",
   "prov.aliasSaveFailed": "Could not save alias",
+  "prov.aliasInvalid": "Use at most 80 characters, with no control characters.",
   "prov.accountId": "ID",
   "prov.pasteRedirect": "Paste redirect URL or code",
   "prov.pasteRedirectHint": "If the browser shows a localhost error, copy the full URL from its address bar and paste it here (or paste the authorization code).",
@@ -922,7 +925,47 @@ export const en = {
   "logs.detail.attempt.recovery.image413": "Image payload too large (413)",
   "logs.detail.attempt.recovery.emptyCompletion": "Empty completion retry",
   "logs.detail.attempt.recovery.consoleGoUpload": "Console upload retry",
+  "logs.detail.attempt.recovery.key401": "API key re-authentication",
+  "logs.detail.attempt.recovery.oauthAccount429": "Account rate-limited (429)",
+  "logs.detail.attempt.recovery.opaqueBlobRejection": "Stale encrypted state dropped",
+  "logs.detail.attempt.recovery.reasoningEffortDowngrade": "Reasoning effort downgraded",
+  "logs.detail.outcome.label": "Outcome",
+  "logs.detail.outcome.completed": "Completed",
+  "logs.detail.outcome.failed": "Failed",
+  "logs.detail.outcome.incomplete": "Incomplete",
+  "logs.detail.outcome.aborted": "Aborted",
+  "logs.detail.sends.label": "Upstream sends",
+  "logs.detail.sends.unresolved": "unresolved",
   "logs.detail.attempt.recovery.unknown": "Unknown recovery reason",
+  "logs.detail.cause.label": "Failure cause",
+  "logs.detail.stage.label": "reached",
+  "logs.detail.resend.label": "Resend",
+  "logs.detail.cause.transportUnsent": "Never sent upstream",
+  "logs.detail.cause.transportAmbiguous": "Connection lost, upstream state unknown",
+  "logs.detail.cause.upstreamDeclined": "Upstream declined to start",
+  "logs.detail.cause.rateLimit": "Rate limited",
+  "logs.detail.cause.quotaExhausted": "Quota exhausted",
+  "logs.detail.cause.credentialRejected": "Credentials rejected",
+  "logs.detail.cause.policyRefusal": "Refused by content policy",
+  "logs.detail.cause.parameterRejected": "Request parameter rejected",
+  "logs.detail.cause.ciphertextRefusal": "Encrypted state rejected",
+  "logs.detail.cause.payloadTooLarge": "Payload too large",
+  "logs.detail.cause.payloadRejected": "Payload rejected",
+  "logs.detail.cause.upstreamFault": "Upstream fault",
+  "logs.detail.cause.emptyOutput": "No usable output",
+  "logs.detail.cause.clientCancelled": "Cancelled by the client",
+  "logs.detail.cause.localRefusal": "Refused by this proxy",
+  "logs.detail.stage.preHeader": "no response head",
+  "logs.detail.stage.headersOnly": "headers only",
+  "logs.detail.stage.protocolPrelude": "protocol prelude",
+  "logs.detail.stage.semanticOutput": "output delivered",
+  "logs.detail.stage.sideEffect": "side effect emitted",
+  "logs.detail.stage.terminal": "answer delivered",
+  "logs.detail.resend.permitted": "Could be resent",
+  "logs.detail.resend.permittedAfterRepair": "Could be resent after repair",
+  "logs.detail.resend.refusedAmbiguous": "Not resent: upstream state unknown",
+  "logs.detail.resend.refusedCommitted": "Not resent: caller already saw output",
+  "logs.detail.resend.refusedFutile": "Not resent: the same request would fail again",
   "logs.detail.reason.usage_missing": "Usage was not reported.",
   "logs.detail.reason.usage_unsupported": "This provider does not report usage.",
   "logs.detail.reason.output_missing": "No positive output token count was reported.",
@@ -1023,6 +1066,82 @@ export const en = {
   "usage.section.models": "Models",
   "usage.section.providers": "Providers",
   "usage.section.coverage": "Coverage breakdown",
+  "usage.section.companion": "Menu bar & widget",
+  "usage.companion.title": "Menu bar & widget",
+  "usage.companion.description": "Settings here drive the OpenCodex desktop/menu bar app and its widget.",
+  "usage.companion.installGuide": "Install guide",
+  "usage.companion.loading": "Loading timeline…",
+  "usage.companion.timelineUnavailable": "Timeline unavailable",
+  "usage.companion.empty": "No usage in the last {hours}h",
+  "usage.companion.chartLabel": "Usage timeline",
+  "usage.companion.olderRecordsSkipped": "Older records were skipped",
+  "usage.companion.settingsUnavailable": "Companion settings unavailable",
+  "usage.companion.corrupt": "The companion settings file is corrupt. Controls show defaults; saving is paused until you replace the file.",
+  "usage.companion.corruptReset": "Replace with defaults",
+  "usage.companion.connected": "Menu bar app connected · {age}",
+  "usage.companion.connectedDesktop": "Desktop app connected · {age}",
+  "usage.companion.installTitle": "Install the desktop app",
+  "usage.companion.installOs": "Operating system",
+  "usage.companion.osMac": "macOS",
+  "usage.companion.osWindows": "Windows",
+  "usage.companion.osLinux": "Linux",
+  "usage.companion.runningInDesktop": "You’re in the OpenCodex desktop app {version}",
+  "usage.companion.openInBrowser": "Open in browser",
+  "usage.companion.installMacStep1": "Download OpenCodex-<version>-macos.dmg from the latest release and drag OpenCodex.app to Applications.",
+  "usage.companion.installMacStep2": "First launch: right-click OpenCodex.app → Open (Gatekeeper asks once until the app is notarized).",
+  "usage.companion.installMacStep3": "The app finds this proxy on its own; the widget appears in the widget gallery once the app has run.",
+  "usage.companion.installWinStep1": "Download OpenCodex-<version>-windows-x64.msi from the latest release and run it.",
+  "usage.companion.installWinStep2": "If SmartScreen warns, choose More info → Run anyway (the installer is not yet code-signed).",
+  "usage.companion.installWinStep3": "OpenCodex appears in the system tray and attaches to this proxy, or starts its bundled one.",
+  "usage.companion.installLinuxStep1": "Download OpenCodex-<version>-linux-x86_64.AppImage (or the .deb) from the latest release.",
+  "usage.companion.installLinuxStep2": "chmod +x the AppImage and run it; a tray icon requires an AppIndicator-capable desktop.",
+  "usage.companion.installLinuxStep3": "The app attaches to this proxy, or starts its bundled one.",
+  "usage.companion.notConnected": "No menu bar app has connected to this proxy yet.",
+  "usage.companion.lastSeen": "Last seen {age}",
+  "usage.companion.installAnother": "Install on another device",
+  "usage.companion.saved": "Saved · {time}",
+  "usage.companion.saveFailed": "Couldn’t save: {error}",
+  "usage.companion.reset": "Reset to defaults",
+  "usage.companion.footer": "The widget shows today's requests, tokens and cost plus the chart configured here, and refreshes when the app polls.",
+  "usage.companion.menuBarShows": "Menu bar shows",
+  "usage.companion.menuRequests": "Requests",
+  "usage.companion.menuTokens": "Tokens",
+  "usage.companion.menuCost": "Cost",
+  "usage.companion.menuQuota": "Quota",
+  "usage.companion.menuNone": "Icon only",
+  "usage.companion.window": "Window",
+  "usage.companion.window6": "6h",
+  "usage.companion.window24": "24h",
+  "usage.companion.window72": "3d",
+  "usage.companion.window168": "7d",
+  "usage.companion.style": "Style",
+  "usage.companion.styleLine": "Line",
+  "usage.companion.styleStacked": "Stacked",
+  "usage.companion.metric": "Metric",
+  "usage.companion.metricTotal": "Total",
+  "usage.companion.metricInput": "Input",
+  "usage.companion.metricOutput": "Output",
+  "usage.companion.metricCached": "Cached",
+  "usage.companion.groupBy": "Group by",
+  "usage.companion.groupModel": "Model",
+  "usage.companion.groupAccount": "Model + account",
+  "usage.companion.popoverSections": "Popover sections",
+  "usage.companion.sectionToday": "Today",
+  "usage.companion.sectionChart": "Chart",
+  "usage.companion.sectionModels": "Models",
+  "usage.companion.sectionCost": "Cost",
+  "usage.companion.sectionAccounts": "Accounts",
+  "usage.companion.advanced": "Advanced",
+  "usage.companion.aggregation": "Aggregation",
+  "usage.companion.aggregationSum": "Sum",
+  "usage.companion.aggregationAverage": "Average",
+  "usage.companion.aggregationMax": "Max",
+  "usage.companion.menuText": "Menu bar text",
+  "usage.companion.placeholders": "Placeholders:",
+  "usage.companion.modelsOnChart": "Models on chart",
+  "usage.companion.modelsCount": "{selected} of {total} on chart",
+  "usage.companion.modelsShowAll": "Show all",
+  "usage.companion.hideProviders": "Hide providers",
   "usage.workspace.report": "Usage report",
   "usage.workspace.sections": "Usage sections",
   "usage.coverage.measured": "Measured",
@@ -1033,6 +1152,14 @@ export const en = {
   "usage.col.requests": "Requests",
   "usage.col.measured": "Measured",
   "usage.col.reported": "Reported",
+  "usage.col.inputTokens": "Input tokens",
+  "usage.col.outputTokens": "Output tokens",
+  "usage.col.cacheHits": "Cache hits",
+  "usage.col.cacheWrites": "Cache writes",
+  "usage.col.cacheHitRate": "Hit rate",
+  "usage.cacheHitRate.partial": "Averaged over {measured} of {total} input tokens; the remaining requests reported no cache detail.",
+  "usage.cacheHitRate.unmeasured": "No request for this row reported cache detail, so there is no hit rate to average.",
+  "usage.unavailable": "—",
   "usage.col.tokens": "Tokens",
   "usage.col.apiListPrice": "API list-price",
   "usage.col.share": "Share",
@@ -1897,6 +2024,7 @@ export const en = {
   "integrations.status.installed": "Installed",
   "integrations.status.notInstalled": "Not installed",
   "integrations.status.appliedAt": "Applied",
+  "integrations.status.supersededStore": "This client now reads its providers from {path}, which opencodex does not write, so enabling it here would change nothing it loads.",
   "integrations.status.backup": "Backup",
   "integrations.status.lastRestore": "Last restore",
   "integrations.status.unknown": "Unknown",
@@ -1957,6 +2085,7 @@ export const en = {
   "integrations.plan.refusal.conflict": "The managed settings conflict with the current file. Review the file or use Replace when that action is available.",
   "integrations.plan.refusal.unsafe": "The client configuration cannot be changed safely. Repair or replace the file before trying again.",
   "integrations.plan.refusal.nonLoopback": "This client requires a loopback proxy address. Use localhost access, a tunnel, or a local forwarder before trying again.",
+  "integrations.plan.refusal.supersededStore": "This client now reads its providers from a file opencodex does not write, so this operation would change nothing it loads.",
   "integrations.plan.refusal.driftRequiresConfirm": "The file changed after this rollback point. Review the drift-aware plan before restoring.",
   "integrations.plan.refusal.snapshotExpired": "The backup for this rollback point has expired, so it can no longer be restored.",
   "integrations.plan.refusal.writeFailed": "The server could not prepare a safe write. Refresh the integration state before trying again.",
@@ -2171,6 +2300,7 @@ export const en = {
 
   "codexAuth.switched": "{email} is selected for the next request",
   "codexAuth.loadFailed": "Codex account settings could not be loaded.",
+  "codexAuth.accountsRefreshFailed": "The latest account refresh failed. The accounts below are the last ones confirmed.",
   "codexAuth.switchFailed": "The account could not be switched. Your previous selection is unchanged.",
   "codexAuth.removeConfirm": "Remove {id}?",
   "codexAuth.removeFailed": "The account could not be removed. Nothing was changed.",
@@ -2716,6 +2846,19 @@ export const en = {
   "claudeDesktop.status.notActiveProfile": "Desktop is serving another profile — re-apply",
   "claudeDesktop.status.disabled": "Claude Desktop integration is off. Fully quit and reopen Desktop after enabling it.",
   "claudeDesktop.enableApply": "Enable and apply",
+  "claudeDesktop.switchModeApply": "Switch mode & apply",
+  "claudeDesktop.status.appliedFirstParty": "First-party: Code tab routed through the local proxy",
+  "claudeDesktop.mode.legend": "Connection mode",
+  "claudeDesktop.mode.firstParty": "First-party",
+  "claudeDesktop.mode.gateway": "Gateway (third-party)",
+  "claudeDesktop.mode.defaultBadge": "default",
+  "claudeDesktop.mode.current": "current",
+  "claudeDesktop.mode.firstPartyHint": "Desktop stays signed in to claude.ai (chat, connectors, remote control). Only the Code tab, its subagents and the Claude Code CLI go through OpenCodex.",
+  "claudeDesktop.mode.gatewayHint": "The whole app switches to OpenCodex as its gateway. Chat runs locally; claude.ai features are unavailable.",
+  "claudeDesktop.mode.switchNote": "Switching replaces the other mode's configuration. Fully quit and reopen Desktop afterwards.",
+  "claudeDesktop.firstParty.proxyRunning": "Local proxy on 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "Local proxy 127.0.0.1:{port} is not running — restart OpenCodex",
+  "claudeDesktop.firstParty.interceptDisabled": "Intercept proxy is disabled in config (claudeCode.intercept.enabled)",
   "claudeDesktop.health.lastRequest": "Last request",
   "claudeDesktop.health.stats": "{count} req / {errors} err",
   "claudeDesktop.effort.supported": "effort",
diff --git a/gui/src/i18n/fr.ts b/gui/src/i18n/fr.ts
index 1153c7329b2..906f7d39462 100644
--- a/gui/src/i18n/fr.ts
+++ b/gui/src/i18n/fr.ts
@@ -324,6 +324,8 @@ export const fr: Record<TKey, string> = {
   "dash.stop": "Arrêter le proxy",
   "dash.stopConfirm": "Arrêter le proxy et restaurer Codex natif ?",
   "dash.stopFailed": "Échec de l’arrêt du proxy (HTTP {status}).",
+  "dash.stopStillRunning": "Le proxy répond toujours : il ne s’est pas arrêté.",
+  "dash.stopUnknown": "L’arrêt n’a pas été confirmé. Vérifiez si le proxy tourne encore avant de réessayer.",
   "dash.maSwitchFailed": "Échec du changement de mode (HTTP {status}).",
   "dash.maNetworkError": "Erreur réseau — le proxy est-il en cours d’exécution ?",
   "dash.stopping": "Arrêt…",
@@ -374,7 +376,7 @@ export const fr: Record<TKey, string> = {
   "compactionRouting.dataNotice": "Une requête de compaction couverte envoie toute la conversation au fournisseur du modèle choisi pour la résumer, même si la conversation s’exécute chez un autre fournisseur.",
   "compactionRouting.autoNotice": "La compaction automatique se déclenche d’elle-même : une longue conversation peut donc partir chez ce fournisseur sans que vous l’ayez demandé.",
   "compactionRouting.providerWarning": "Avec ce réglage, chaque requête de compaction couverte envoie l’intégralité du contenu de la conversation à {provider} pour la résumer.",
-  "compactionRouting.comboWarning": "Avec ce réglage, chaque requête de compaction couverte envoie l’intégralité du contenu de la conversation à chaque cible du combo {combo} ({providers}), y compris les cibles de bascule, pour le résumer.",
+  "compactionRouting.comboWarning": "Avec ce réglage, chaque requête de compaction couverte envoie l’intégralité du contenu de la conversation au combo {combo} pour le résumer. Le combo essaie ses cibles ({providers}) dans l’ordre et retient la première qui répond, donc n’importe laquelle peut recevoir la conversation.",
   "compactionRouting.comboProvidersUnknown": "ses fournisseurs cibles configurés",
   "compactionRouting.loadFailed": "Impossible de charger les paramètres de compaction.",
   "compactionRouting.saved": "Paramètres de compaction enregistrés.",
@@ -471,6 +473,7 @@ export const fr: Record<TKey, string> = {
   "prov.aliasPrompt": "Nom d’affichage (laissez vide pour l’effacer)",
   "prov.aliasSaved": "Alias enregistré",
   "prov.aliasSaveFailed": "Impossible d’enregistrer l’alias",
+  "prov.aliasInvalid": "Utilisez au maximum 80 caractères, sans caractères de contrôle.",
   "prov.accountId": "ID",
   "prov.pasteRedirect": "Coller l’URL de redirection ou le code",
   "prov.pasteRedirectHint": "Si le navigateur affiche une erreur localhost, copiez l’URL complète depuis sa barre d’adresse et collez-la ici (ou collez le code d’autorisation).",
@@ -898,12 +901,52 @@ export const fr: Record<TKey, string> = {
   "logs.detail.attempt.recovery.connectionReset": "Réinitialisation de la connexion",
   "logs.detail.attempt.recovery.emptyCompletion": "Nouvelle tentative après une réponse vide",
   "logs.detail.attempt.recovery.consoleGoUpload": "Nouvelle tentative d’envoi Console",
+  "logs.detail.attempt.recovery.key401": "Ré-authentification de la clé API",
+  "logs.detail.attempt.recovery.oauthAccount429": "Compte limité (429)",
+  "logs.detail.attempt.recovery.opaqueBlobRejection": "État chiffré obsolète abandonné",
+  "logs.detail.attempt.recovery.reasoningEffortDowngrade": "Effort de raisonnement réduit",
+  "logs.detail.outcome.label": "Résultat",
+  "logs.detail.outcome.completed": "Terminé",
+  "logs.detail.outcome.failed": "Échec",
+  "logs.detail.outcome.incomplete": "Incomplet",
+  "logs.detail.outcome.aborted": "Interrompu",
+  "logs.detail.sends.label": "Envois en amont",
+  "logs.detail.sends.unresolved": "non résolus",
   "logs.detail.attempt.recovery.oauth401": "Réauthentification OAuth",
   "logs.detail.attempt.recovery.key429": "Clé soumise à une limitation de débit (429)",
   "logs.detail.attempt.recovery.rateLimit429": "Limitation de débit (429)",
   "logs.detail.attempt.recovery.anthropicOauth429": "Limitation de débit OAuth Anthropic (429)",
   "logs.detail.attempt.recovery.image413": "Charge utile d’image trop volumineuse (413)",
   "logs.detail.attempt.recovery.unknown": "Motif de récupération inconnu",
+  "logs.detail.cause.label": "Cause de l'échec",
+  "logs.detail.stage.label": "atteint",
+  "logs.detail.resend.label": "Renvoi",
+  "logs.detail.cause.transportUnsent": "Jamais envoyé en amont",
+  "logs.detail.cause.transportAmbiguous": "Connexion perdue, état amont inconnu",
+  "logs.detail.cause.upstreamDeclined": "L'amont a refusé de démarrer",
+  "logs.detail.cause.rateLimit": "Débit limité",
+  "logs.detail.cause.quotaExhausted": "Quota épuisé",
+  "logs.detail.cause.credentialRejected": "Identifiants refusés",
+  "logs.detail.cause.policyRefusal": "Refusé par la politique de contenu",
+  "logs.detail.cause.parameterRejected": "Paramètre de requête refusé",
+  "logs.detail.cause.ciphertextRefusal": "État chiffré refusé",
+  "logs.detail.cause.payloadTooLarge": "Charge utile trop volumineuse",
+  "logs.detail.cause.payloadRejected": "Charge utile refusée",
+  "logs.detail.cause.upstreamFault": "Panne en amont",
+  "logs.detail.cause.emptyOutput": "Aucune sortie exploitable",
+  "logs.detail.cause.clientCancelled": "Annulé par le client",
+  "logs.detail.cause.localRefusal": "Refusé par ce proxy",
+  "logs.detail.stage.preHeader": "aucun en-tête de réponse",
+  "logs.detail.stage.headersOnly": "en-têtes seulement",
+  "logs.detail.stage.protocolPrelude": "prélude de protocole",
+  "logs.detail.stage.semanticOutput": "sortie livrée",
+  "logs.detail.stage.sideEffect": "effet de bord émis",
+  "logs.detail.stage.terminal": "réponse livrée",
+  "logs.detail.resend.permitted": "Peut être renvoyé",
+  "logs.detail.resend.permittedAfterRepair": "Peut être renvoyé après correction",
+  "logs.detail.resend.refusedAmbiguous": "Non renvoyé : état amont inconnu",
+  "logs.detail.resend.refusedCommitted": "Non renvoyé : l'appelant a déjà vu la sortie",
+  "logs.detail.resend.refusedFutile": "Non renvoyé : la même requête échouerait encore",
   "logs.detail.reason.usage_missing": "L’utilisation n’a pas été communiquée.",
   "logs.detail.reason.usage_unsupported": "Ce fournisseur ne communique pas l’utilisation.",
   "logs.detail.reason.output_missing": "Aucun nombre positif de jetons de sortie n’a été communiqué.",
@@ -1000,6 +1043,82 @@ export const fr: Record<TKey, string> = {
   "usage.section.models": "Modèles",
   "usage.section.providers": "Fournisseurs",
   "usage.section.coverage": "Répartition de la couverture",
+  "usage.section.companion": "Barre des menus et widget",
+  "usage.companion.title": "Barre des menus et widget",
+  "usage.companion.description": "Ces réglages pilotent l’application OpenCodex de bureau/barre des menus et son widget.",
+  "usage.companion.installGuide": "Guide d’installation",
+  "usage.companion.loading": "Chargement de la chronologie…",
+  "usage.companion.timelineUnavailable": "Chronologie indisponible",
+  "usage.companion.empty": "Aucune utilisation au cours des {hours} dernières heures",
+  "usage.companion.chartLabel": "Chronologie de l’utilisation",
+  "usage.companion.olderRecordsSkipped": "Les enregistrements plus anciens ont été ignorés",
+  "usage.companion.settingsUnavailable": "Réglages du compagnon indisponibles",
+  "usage.companion.corrupt": "Le fichier de réglages du compagnon est corrompu. Les contrôles affichent les valeurs par défaut ; l’enregistrement est suspendu jusqu’au remplacement du fichier.",
+  "usage.companion.corruptReset": "Remplacer par les valeurs par défaut",
+  "usage.companion.saved": "Enregistré · {time}",
+  "usage.companion.saveFailed": "Échec de l’enregistrement : {error}",
+  "usage.companion.reset": "Rétablir les valeurs par défaut",
+  "usage.companion.footer": "Le widget affiche les requêtes, les jetons et le coût du jour, ainsi que le graphique configuré ici, et s’actualise quand l’app interroge le proxy.",
+  "usage.companion.menuBarShows": "La barre des menus affiche",
+  "usage.companion.menuRequests": "Requêtes",
+  "usage.companion.menuTokens": "Jetons",
+  "usage.companion.menuCost": "Coût",
+  "usage.companion.menuQuota": "Limite",
+  "usage.companion.menuNone": "Icône uniquement",
+  "usage.companion.window": "Période",
+  "usage.companion.window6": "6 h",
+  "usage.companion.window24": "24 h",
+  "usage.companion.window72": "3 j",
+  "usage.companion.window168": "7 j",
+  "usage.companion.style": "Présentation",
+  "usage.companion.styleLine": "Courbe",
+  "usage.companion.styleStacked": "Empilé",
+  "usage.companion.metric": "Métrique",
+  "usage.companion.metricTotal": "Total général",
+  "usage.companion.metricInput": "Entrée",
+  "usage.companion.metricOutput": "Sortie",
+  "usage.companion.metricCached": "En cache",
+  "usage.companion.groupBy": "Regrouper par",
+  "usage.companion.groupModel": "Modèle",
+  "usage.companion.groupAccount": "Modèle + compte",
+  "usage.companion.popoverSections": "Sections du panneau",
+  "usage.companion.sectionToday": "Aujourd’hui",
+  "usage.companion.sectionChart": "Graphique",
+  "usage.companion.sectionModels": "Modèles",
+  "usage.companion.sectionCost": "Coût",
+  "usage.companion.sectionAccounts": "Comptes",
+  "usage.companion.advanced": "Avancé",
+  "usage.companion.aggregation": "Agrégation",
+  "usage.companion.aggregationSum": "Somme",
+  "usage.companion.aggregationAverage": "Moyenne",
+  "usage.companion.aggregationMax": "Maximum",
+  "usage.companion.menuText": "Texte de la barre des menus",
+  "usage.companion.placeholders": "Paramètres substituables :",
+  "usage.companion.modelsOnChart": "Modèles du graphique",
+  "usage.companion.connected": "App de barre des menus connectée · {age}",
+  "usage.companion.connectedDesktop": "Application de bureau connectée · {age}",
+  "usage.companion.installTitle": "Installer l’application de bureau",
+  "usage.companion.installOs": "Système d’exploitation",
+  "usage.companion.osMac": "Mac",
+  "usage.companion.osWindows": "Système Windows",
+  "usage.companion.osLinux": "Système Linux",
+  "usage.companion.runningInDesktop": "Vous êtes dans l’application de bureau OpenCodex {version}",
+  "usage.companion.openInBrowser": "Ouvrir dans le navigateur",
+  "usage.companion.installMacStep1": "Téléchargez OpenCodex-<version>-macos.dmg depuis la dernière version et faites glisser OpenCodex.app dans Applications.",
+  "usage.companion.installMacStep2": "Premier lancement : faites un clic droit sur OpenCodex.app → Ouvrir (Gatekeeper demande une confirmation jusqu’à la notarisation).",
+  "usage.companion.installMacStep3": "L’application trouve ce proxy automatiquement ; le widget apparaît dans la galerie après son lancement.",
+  "usage.companion.installWinStep1": "Téléchargez OpenCodex-<version>-windows-x64.msi depuis la dernière version et exécutez-le.",
+  "usage.companion.installWinStep2": "Si SmartScreen vous avertit, choisissez Informations supplémentaires → Exécuter quand même (l’installateur n’est pas encore signé).",
+  "usage.companion.installWinStep3": "OpenCodex apparaît dans la zone de notification et se connecte à ce proxy, ou démarre celui fourni.",
+  "usage.companion.installLinuxStep1": "Téléchargez OpenCodex-<version>-linux-x86_64.AppImage (ou le .deb) depuis la dernière version.",
+  "usage.companion.installLinuxStep2": "Exécutez chmod +x sur l’AppImage puis lancez-le ; une icône de zone de notification nécessite un bureau compatible AppIndicator.",
+  "usage.companion.installLinuxStep3": "L’application se connecte à ce proxy ou démarre celui fourni.",
+  "usage.companion.notConnected": "Aucune app de barre des menus ne s’est encore connectée à ce proxy.",
+  "usage.companion.lastSeen": "Dernière connexion {age}",
+  "usage.companion.installAnother": "Installer sur un autre appareil",
+  "usage.companion.modelsCount": "{selected} sur {total} dans le graphique",
+  "usage.companion.modelsShowAll": "Tout afficher",
+  "usage.companion.hideProviders": "Masquer les fournisseurs",
   "usage.workspace.report": "Rapport d’utilisation",
   "usage.workspace.sections": "Sections d’utilisation",
   "usage.coverage.measured": "Mesurée",
@@ -1010,6 +1129,14 @@ export const fr: Record<TKey, string> = {
   "usage.col.requests": "Requêtes",
   "usage.col.measured": "Mesurées",
   "usage.col.reported": "Communiquées",
+  "usage.col.inputTokens": "Jetons d’entrée",
+  "usage.col.outputTokens": "Jetons de sortie",
+  "usage.col.cacheHits": "Lectures du cache",
+  "usage.col.cacheWrites": "Écritures dans le cache",
+  "usage.col.cacheHitRate": "Taux de succès du cache",
+  "usage.cacheHitRate.partial": "Moyenne calculée sur {measured} des {total} jetons d’entrée ; les autres requêtes n’ont fourni aucun détail sur le cache.",
+  "usage.cacheHitRate.unmeasured": "Aucune requête de cette ligne n’a fourni de détails sur le cache ; il n’y a donc pas de taux de succès moyen à calculer.",
+  "usage.unavailable": "—",
   "usage.col.tokens": "Jetons",
   "usage.col.apiListPrice": "Tarif catalogue API",
   "usage.col.share": "Part",
@@ -1829,6 +1956,7 @@ export const fr: Record<TKey, string> = {
   "integrations.status.installed": "Installé",
   "integrations.status.notInstalled": "Non installé",
   "integrations.status.appliedAt": "Appliqué",
+  "integrations.status.supersededStore": "Ce client lit désormais ses fournisseurs depuis {path}, un fichier qu'opencodex n'écrit pas : l'activer ici ne changerait rien à ce qu'il charge.",
   "integrations.status.backup": "Sauvegarde",
   "integrations.status.lastRestore": "Dernière restauration",
   "integrations.status.unknown": "Inconnu",
@@ -1889,6 +2017,7 @@ export const fr: Record<TKey, string> = {
   "integrations.plan.refusal.conflict": "Les paramètres gérés sont en conflit avec le fichier actuel. Vérifiez le fichier ou utilisez Remplacer si cette action est disponible.",
   "integrations.plan.refusal.unsafe": "La configuration du client ne peut pas être modifiée en toute sécurité. Réparez ou remplacez le fichier avant de réessayer.",
   "integrations.plan.refusal.nonLoopback": "Ce client exige une adresse proxy en boucle locale. Utilisez localhost, un tunnel ou un transfert local avant de réessayer.",
+  "integrations.plan.refusal.supersededStore": "Ce client lit ses fournisseurs depuis un fichier qu'opencodex n'écrit pas : cette opération ne changerait rien à ce qu'il charge.",
   "integrations.plan.refusal.driftRequiresConfirm": "Le fichier a changé après ce point de restauration. Vérifiez le plan tenant compte des changements avant de restaurer.",
   "integrations.plan.refusal.snapshotExpired": "La sauvegarde de ce point de restauration a expiré et ne peut plus être restaurée.",
   "integrations.plan.refusal.writeFailed": "Le serveur n’a pas pu préparer une écriture sûre. Actualisez l’état de l’intégration avant de réessayer.",
@@ -2093,6 +2222,7 @@ export const fr: Record<TKey, string> = {
   "accountPool.priorityUpdateFailed": "Impossible d’enregistrer l’ordre de sélection de {email}. La dernière valeur confirmée est affichée.",
   "codexAuth.switched": "{email} est sélectionné pour la prochaine requête",
   "codexAuth.loadFailed": "Impossible de charger les paramètres des comptes Codex.",
+  "codexAuth.accountsRefreshFailed": "La dernière actualisation des comptes a échoué. Les comptes ci-dessous sont les derniers confirmés.",
   "codexAuth.switchFailed": "Impossible de changer de compte. Votre sélection précédente reste inchangée.",
   "codexAuth.removeConfirm": "Supprimer {id} ?",
   "codexAuth.removeFailed": "Impossible de supprimer le compte. Aucune modification apportée.",
@@ -2633,6 +2763,19 @@ export const fr: Record<TKey, string> = {
   "claudeDesktop.status.notActiveProfile": "Desktop utilise un autre profil — appliquer de nouveau",
   "claudeDesktop.status.disabled": "L’intégration Claude Desktop est désactivée. Quittez complètement Desktop et rouvrez-le après l’avoir activée.",
   "claudeDesktop.enableApply": "Activer et appliquer",
+  "claudeDesktop.switchModeApply": "Changer de mode et appliquer",
+  "claudeDesktop.status.appliedFirstParty": "Première partie : l'onglet Code passe par le proxy local",
+  "claudeDesktop.mode.legend": "Mode de connexion",
+  "claudeDesktop.mode.firstParty": "Première partie (first-party)",
+  "claudeDesktop.mode.gateway": "Passerelle (tiers)",
+  "claudeDesktop.mode.defaultBadge": "par défaut",
+  "claudeDesktop.mode.current": "actuel",
+  "claudeDesktop.mode.firstPartyHint": "Desktop reste connecté à claude.ai (chat, connecteurs, contrôle à distance). Seuls l'onglet Code, ses sous-agents et la CLI Claude Code passent par OpenCodex.",
+  "claudeDesktop.mode.gatewayHint": "Toute l'application bascule sur OpenCodex comme passerelle. Le chat tourne en local ; les fonctions claude.ai sont indisponibles.",
+  "claudeDesktop.mode.switchNote": "Le changement remplace la configuration de l'autre mode. Quittez complètement Desktop puis rouvrez-le.",
+  "claudeDesktop.firstParty.proxyRunning": "Proxy local sur 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "Le proxy local 127.0.0.1:{port} ne tourne pas — redémarrez OpenCodex",
+  "claudeDesktop.firstParty.interceptDisabled": "Le proxy d'interception est désactivé dans la config (claudeCode.intercept.enabled)",
   "claudeDesktop.health.lastRequest": "Dernière requête",
   "claudeDesktop.health.stats": "{count} req. / {errors} err.",
   "claudeDesktop.effort.supported": "effort",
diff --git a/gui/src/i18n/ja.ts b/gui/src/i18n/ja.ts
index 64a68f59419..e748ce03290 100644
--- a/gui/src/i18n/ja.ts
+++ b/gui/src/i18n/ja.ts
@@ -331,6 +331,8 @@ export const ja: Record<TKey, string> = {
   "dash.stop": "プロキシを停止",
   "dash.stopConfirm": "プロキシを停止してネイティブの Codex に戻しますか?",
   "dash.stopFailed": "プロキシを停止できませんでした (HTTP {status})。",
+  "dash.stopStillRunning": "プロキシはまだ応答しています。停止していません。",
+  "dash.stopUnknown": "停止できたか確認できませんでした。再試行する前にプロキシが動作中か確認してください。",
   "dash.maSwitchFailed": "モードの切り替えに失敗しました (HTTP {status})。",
   "dash.maNetworkError": "ネットワークエラー — プロキシは起動していますか?",
   "dash.stopping": "停止中…",
@@ -375,7 +377,7 @@ export const ja: Record<TKey, string> = {
   "compactionRouting.dataNotice": "適用対象の圧縮リクエストは、会話が別のプロバイダーで動いていても、会話全体を選択したモデルのプロバイダーへ送信して要約します。",
   "compactionRouting.autoNotice": "自動圧縮はユーザーが求めなくても実行されるため、長い会話が知らないうちにそのプロバイダーへ送信されることがあります。",
   "compactionRouting.providerWarning": "この設定では、適用対象の圧縮リクエストのたびに会話の全内容が要約のために {provider} へ送信されます。",
-  "compactionRouting.comboWarning": "この設定では、適用対象の圧縮リクエストのたびに会話の全内容が、フェイルオーバー先を含むコンボ {combo} のすべてのターゲット（{providers}）へ要約のために送信されます。",
+  "compactionRouting.comboWarning": "この設定では、適用対象の圧縮リクエストのたびに会話の全内容が要約のためコンボ {combo} へ送信されます。コンボはターゲット（{providers}）を順に試し、最初に応答したものを使うため、そのいずれもが会話を受け取る可能性があります。",
   "compactionRouting.comboProvidersUnknown": "設定済みのターゲットプロバイダー",
   "compactionRouting.loadFailed": "圧縮設定を読み込めませんでした。",
   "compactionRouting.saved": "圧縮設定を保存しました。",
@@ -834,7 +836,47 @@ export const ja: Record<TKey, string> = {
   "logs.detail.attempt.recovery.image413": "画像ペイロードが大きすぎます (413)",
   "logs.detail.attempt.recovery.emptyCompletion": "空の完了を再試行",
   "logs.detail.attempt.recovery.consoleGoUpload": "Console アップロード再試行",
+  "logs.detail.attempt.recovery.key401": "API キーの再認証",
+  "logs.detail.attempt.recovery.oauthAccount429": "アカウントのレート制限 (429)",
+  "logs.detail.attempt.recovery.opaqueBlobRejection": "古い暗号化状態を破棄",
+  "logs.detail.attempt.recovery.reasoningEffortDowngrade": "推論強度を下げて再試行",
+  "logs.detail.outcome.label": "結果",
+  "logs.detail.outcome.completed": "完了",
+  "logs.detail.outcome.failed": "失敗",
+  "logs.detail.outcome.incomplete": "未完了",
+  "logs.detail.outcome.aborted": "中断",
+  "logs.detail.sends.label": "アップストリーム送信",
+  "logs.detail.sends.unresolved": "未確定",
   "logs.detail.attempt.recovery.unknown": "不明なリカバリ理由",
+  "logs.detail.cause.label": "失敗の原因",
+  "logs.detail.stage.label": "到達段階",
+  "logs.detail.resend.label": "再送",
+  "logs.detail.cause.transportUnsent": "アップストリームへ未送信",
+  "logs.detail.cause.transportAmbiguous": "接続が切れ、処理状況は不明",
+  "logs.detail.cause.upstreamDeclined": "アップストリームが開始を拒否",
+  "logs.detail.cause.rateLimit": "レート制限",
+  "logs.detail.cause.quotaExhausted": "クォータ枯渇",
+  "logs.detail.cause.credentialRejected": "認証情報が拒否されました",
+  "logs.detail.cause.policyRefusal": "コンテンツポリシーによる拒否",
+  "logs.detail.cause.parameterRejected": "リクエストパラメータが拒否されました",
+  "logs.detail.cause.ciphertextRefusal": "暗号化状態が拒否されました",
+  "logs.detail.cause.payloadTooLarge": "ペイロードが大きすぎます",
+  "logs.detail.cause.payloadRejected": "ペイロードが拒否されました",
+  "logs.detail.cause.upstreamFault": "アップストリーム障害",
+  "logs.detail.cause.emptyOutput": "利用可能な出力なし",
+  "logs.detail.cause.clientCancelled": "クライアントがキャンセル",
+  "logs.detail.cause.localRefusal": "このプロキシが拒否",
+  "logs.detail.stage.preHeader": "レスポンスヘッダーなし",
+  "logs.detail.stage.headersOnly": "ヘッダーのみ",
+  "logs.detail.stage.protocolPrelude": "プロトコル前段",
+  "logs.detail.stage.semanticOutput": "出力を配信済み",
+  "logs.detail.stage.sideEffect": "副作用が発生",
+  "logs.detail.stage.terminal": "応答を配信済み",
+  "logs.detail.resend.permitted": "再送可能",
+  "logs.detail.resend.permittedAfterRepair": "修正後に再送可能",
+  "logs.detail.resend.refusedAmbiguous": "再送なし: アップストリームの状態が不明",
+  "logs.detail.resend.refusedCommitted": "再送なし: 呼び出し元が既に出力を受信",
+  "logs.detail.resend.refusedFutile": "再送なし: 同じ要求は再び失敗します",
   "logs.detail.reason.usage_missing": "使用量が報告されませんでした。",
   "logs.detail.reason.usage_unsupported": "このプロバイダーは使用量を報告しません。",
   "logs.detail.reason.output_missing": "正の出力トークン数が報告されませんでした。",
@@ -935,6 +977,82 @@ export const ja: Record<TKey, string> = {
   "usage.section.models": "モデル",
   "usage.section.providers": "プロバイダー",
   "usage.section.coverage": "カバレッジ内訳",
+  "usage.section.companion": "メニューバーとウィジェット",
+  "usage.companion.title": "メニューバーとウィジェット",
+  "usage.companion.description": "ここでの設定は OpenCodex デスクトップ／メニューバーアプリとウィジェットを制御します。",
+  "usage.companion.installGuide": "インストールガイド",
+  "usage.companion.loading": "タイムラインを読み込み中…",
+  "usage.companion.timelineUnavailable": "タイムラインを利用できません",
+  "usage.companion.empty": "過去 {hours} 時間に利用はありません",
+  "usage.companion.chartLabel": "使用量タイムライン",
+  "usage.companion.olderRecordsSkipped": "古い記録はスキップされました",
+  "usage.companion.settingsUnavailable": "コンパニオン設定を利用できません",
+  "usage.companion.corrupt": "コンパニオン設定ファイルが破損しています。コントロールにはデフォルト値が表示され、ファイルを置き換えるまで保存は一時停止されます。",
+  "usage.companion.corruptReset": "デフォルト値に置き換える",
+  "usage.companion.saved": "保存済み · {time}",
+  "usage.companion.saveFailed": "保存できませんでした: {error}",
+  "usage.companion.reset": "既定値に戻す",
+  "usage.companion.footer": "ウィジェットには今日のリクエスト数、トークン数、コストと、ここで設定したグラフが表示され、アプリのポーリング時に更新されます。",
+  "usage.companion.menuBarShows": "メニューバーに表示",
+  "usage.companion.menuRequests": "リクエスト",
+  "usage.companion.menuTokens": "トークン",
+  "usage.companion.menuCost": "コスト",
+  "usage.companion.menuQuota": "クォータ",
+  "usage.companion.menuNone": "アイコンのみ",
+  "usage.companion.window": "期間",
+  "usage.companion.window6": "6時間",
+  "usage.companion.window24": "24時間",
+  "usage.companion.window72": "3日",
+  "usage.companion.window168": "7日",
+  "usage.companion.style": "スタイル",
+  "usage.companion.styleLine": "線",
+  "usage.companion.styleStacked": "積み上げ",
+  "usage.companion.metric": "指標",
+  "usage.companion.metricTotal": "合計",
+  "usage.companion.metricInput": "入力",
+  "usage.companion.metricOutput": "出力",
+  "usage.companion.metricCached": "キャッシュ済み",
+  "usage.companion.groupBy": "グループ化",
+  "usage.companion.groupModel": "モデル",
+  "usage.companion.groupAccount": "モデル + アカウント",
+  "usage.companion.popoverSections": "ポップオーバーのセクション",
+  "usage.companion.sectionToday": "今日",
+  "usage.companion.sectionChart": "グラフ",
+  "usage.companion.sectionModels": "モデル",
+  "usage.companion.sectionCost": "コスト",
+  "usage.companion.sectionAccounts": "アカウント",
+  "usage.companion.advanced": "詳細設定",
+  "usage.companion.aggregation": "集計",
+  "usage.companion.aggregationSum": "合計",
+  "usage.companion.aggregationAverage": "平均",
+  "usage.companion.aggregationMax": "最大",
+  "usage.companion.menuText": "メニューバーのテキスト",
+  "usage.companion.placeholders": "プレースホルダー:",
+  "usage.companion.modelsOnChart": "グラフのモデル",
+  "usage.companion.connected": "メニューバーアプリ接続済み · {age}",
+  "usage.companion.connectedDesktop": "デスクトップアプリ接続済み · {age}",
+  "usage.companion.installTitle": "デスクトップアプリをインストール",
+  "usage.companion.installOs": "オペレーティングシステム",
+  "usage.companion.osMac": "macOS",
+  "usage.companion.osWindows": "Windows",
+  "usage.companion.osLinux": "Linux",
+  "usage.companion.runningInDesktop": "OpenCodex デスクトップアプリ {version} を使用中です",
+  "usage.companion.openInBrowser": "ブラウザで開く",
+  "usage.companion.installMacStep1": "最新リリースから OpenCodex-<version>-macos.dmg をダウンロードし、OpenCodex.app をアプリケーションへ移動します。",
+  "usage.companion.installMacStep2": "初回起動：OpenCodex.app を右クリックして「開く」を選択します（公証されるまで Gatekeeper が一度確認します）。",
+  "usage.companion.installMacStep3": "アプリはこのプロキシを自動検出します。アプリを起動するとウィジェットギャラリーに表示されます。",
+  "usage.companion.installWinStep1": "最新リリースから OpenCodex-<version>-windows-x64.msi をダウンロードして実行します。",
+  "usage.companion.installWinStep2": "SmartScreen が警告したら「詳細情報」→「実行」を選択します（インストーラーはまだコード署名されていません）。",
+  "usage.companion.installWinStep3": "OpenCodex はシステムトレイに表示され、このプロキシに接続するか、同梱のプロキシを起動します。",
+  "usage.companion.installLinuxStep1": "最新リリースから OpenCodex-<version>-linux-x86_64.AppImage（または .deb）をダウンロードします。",
+  "usage.companion.installLinuxStep2": "AppImage に chmod +x を実行して起動します。トレイアイコンには AppIndicator 対応デスクトップが必要です。",
+  "usage.companion.installLinuxStep3": "アプリはこのプロキシに接続するか、同梱のプロキシを起動します。",
+  "usage.companion.notConnected": "このプロキシに接続したメニューバーアプリはまだありません。",
+  "usage.companion.lastSeen": "最終接続 {age}",
+  "usage.companion.installAnother": "別のデバイスにインストール",
+  "usage.companion.modelsCount": "{selected} / {total} がグラフに表示中",
+  "usage.companion.modelsShowAll": "すべて表示",
+  "usage.companion.hideProviders": "プロバイダーを非表示",
   "usage.workspace.report": "使用量レポート",
   "usage.workspace.sections": "使用量セクション",
   "usage.coverage.measured": "計測",
@@ -945,6 +1063,14 @@ export const ja: Record<TKey, string> = {
   "usage.col.requests": "リクエスト",
   "usage.col.measured": "計測",
   "usage.col.reported": "報告",
+  "usage.col.inputTokens": "入力トークン",
+  "usage.col.outputTokens": "出力トークン",
+  "usage.col.cacheHits": "キャッシュヒット",
+  "usage.col.cacheWrites": "キャッシュ書き込み",
+  "usage.col.cacheHitRate": "ヒット率",
+  "usage.cacheHitRate.partial": "入力トークン全体 {total} のうち {measured} を対象に平均しています。残りのリクエストではキャッシュの詳細が報告されていません。",
+  "usage.cacheHitRate.unmeasured": "この行のリクエストはいずれもキャッシュの詳細を報告していないため、平均ヒット率はありません。",
+  "usage.unavailable": "—",
   "usage.col.tokens": "トークン",
   "usage.col.apiListPrice": "API 定価",
   "usage.col.share": "割合",
@@ -1753,6 +1879,7 @@ export const ja: Record<TKey, string> = {
   "integrations.status.installed": "インストール済み",
   "integrations.status.notInstalled": "未インストール",
   "integrations.status.appliedAt": "適用",
+  "integrations.status.supersededStore": "このクライアントは現在 {path} からプロバイダーを読み込みます。opencodex はこのファイルを書き込まないため、ここで有効にしても読み込む内容は変わりません。",
   "integrations.status.backup": "バックアップ",
   "integrations.status.lastRestore": "最終復元",
   "integrations.status.unknown": "不明",
@@ -1813,6 +1940,7 @@ export const ja: Record<TKey, string> = {
   "integrations.plan.refusal.conflict": "管理対象の設定が現在のファイルと競合しています。ファイルを確認するか、利用可能な場合は置き換えを使用してください。",
   "integrations.plan.refusal.unsafe": "クライアント設定を安全に変更できません。ファイルを修復または置き換えてから再試行してください。",
   "integrations.plan.refusal.nonLoopback": "このクライアントにはループバックのプロキシアドレスが必要です。localhost、トンネル、またはローカル転送を使用してください。",
+  "integrations.plan.refusal.supersededStore": "このクライアントは opencodex が書き込まないファイルからプロバイダーを読み込むため、この操作では読み込む内容は変わりません。",
   "integrations.plan.refusal.driftRequiresConfirm": "このロールバック地点以降にファイルが変更されました。変更を考慮したプランを確認してから復元してください。",
   "integrations.plan.refusal.snapshotExpired": "このロールバック地点のバックアップは期限切れのため、復元できません。",
   "integrations.plan.refusal.writeFailed": "サーバーは安全な書き込みを準備できませんでした。統合状態を更新してから再試行してください。",
@@ -2021,6 +2149,7 @@ export const ja: Record<TKey, string> = {
   "accountPool.priorityUpdateFailed": "{email} の選択順序を保存できませんでした。最後に確認された値を表示しています。",
   "codexAuth.switched": "次のリクエストでは {email} を使用します",
   "codexAuth.loadFailed": "Codex アカウント設定を読み込めませんでした。",
+  "codexAuth.accountsRefreshFailed": "最新のアカウント更新に失敗しました。以下は最後に確認されたアカウントです。",
   "codexAuth.switchFailed": "アカウントを切り替えられませんでした。以前の選択はそのままです。",
   "codexAuth.removeConfirm": "{id} を削除しますか?",
   "codexAuth.removeFailed": "アカウントを削除できませんでした。何も変更されていません。",
@@ -2438,6 +2567,19 @@ export const ja: Record<TKey, string> = {
   "claudeDesktop.status.notActiveProfile": "Desktop は別のプロファイルを使用中 — 再適用してください",
   "claudeDesktop.status.disabled": "Claude Desktop 連携はオフです。有効にした後、Desktop を完全に終了して再起動してください。",
   "claudeDesktop.enableApply": "有効にして適用",
+  "claudeDesktop.switchModeApply": "モードを切り替えて適用",
+  "claudeDesktop.status.appliedFirstParty": "1P: Code タブはローカルプロキシ経由",
+  "claudeDesktop.mode.legend": "接続モード",
+  "claudeDesktop.mode.firstParty": "1P（ファーストパーティ）",
+  "claudeDesktop.mode.gateway": "ゲートウェイ（3P）",
+  "claudeDesktop.mode.defaultBadge": "デフォルト",
+  "claudeDesktop.mode.current": "現在",
+  "claudeDesktop.mode.firstPartyHint": "Desktop は claude.ai にログインしたまま（チャット・コネクタ・リモート操作）。Code タブとそのサブエージェント、Claude Code CLI だけが OpenCodex を通ります。",
+  "claudeDesktop.mode.gatewayHint": "アプリ全体が OpenCodex をゲートウェイとして使います。チャットはローカル実行になり、claude.ai の機能は使えません。",
+  "claudeDesktop.mode.switchNote": "切り替えると他方のモードの設定は削除されます。適用後は Desktop を完全に終了して再起動してください。",
+  "claudeDesktop.firstParty.proxyRunning": "ローカルプロキシ 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "ローカルプロキシ 127.0.0.1:{port} が停止中 — OpenCodex を再起動",
+  "claudeDesktop.firstParty.interceptDisabled": "設定でインターセプトプロキシが無効です（claudeCode.intercept.enabled）",
   "claudeDesktop.health.lastRequest": "最終リクエスト",
   "claudeDesktop.health.stats": "{count} リクエスト / {errors} エラー",
   "claudeDesktop.effort.supported": "effort",
@@ -2574,6 +2716,7 @@ export const ja: Record<TKey, string> = {
   "prov.aliasPrompt": "Display name (leave empty to clear)",
   "prov.aliasSaved": "Alias saved",
   "prov.aliasSaveFailed": "Could not save alias",
+  "prov.aliasInvalid": "制御文字を含めず、80文字以内で入力してください。",
   "prov.accountId": "ID",
   "models.customAdd": "Add custom model",
   "models.customAddTitle": "Add custom model — {provider}",
diff --git a/gui/src/i18n/ko.ts b/gui/src/i18n/ko.ts
index d5a4a9392c5..d40f976c87c 100644
--- a/gui/src/i18n/ko.ts
+++ b/gui/src/i18n/ko.ts
@@ -326,6 +326,8 @@ export const ko: Record<TKey, string> = {
   "dash.stop": "프록시 중지",
   "dash.stopConfirm": "프록시를 중지하고 Codex 원본 설정을 복원할까요?",
   "dash.stopFailed": "프록시를 중지하지 못했습니다 (HTTP {status}).",
+  "dash.stopStillRunning": "프록시가 아직 응답하고 있습니다. 중지되지 않았습니다.",
+  "dash.stopUnknown": "중지 여부를 확인하지 못했습니다. 다시 시도하기 전에 프록시가 실행 중인지 확인하세요.",
   "dash.maSwitchFailed": "모드 전환에 실패했습니다 (HTTP {status}).",
   "dash.maNetworkError": "네트워크 오류 — 프록시가 실행 중인지 확인하세요.",
   "dash.stopping": "중지 중…",
@@ -370,7 +372,7 @@ export const ko: Record<TKey, string> = {
   "compactionRouting.dataNotice": "적용 대상 압축 요청은 대화가 다른 프로바이더에서 실행 중이더라도 전체 대화를 선택한 모델의 프로바이더로 보내 요약합니다.",
   "compactionRouting.autoNotice": "자동 압축은 사용자가 요청하지 않아도 실행되므로, 긴 대화가 예고 없이 해당 프로바이더로 전송될 수 있습니다.",
   "compactionRouting.providerWarning": "이 설정을 사용하면 적용 대상 압축 요청마다 전체 대화 내용이 요약을 위해 {provider}로 전송됩니다.",
-  "compactionRouting.comboWarning": "이 설정을 사용하면 적용 대상 압축 요청마다 전체 대화 내용이 장애 조치 대상을 포함한 콤보 {combo}의 모든 대상({providers})으로 요약을 위해 전송됩니다.",
+  "compactionRouting.comboWarning": "이 설정을 사용하면 적용 대상 압축 요청마다 전체 대화 내용이 요약을 위해 콤보 {combo}로 전송됩니다. 콤보는 대상({providers})을 순서대로 시도해 먼저 응답한 하나를 사용하므로, 그중 어느 것이든 대화를 받을 수 있습니다.",
   "compactionRouting.comboProvidersUnknown": "구성된 대상 프로바이더",
   "compactionRouting.loadFailed": "압축 설정을 불러올 수 없습니다.",
   "compactionRouting.saved": "압축 설정을 저장했습니다.",
@@ -470,6 +472,7 @@ export const ko: Record<TKey, string> = {
   "prov.aliasPrompt": "표시 이름 (비우면 삭제)",
   "prov.aliasSaved": "별칭이 저장되었습니다",
   "prov.aliasSaveFailed": "별칭을 저장하지 못했습니다",
+  "prov.aliasInvalid": "제어 문자 없이 80자 이내로 입력하세요.",
   "prov.accountId": "ID",
   "prov.pasteRedirect": "리다이렉트 URL 또는 코드 붙여넣기",
   "prov.pasteRedirectHint": "브라우저에 localhost 오류가 표시되면, 주소창의 전체 URL을 복사해 여기에 붙여넣으세요(또는 인증 코드 붙여넣기).",
@@ -904,7 +907,47 @@ export const ko: Record<TKey, string> = {
   "logs.detail.attempt.recovery.image413": "이미지 페이로드가 너무 큼 (413)",
   "logs.detail.attempt.recovery.emptyCompletion": "빈 응답 재시도",
   "logs.detail.attempt.recovery.consoleGoUpload": "Console 업로드 재시도",
+  "logs.detail.attempt.recovery.key401": "API 키 재인증",
+  "logs.detail.attempt.recovery.oauthAccount429": "계정 속도 제한 (429)",
+  "logs.detail.attempt.recovery.opaqueBlobRejection": "만료된 암호화 상태 제거",
+  "logs.detail.attempt.recovery.reasoningEffortDowngrade": "추론 강도 하향",
+  "logs.detail.outcome.label": "결과",
+  "logs.detail.outcome.completed": "완료",
+  "logs.detail.outcome.failed": "실패",
+  "logs.detail.outcome.incomplete": "미완료",
+  "logs.detail.outcome.aborted": "중단됨",
+  "logs.detail.sends.label": "업스트림 전송",
+  "logs.detail.sends.unresolved": "미확인",
   "logs.detail.attempt.recovery.unknown": "알 수 없는 복구 사유",
+  "logs.detail.cause.label": "실패 원인",
+  "logs.detail.stage.label": "도달 지점",
+  "logs.detail.resend.label": "재전송",
+  "logs.detail.cause.transportUnsent": "업스트림으로 전송되지 않음",
+  "logs.detail.cause.transportAmbiguous": "연결이 끊겨 업스트림 처리 여부 불명",
+  "logs.detail.cause.upstreamDeclined": "업스트림이 시작을 거부함",
+  "logs.detail.cause.rateLimit": "요청 한도 초과",
+  "logs.detail.cause.quotaExhausted": "할당량 소진",
+  "logs.detail.cause.credentialRejected": "자격 증명 거부됨",
+  "logs.detail.cause.policyRefusal": "콘텐츠 정책으로 거부됨",
+  "logs.detail.cause.parameterRejected": "요청 파라미터 거부됨",
+  "logs.detail.cause.ciphertextRefusal": "암호화된 상태 거부됨",
+  "logs.detail.cause.payloadTooLarge": "페이로드가 너무 큼",
+  "logs.detail.cause.payloadRejected": "페이로드 거부됨",
+  "logs.detail.cause.upstreamFault": "업스트림 장애",
+  "logs.detail.cause.emptyOutput": "사용할 수 있는 출력 없음",
+  "logs.detail.cause.clientCancelled": "클라이언트가 취소함",
+  "logs.detail.cause.localRefusal": "이 프록시가 거부함",
+  "logs.detail.stage.preHeader": "응답 헤더 없음",
+  "logs.detail.stage.headersOnly": "헤더까지",
+  "logs.detail.stage.protocolPrelude": "프로토콜 프리앰블",
+  "logs.detail.stage.semanticOutput": "출력 전달됨",
+  "logs.detail.stage.sideEffect": "부수 효과 발생",
+  "logs.detail.stage.terminal": "응답 전달 완료",
+  "logs.detail.resend.permitted": "재전송 가능",
+  "logs.detail.resend.permittedAfterRepair": "수정 후 재전송 가능",
+  "logs.detail.resend.refusedAmbiguous": "재전송 안 함: 업스트림 처리 여부 불명",
+  "logs.detail.resend.refusedCommitted": "재전송 안 함: 이미 출력이 전달됨",
+  "logs.detail.resend.refusedFutile": "재전송 안 함: 같은 요청은 다시 실패함",
   "logs.detail.reason.usage_missing": "usage가 보고되지 않았습니다.",
   "logs.detail.reason.usage_unsupported": "이 프로바이더는 usage 보고를 지원하지 않습니다.",
   "logs.detail.reason.output_missing": "양수 출력 토큰 수가 보고되지 않았습니다.",
@@ -1004,6 +1047,82 @@ export const ko: Record<TKey, string> = {
   "usage.section.models": "모델",
   "usage.section.providers": "프로바이더",
   "usage.section.coverage": "커버리지 상세",
+  "usage.section.companion": "메뉴 막대 및 위젯",
+  "usage.companion.title": "메뉴 막대 및 위젯",
+  "usage.companion.description": "이 설정은 OpenCodex 데스크톱/메뉴 막대 앱과 위젯을 제어합니다.",
+  "usage.companion.installGuide": "설치 안내",
+  "usage.companion.loading": "타임라인 로드 중…",
+  "usage.companion.timelineUnavailable": "타임라인을 사용할 수 없습니다",
+  "usage.companion.empty": "지난 {hours}시간 동안 사용량이 없습니다",
+  "usage.companion.chartLabel": "사용량 타임라인",
+  "usage.companion.olderRecordsSkipped": "오래된 기록을 건너뛰었습니다",
+  "usage.companion.settingsUnavailable": "컴패니언 설정을 사용할 수 없습니다",
+  "usage.companion.corrupt": "컴패니언 설정 파일이 손상되었습니다. 컨트롤에는 기본값이 표시되며 파일을 교체할 때까지 저장이 일시 중지됩니다.",
+  "usage.companion.corruptReset": "기본값으로 교체",
+  "usage.companion.saved": "저장됨 · {time}",
+  "usage.companion.saveFailed": "저장하지 못했습니다: {error}",
+  "usage.companion.reset": "기본값으로 재설정",
+  "usage.companion.footer": "위젯에는 오늘의 요청, 토큰, 비용과 여기에서 구성한 차트가 표시되며 앱이 폴링할 때 새로 고쳐집니다.",
+  "usage.companion.menuBarShows": "메뉴 막대 표시",
+  "usage.companion.menuRequests": "요청",
+  "usage.companion.menuTokens": "토큰",
+  "usage.companion.menuCost": "비용",
+  "usage.companion.menuQuota": "할당량",
+  "usage.companion.menuNone": "아이콘만",
+  "usage.companion.window": "기간",
+  "usage.companion.window6": "6시간",
+  "usage.companion.window24": "24시간",
+  "usage.companion.window72": "3일",
+  "usage.companion.window168": "7일",
+  "usage.companion.style": "스타일",
+  "usage.companion.styleLine": "선",
+  "usage.companion.styleStacked": "누적",
+  "usage.companion.metric": "지표",
+  "usage.companion.metricTotal": "합계",
+  "usage.companion.metricInput": "입력",
+  "usage.companion.metricOutput": "출력",
+  "usage.companion.metricCached": "캐시됨",
+  "usage.companion.groupBy": "그룹 기준",
+  "usage.companion.groupModel": "모델",
+  "usage.companion.groupAccount": "모델 + 계정",
+  "usage.companion.popoverSections": "팝오버 섹션",
+  "usage.companion.sectionToday": "오늘",
+  "usage.companion.sectionChart": "차트",
+  "usage.companion.sectionModels": "모델",
+  "usage.companion.sectionCost": "비용",
+  "usage.companion.sectionAccounts": "계정",
+  "usage.companion.advanced": "고급",
+  "usage.companion.aggregation": "집계",
+  "usage.companion.aggregationSum": "합계",
+  "usage.companion.aggregationAverage": "평균",
+  "usage.companion.aggregationMax": "최대",
+  "usage.companion.menuText": "메뉴 막대 텍스트",
+  "usage.companion.placeholders": "자리표시자:",
+  "usage.companion.modelsOnChart": "차트의 모델",
+  "usage.companion.connected": "메뉴 막대 앱 연결됨 · {age}",
+  "usage.companion.connectedDesktop": "데스크톱 앱 연결됨 · {age}",
+  "usage.companion.installTitle": "데스크톱 앱 설치",
+  "usage.companion.installOs": "운영 체제",
+  "usage.companion.osMac": "macOS",
+  "usage.companion.osWindows": "Windows",
+  "usage.companion.osLinux": "Linux",
+  "usage.companion.runningInDesktop": "OpenCodex 데스크톱 앱 {version}에서 실행 중입니다",
+  "usage.companion.openInBrowser": "브라우저에서 열기",
+  "usage.companion.installMacStep1": "최신 릴리스에서 OpenCodex-<version>-macos.dmg를 다운로드하고 OpenCodex.app을 응용 프로그램으로 드래그하세요.",
+  "usage.companion.installMacStep2": "첫 실행: OpenCodex.app을 마우스 오른쪽 버튼으로 클릭하고 열기를 선택하세요(공증될 때까지 Gatekeeper가 한 번 확인합니다).",
+  "usage.companion.installMacStep3": "앱이 이 프록시를 자동으로 찾으며, 앱을 실행하면 위젯 갤러리에 위젯이 표시됩니다.",
+  "usage.companion.installWinStep1": "최신 릴리스에서 OpenCodex-<version>-windows-x64.msi를 다운로드하고 실행하세요.",
+  "usage.companion.installWinStep2": "SmartScreen 경고가 표시되면 추가 정보 → 실행을 선택하세요(설치 프로그램은 아직 코드 서명되지 않았습니다).",
+  "usage.companion.installWinStep3": "OpenCodex가 시스템 트레이에 나타나 이 프록시에 연결하거나 번들 프록시를 시작합니다.",
+  "usage.companion.installLinuxStep1": "최신 릴리스에서 OpenCodex-<version>-linux-x86_64.AppImage(또는 .deb)를 다운로드하세요.",
+  "usage.companion.installLinuxStep2": "AppImage에 chmod +x를 실행하고 시작하세요. 트레이 아이콘에는 AppIndicator를 지원하는 데스크톱이 필요합니다.",
+  "usage.companion.installLinuxStep3": "앱이 이 프록시에 연결하거나 번들 프록시를 시작합니다.",
+  "usage.companion.notConnected": "아직 이 프록시에 연결한 메뉴 막대 앱이 없습니다.",
+  "usage.companion.lastSeen": "마지막 연결 {age}",
+  "usage.companion.installAnother": "다른 기기에 설치",
+  "usage.companion.modelsCount": "{selected} / {total}개가 차트에 표시됨",
+  "usage.companion.modelsShowAll": "모두 표시",
+  "usage.companion.hideProviders": "공급자 숨기기",
   "usage.workspace.report": "사용량 보고서",
   "usage.workspace.sections": "사용량 섹션",
   "usage.coverage.measured": "측정됨",
@@ -1014,6 +1133,14 @@ export const ko: Record<TKey, string> = {
   "usage.col.requests": "요청",
   "usage.col.measured": "측정됨",
   "usage.col.reported": "측정됨",
+  "usage.col.inputTokens": "입력 토큰",
+  "usage.col.outputTokens": "출력 토큰",
+  "usage.col.cacheHits": "캐시 히트",
+  "usage.col.cacheWrites": "캐시 쓰기",
+  "usage.col.cacheHitRate": "히트율",
+  "usage.cacheHitRate.partial": "전체 입력 토큰 {total} 중 {measured}에 대해 계산한 평균입니다. 나머지 요청에는 캐시 세부 정보가 없습니다.",
+  "usage.cacheHitRate.unmeasured": "이 행의 요청에는 모두 캐시 세부 정보가 없어 평균 히트율을 계산할 수 없습니다.",
+  "usage.unavailable": "—",
   "usage.col.tokens": "토큰",
   "usage.col.apiListPrice": "API 정가",
   "usage.col.share": "비율",
@@ -1345,6 +1472,7 @@ export const ko: Record<TKey, string> = {
   "integrations.status.installed": "설치 감지됨",
   "integrations.status.notInstalled": "설치되지 않음",
   "integrations.status.appliedAt": "적용",
+  "integrations.status.supersededStore": "이 클라이언트는 이제 {path}에서 프로바이더를 읽습니다. opencodex는 이 파일을 쓰지 않으므로 여기서 켜도 클라이언트가 불러오는 내용은 달라지지 않습니다.",
   "integrations.status.backup": "백업",
   "integrations.status.lastRestore": "마지막 복원",
   "integrations.status.unknown": "알 수 없음",
@@ -1405,6 +1533,7 @@ export const ko: Record<TKey, string> = {
   "integrations.plan.refusal.conflict": "관리 설정이 현재 파일과 충돌합니다. 파일을 검토하거나 사용할 수 있다면 교체 작업을 선택하세요.",
   "integrations.plan.refusal.unsafe": "클라이언트 구성을 안전하게 변경할 수 없습니다. 파일을 복구하거나 교체한 뒤 다시 시도하세요.",
   "integrations.plan.refusal.nonLoopback": "이 클라이언트에는 루프백 프록시 주소가 필요합니다. localhost, 터널 또는 로컬 포워더를 사용한 뒤 다시 시도하세요.",
+  "integrations.plan.refusal.supersededStore": "이 클라이언트는 opencodex가 쓰지 않는 파일에서 프로바이더를 읽으므로, 이 작업으로는 클라이언트가 불러오는 내용이 달라지지 않습니다.",
   "integrations.plan.refusal.driftRequiresConfirm": "이 롤백 시점 이후 파일이 변경되었습니다. 변경 상태를 반영한 계획을 검토한 뒤 복원하세요.",
   "integrations.plan.refusal.snapshotExpired": "이 롤백 시점의 백업이 만료되어 더 이상 복원할 수 없습니다.",
   "integrations.plan.refusal.writeFailed": "서버가 안전한 쓰기 작업을 준비하지 못했습니다. 통합 상태를 새로 고친 뒤 다시 시도하세요.",
@@ -1613,6 +1742,7 @@ export const ko: Record<TKey, string> = {
   "accountPool.priorityUpdateFailed": "{email}의 선택 순서를 저장하지 못했습니다. 마지막으로 확인된 값을 표시합니다.",
   "codexAuth.switched": "다음 요청에 {email}을(를) 사용합니다",
   "codexAuth.loadFailed": "Codex 계정 설정을 불러오지 못했습니다.",
+  "codexAuth.accountsRefreshFailed": "최신 계정 새로고침에 실패했습니다. 아래 목록은 마지막으로 확인된 계정입니다.",
   "codexAuth.switchFailed": "계정을 전환하지 못했습니다. 이전 선택은 그대로 유지됩니다.",
   "codexAuth.removeConfirm": "{id}을(를) 삭제하시겠습니까?",
   "codexAuth.removeFailed": "계정을 제거하지 못했습니다. 변경된 내용은 없습니다.",
@@ -2655,6 +2785,19 @@ export const ko: Record<TKey, string> = {
   "claudeDesktop.status.notActiveProfile": "Desktop이 다른 프로필을 사용 중 — 재적용 필요",
   "claudeDesktop.status.disabled": "Claude Desktop 통합이 꺼져 있습니다. 켠 뒤 Desktop을 완전히 종료하고 다시 여세요.",
   "claudeDesktop.enableApply": "켜고 적용",
+  "claudeDesktop.switchModeApply": "모드 전환 후 적용",
+  "claudeDesktop.status.appliedFirstParty": "1P: Code 탭이 로컬 프록시를 통해 연결됨",
+  "claudeDesktop.mode.legend": "연결 모드",
+  "claudeDesktop.mode.firstParty": "1P (퍼스트파티)",
+  "claudeDesktop.mode.gateway": "게이트웨이 (3P)",
+  "claudeDesktop.mode.defaultBadge": "기본값",
+  "claudeDesktop.mode.current": "현재",
+  "claudeDesktop.mode.firstPartyHint": "Desktop은 claude.ai에 로그인된 상태를 유지합니다(채팅·커넥터·원격 제어). Code 탭과 서브에이전트, Claude Code CLI만 OpenCodex를 거칩니다.",
+  "claudeDesktop.mode.gatewayHint": "앱 전체가 OpenCodex를 게이트웨이로 사용합니다. 채팅은 로컬로 실행되고 claude.ai 기능은 사용할 수 없습니다.",
+  "claudeDesktop.mode.switchNote": "전환하면 다른 모드의 설정은 제거됩니다. 적용 후 Desktop을 완전히 종료하고 다시 열어주세요.",
+  "claudeDesktop.firstParty.proxyRunning": "로컬 프록시 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "로컬 프록시 127.0.0.1:{port}가 실행 중이 아님 — OpenCodex 재시작",
+  "claudeDesktop.firstParty.interceptDisabled": "설정에서 인터셉트 프록시가 비활성화됨 (claudeCode.intercept.enabled)",
   "claudeDesktop.health.lastRequest": "마지막 요청",
   "claudeDesktop.health.stats": "{count} 요청 / {errors} 에러",
   "claudeDesktop.effort.supported": "effort",
diff --git a/gui/src/i18n/ru.ts b/gui/src/i18n/ru.ts
index 631637977eb..0e4b1729a17 100644
--- a/gui/src/i18n/ru.ts
+++ b/gui/src/i18n/ru.ts
@@ -331,6 +331,8 @@ export const ru: Record<TKey, string> = {
   "dash.stop": "Остановить прокси",
   "dash.stopConfirm": "Остановить прокси и восстановить нативный Codex?",
   "dash.stopFailed": "Не удалось остановить прокси (HTTP {status}).",
+  "dash.stopStillRunning": "Прокси всё ещё отвечает — он не остановлен.",
+  "dash.stopUnknown": "Остановка не подтверждена. Прежде чем повторять, проверьте, работает ли прокси.",
   "dash.maSwitchFailed": "Не удалось переключить режим (HTTP {status}).",
   "dash.maNetworkError": "Ошибка сети — прокси запущен?",
   "dash.stopping": "Остановка…",
@@ -375,7 +377,7 @@ export const ru: Record<TKey, string> = {
   "compactionRouting.dataNotice": "Охваченный запрос сжатия отправляет весь разговор провайдеру выбранной модели для составления сводки, даже если разговор идёт у другого провайдера.",
   "compactionRouting.autoNotice": "Автоматическое сжатие запускается само, поэтому длинный разговор может уйти этому провайдеру без вашего запроса.",
   "compactionRouting.providerWarning": "С этой настройкой каждый охваченный запрос сжатия отправляет полное содержимое разговора провайдеру {provider} для составления сводки.",
-  "compactionRouting.comboWarning": "С этой настройкой каждый охваченный запрос сжатия отправляет полное содержимое разговора каждой цели комбо {combo} ({providers}), включая резервные цели, для составления сводки.",
+  "compactionRouting.comboWarning": "С этой настройкой каждый охваченный запрос сжатия отправляет полное содержимое разговора комбо {combo} для составления сводки. Комбо пробует свои цели ({providers}) по порядку и использует первую ответившую, поэтому разговор может получить любая из них.",
   "compactionRouting.comboProvidersUnknown": "его настроенные целевые провайдеры",
   "compactionRouting.loadFailed": "Не удалось загрузить настройки сжатия.",
   "compactionRouting.saved": "Настройки сжатия сохранены.",
@@ -472,6 +474,7 @@ export const ru: Record<TKey, string> = {
   "prov.aliasPrompt": "Отображаемое имя (оставьте пустым для удаления)",
   "prov.aliasSaved": "Псевдоним сохранен",
   "prov.aliasSaveFailed": "Не удалось сохранить псевдоним",
+  "prov.aliasInvalid": "Не более 80 символов, без управляющих символов.",
   "prov.accountId": "ID",
   "prov.pasteRedirect": "Вставьте URL перенаправления или код",
   "prov.pasteRedirectHint": "Если браузер показывает ошибку localhost, скопируйте полный URL из его адресной строки и вставьте сюда (или вставьте код авторизации).",
@@ -890,7 +893,47 @@ export const ru: Record<TKey, string> = {
   "logs.detail.attempt.recovery.image413": "Слишком большой размер изображения (413)",
   "logs.detail.attempt.recovery.emptyCompletion": "Повтор пустого завершения",
   "logs.detail.attempt.recovery.consoleGoUpload": "Повтор загрузки Console",
+  "logs.detail.attempt.recovery.key401": "Повторная аутентификация API-ключа",
+  "logs.detail.attempt.recovery.oauthAccount429": "Ограничение частоты для аккаунта (429)",
+  "logs.detail.attempt.recovery.opaqueBlobRejection": "Устаревшее зашифрованное состояние отброшено",
+  "logs.detail.attempt.recovery.reasoningEffortDowngrade": "Уровень рассуждения понижен",
+  "logs.detail.outcome.label": "Итог",
+  "logs.detail.outcome.completed": "Завершено",
+  "logs.detail.outcome.failed": "Сбой",
+  "logs.detail.outcome.incomplete": "Не завершено",
+  "logs.detail.outcome.aborted": "Прервано",
+  "logs.detail.sends.label": "Отправки к провайдеру",
+  "logs.detail.sends.unresolved": "не подтверждено",
   "logs.detail.attempt.recovery.unknown": "Неизвестная причина восстановления",
+  "logs.detail.cause.label": "Причина сбоя",
+  "logs.detail.stage.label": "достигнуто",
+  "logs.detail.resend.label": "Повторная отправка",
+  "logs.detail.cause.transportUnsent": "Не отправлено на сервер",
+  "logs.detail.cause.transportAmbiguous": "Соединение потеряно, состояние сервера неизвестно",
+  "logs.detail.cause.upstreamDeclined": "Сервер отказался начать",
+  "logs.detail.cause.rateLimit": "Превышен лимит запросов",
+  "logs.detail.cause.quotaExhausted": "Квота исчерпана",
+  "logs.detail.cause.credentialRejected": "Учётные данные отклонены",
+  "logs.detail.cause.policyRefusal": "Отклонено политикой контента",
+  "logs.detail.cause.parameterRejected": "Параметр запроса отклонён",
+  "logs.detail.cause.ciphertextRefusal": "Зашифрованное состояние отклонено",
+  "logs.detail.cause.payloadTooLarge": "Слишком большой запрос",
+  "logs.detail.cause.payloadRejected": "Тело запроса отклонено",
+  "logs.detail.cause.upstreamFault": "Сбой на стороне сервера",
+  "logs.detail.cause.emptyOutput": "Нет пригодного вывода",
+  "logs.detail.cause.clientCancelled": "Отменено клиентом",
+  "logs.detail.cause.localRefusal": "Отклонено этим прокси",
+  "logs.detail.stage.preHeader": "нет заголовка ответа",
+  "logs.detail.stage.headersOnly": "только заголовки",
+  "logs.detail.stage.protocolPrelude": "начало протокола",
+  "logs.detail.stage.semanticOutput": "вывод доставлен",
+  "logs.detail.stage.sideEffect": "побочный эффект отправлен",
+  "logs.detail.stage.terminal": "ответ доставлен",
+  "logs.detail.resend.permitted": "Можно отправить повторно",
+  "logs.detail.resend.permittedAfterRepair": "Можно отправить повторно после исправления",
+  "logs.detail.resend.refusedAmbiguous": "Не отправлено повторно: состояние сервера неизвестно",
+  "logs.detail.resend.refusedCommitted": "Не отправлено повторно: клиент уже получил вывод",
+  "logs.detail.resend.refusedFutile": "Не отправлено повторно: тот же запрос снова не пройдёт",
   "logs.detail.reason.usage_missing": "Данные об использовании не были сообщены.",
   "logs.detail.reason.usage_unsupported": "Этот провайдер не сообщает данные об использовании.",
   "logs.detail.reason.output_missing": "Положительное число выходных токенов не было сообщено.",
@@ -991,6 +1034,82 @@ export const ru: Record<TKey, string> = {
   "usage.section.models": "Модели",
   "usage.section.providers": "Провайдеры",
   "usage.section.coverage": "Детализация покрытия",
+  "usage.section.companion": "Строка меню и виджет",
+  "usage.companion.title": "Строка меню и виджет",
+  "usage.companion.description": "Эти настройки управляют настольным приложением/приложением в строке меню OpenCodex и его виджетом.",
+  "usage.companion.installGuide": "Руководство по установке",
+  "usage.companion.loading": "Загрузка временной шкалы…",
+  "usage.companion.timelineUnavailable": "Временная шкала недоступна",
+  "usage.companion.empty": "Нет использования за последние {hours} ч",
+  "usage.companion.chartLabel": "Временная шкала использования",
+  "usage.companion.olderRecordsSkipped": "Старые записи пропущены",
+  "usage.companion.settingsUnavailable": "Настройки компаньона недоступны",
+  "usage.companion.corrupt": "Файл настроек компаньона повреждён. В элементах управления показаны значения по умолчанию; сохранение приостановлено, пока файл не будет заменён.",
+  "usage.companion.corruptReset": "Заменить значениями по умолчанию",
+  "usage.companion.saved": "Сохранено · {time}",
+  "usage.companion.saveFailed": "Не удалось сохранить: {error}",
+  "usage.companion.reset": "Сбросить настройки",
+  "usage.companion.footer": "Виджет показывает сегодняшние запросы, токены и стоимость, а также настроенный здесь график, и обновляется при опросе приложения.",
+  "usage.companion.menuBarShows": "В строке меню",
+  "usage.companion.menuRequests": "Запросы",
+  "usage.companion.menuTokens": "Токены",
+  "usage.companion.menuCost": "Стоимость",
+  "usage.companion.menuQuota": "Квота",
+  "usage.companion.menuNone": "Только значок",
+  "usage.companion.window": "Период",
+  "usage.companion.window6": "6 ч",
+  "usage.companion.window24": "24 ч",
+  "usage.companion.window72": "3 д",
+  "usage.companion.window168": "7 д",
+  "usage.companion.style": "Стиль",
+  "usage.companion.styleLine": "Линия",
+  "usage.companion.styleStacked": "С накоплением",
+  "usage.companion.metric": "Метрика",
+  "usage.companion.metricTotal": "Всего",
+  "usage.companion.metricInput": "Входные",
+  "usage.companion.metricOutput": "Выходные",
+  "usage.companion.metricCached": "Из кэша",
+  "usage.companion.groupBy": "Группировать по",
+  "usage.companion.groupModel": "Модели",
+  "usage.companion.groupAccount": "Модели + аккаунту",
+  "usage.companion.popoverSections": "Разделы всплывающего окна",
+  "usage.companion.sectionToday": "Сегодня",
+  "usage.companion.sectionChart": "График",
+  "usage.companion.sectionModels": "Модели",
+  "usage.companion.sectionCost": "Стоимость",
+  "usage.companion.sectionAccounts": "Аккаунты",
+  "usage.companion.advanced": "Дополнительно",
+  "usage.companion.aggregation": "Агрегация",
+  "usage.companion.aggregationSum": "Сумма",
+  "usage.companion.aggregationAverage": "Среднее",
+  "usage.companion.aggregationMax": "Максимум",
+  "usage.companion.menuText": "Текст строки меню",
+  "usage.companion.placeholders": "Заполнители:",
+  "usage.companion.modelsOnChart": "Модели на графике",
+  "usage.companion.connected": "Приложение в строке меню подключено · {age}",
+  "usage.companion.connectedDesktop": "Настольное приложение подключено · {age}",
+  "usage.companion.installTitle": "Установить настольное приложение",
+  "usage.companion.installOs": "Операционная система",
+  "usage.companion.osMac": "macOS",
+  "usage.companion.osWindows": "Windows",
+  "usage.companion.osLinux": "Linux",
+  "usage.companion.runningInDesktop": "Вы находитесь в настольном приложении OpenCodex {version}",
+  "usage.companion.openInBrowser": "Открыть в браузере",
+  "usage.companion.installMacStep1": "Скачайте OpenCodex-<version>-macos.dmg из последнего релиза и перетащите OpenCodex.app в Программы.",
+  "usage.companion.installMacStep2": "Первый запуск: нажмите OpenCodex.app правой кнопкой и выберите «Открыть» (до нотариальной заверки Gatekeeper спросит один раз).",
+  "usage.companion.installMacStep3": "Приложение само найдёт этот прокси; после запуска приложение появится в галерее виджетов.",
+  "usage.companion.installWinStep1": "Скачайте OpenCodex-<version>-windows-x64.msi из последнего релиза и запустите его.",
+  "usage.companion.installWinStep2": "Если SmartScreen предупредит, выберите Подробнее → Всё равно запустить (установщик ещё не подписан).",
+  "usage.companion.installWinStep3": "OpenCodex появится в системном трее и подключится к этому прокси или запустит встроенный.",
+  "usage.companion.installLinuxStep1": "Скачайте OpenCodex-<version>-linux-x86_64.AppImage (или .deb) из последнего релиза.",
+  "usage.companion.installLinuxStep2": "Выполните chmod +x для AppImage и запустите его; для значка в трее нужен рабочий стол с поддержкой AppIndicator.",
+  "usage.companion.installLinuxStep3": "Приложение подключится к этому прокси или запустит встроенный.",
+  "usage.companion.notConnected": "К этому прокси ещё не подключалось приложение из строки меню.",
+  "usage.companion.lastSeen": "Последнее подключение: {age}",
+  "usage.companion.installAnother": "Установить на другом устройстве",
+  "usage.companion.modelsCount": "{selected} из {total} на графике",
+  "usage.companion.modelsShowAll": "Показать все",
+  "usage.companion.hideProviders": "Скрыть провайдеров",
   "usage.workspace.report": "Отчёт об использовании",
   "usage.workspace.sections": "Разделы использования",
   "usage.coverage.measured": "Измерено",
@@ -1001,6 +1120,14 @@ export const ru: Record<TKey, string> = {
   "usage.col.requests": "Запросы",
   "usage.col.measured": "Измерено",
   "usage.col.reported": "Сообщено",
+  "usage.col.inputTokens": "Входные токены",
+  "usage.col.outputTokens": "Выходные токены",
+  "usage.col.cacheHits": "Попадания в кэш",
+  "usage.col.cacheWrites": "Записи в кэш",
+  "usage.col.cacheHitRate": "Доля попаданий",
+  "usage.cacheHitRate.partial": "Среднее рассчитано по {measured} из {total} входных токенов; для остальных запросов сведения о кэше не поступили.",
+  "usage.cacheHitRate.unmeasured": "Ни один запрос в этой строке не содержал сведений о кэше, поэтому среднюю долю попаданий рассчитать нельзя.",
+  "usage.unavailable": "—",
   "usage.col.tokens": "Токены",
   "usage.col.apiListPrice": "Прайс-лист API",
   "usage.col.share": "Доля",
@@ -1824,6 +1951,7 @@ export const ru: Record<TKey, string> = {
   "integrations.status.installed": "Установлен",
   "integrations.status.notInstalled": "Не установлен",
   "integrations.status.appliedAt": "Применено",
+  "integrations.status.supersededStore": "Этот клиент теперь читает провайдеров из {path}, а opencodex этот файл не пишет, поэтому включение здесь ничего не изменит в том, что клиент загружает.",
   "integrations.status.backup": "Резервная копия",
   "integrations.status.lastRestore": "Последнее восстановление",
   "integrations.status.unknown": "Неизвестно",
@@ -1884,6 +2012,7 @@ export const ru: Record<TKey, string> = {
   "integrations.plan.refusal.conflict": "Управляемые настройки конфликтуют с текущим файлом. Проверьте файл или используйте замену, если она доступна.",
   "integrations.plan.refusal.unsafe": "Конфигурацию клиента нельзя безопасно изменить. Исправьте или замените файл перед повторной попыткой.",
   "integrations.plan.refusal.nonLoopback": "Этому клиенту нужен адрес прокси в loopback. Используйте localhost, туннель или локальную переадресацию.",
+  "integrations.plan.refusal.supersededStore": "Этот клиент читает провайдеров из файла, который opencodex не пишет, поэтому операция ничего не изменит в том, что он загружает.",
   "integrations.plan.refusal.driftRequiresConfirm": "Файл изменился после этой точки отката. Проверьте план с учётом изменений перед восстановлением.",
   "integrations.plan.refusal.snapshotExpired": "Резервная копия для этой точки отката истекла и больше не может быть восстановлена.",
   "integrations.plan.refusal.writeFailed": "Сервер не смог подготовить безопасную запись. Обновите состояние интеграции перед повторной попыткой.",
@@ -2092,6 +2221,7 @@ export const ru: Record<TKey, string> = {
   "accountPool.priorityUpdateFailed": "Не удалось сохранить порядок выбора для {email}. Показано последнее подтверждённое значение.",
   "codexAuth.switched": "{email} выбран для следующего запроса",
   "codexAuth.loadFailed": "Не удалось загрузить настройки аккаунтов Codex.",
+  "codexAuth.accountsRefreshFailed": "Последнее обновление аккаунтов не удалось. Ниже показаны последние подтверждённые аккаунты.",
   "codexAuth.switchFailed": "Не удалось переключить аккаунт. Ваш предыдущий выбор не изменён.",
   "codexAuth.removeConfirm": "Удалить {id}?",
   "codexAuth.removeFailed": "Не удалось удалить аккаунт. Ничего не изменено.",
@@ -2509,6 +2639,19 @@ export const ru: Record<TKey, string> = {
   "claudeDesktop.status.notActiveProfile": "Desktop использует другой профиль — примените заново",
   "claudeDesktop.status.disabled": "Интеграция Claude Desktop отключена. После включения полностью закройте и снова откройте Desktop.",
   "claudeDesktop.enableApply": "Включить и применить",
+  "claudeDesktop.switchModeApply": "Сменить режим и применить",
+  "claudeDesktop.status.appliedFirstParty": "First-party: вкладка Code идёт через локальный прокси",
+  "claudeDesktop.mode.legend": "Режим подключения",
+  "claudeDesktop.mode.firstParty": "First-party",
+  "claudeDesktop.mode.gateway": "Шлюз (сторонний)",
+  "claudeDesktop.mode.defaultBadge": "по умолчанию",
+  "claudeDesktop.mode.current": "текущий",
+  "claudeDesktop.mode.firstPartyHint": "Desktop остаётся в claude.ai (чат, коннекторы, удалённое управление). Через OpenCodex идут только вкладка Code, её субагенты и CLI Claude Code.",
+  "claudeDesktop.mode.gatewayHint": "Всё приложение переключается на OpenCodex как шлюз. Чат работает локально; функции claude.ai недоступны.",
+  "claudeDesktop.mode.switchNote": "Переключение удаляет настройки другого режима. После применения полностью закройте и заново откройте Desktop.",
+  "claudeDesktop.firstParty.proxyRunning": "Локальный прокси на 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "Локальный прокси 127.0.0.1:{port} не запущен — перезапустите OpenCodex",
+  "claudeDesktop.firstParty.interceptDisabled": "Перехватывающий прокси отключён в конфигурации (claudeCode.intercept.enabled)",
   "claudeDesktop.health.lastRequest": "Последний запрос",
   "claudeDesktop.health.stats": "{count} запр. / {errors} ошиб.",
   "claudeDesktop.effort.supported": "effort",
diff --git a/gui/src/i18n/tr.ts b/gui/src/i18n/tr.ts
index 1646ccb8251..2bf09d6aa98 100644
--- a/gui/src/i18n/tr.ts
+++ b/gui/src/i18n/tr.ts
@@ -332,6 +332,8 @@ export const tr: Record<TKey, string> = {
   "dash.stop": "Proxy'yi Durdur",
   "dash.stopConfirm": "Proxy durdurulsun ve yerel Codex geri yüklensin mi?",
   "dash.stopFailed": "Proxy durdurulamadı (HTTP {status}).",
+  "dash.stopStillRunning": "Proxy hâlâ yanıt veriyor, yani durmadı.",
+  "dash.stopUnknown": "Durdurma doğrulanamadı. Yeniden denemeden önce proxy’nin çalışıp çalışmadığını kontrol edin.",
   "dash.maSwitchFailed": "Mod değiştirme başarısız oldu (HTTP {status}).",
   "dash.maNetworkError": "Ağ hatası — proxy çalışıyor mu?",
   "dash.stopping": "Durduruluyor…",
@@ -376,7 +378,7 @@ export const tr: Record<TKey, string> = {
   "compactionRouting.dataNotice": "Kapsama giren bir özetleme isteği, konuşma başka bir sağlayıcıda yürütülse bile konuşmanın tamamını özetlenmek üzere seçilen modelin sağlayıcısına gönderir.",
   "compactionRouting.autoNotice": "Otomatik özetleme kendiliğinden çalışır; bu nedenle uzun bir konuşma siz istemeden o sağlayıcıya gidebilir.",
   "compactionRouting.providerWarning": "Bu ayarla kapsama giren her özetleme isteği, konuşmanın tüm içeriğini özetlenmek üzere {provider} sağlayıcısına gönderir.",
-  "compactionRouting.comboWarning": "Bu ayarla kapsama giren her özetleme isteği, konuşmanın tüm içeriğini yedek hedefler dahil {combo} kombosunun her hedefine ({providers}) özetlenmek üzere gönderir.",
+  "compactionRouting.comboWarning": "Bu ayarla kapsama giren her özetleme isteği, konuşmanın tüm içeriğini özetlenmek üzere {combo} kombosuna gönderir. Kombo hedeflerini ({providers}) sırayla dener ve yanıt veren ilkini kullanır; dolayısıyla bunlardan herhangi biri konuşmayı alabilir.",
   "compactionRouting.comboProvidersUnknown": "yapılandırılmış hedef sağlayıcıları",
   "compactionRouting.loadFailed": "Özetleme ayarları yüklenemedi.",
   "compactionRouting.saved": "Özetleme ayarları kaydedildi.",
@@ -475,6 +477,7 @@ export const tr: Record<TKey, string> = {
   "prov.aliasPrompt": "Görüntülenen ad (temizlemek için boş bırakın)",
   "prov.aliasSaved": "Takma ad kaydedildi",
   "prov.aliasSaveFailed": "Takma ad kaydedilemedi",
+  "prov.aliasInvalid": "En fazla 80 karakter kullanın, kontrol karakteri içermemelidir.",
   "prov.accountId": "ID",
   "prov.pasteRedirect": "Yönlendirme URL'sini veya kodu yapıştırın",
   "prov.pasteRedirectHint": "Tarayıcı localhost hatası gösterirse adres çubuğundaki URL'yi kopyalayıp buraya yapıştırın.",
@@ -909,7 +912,47 @@ export const tr: Record<TKey, string> = {
   "logs.detail.attempt.recovery.image413": "Görsel boyutu çok büyük (413)",
   "logs.detail.attempt.recovery.emptyCompletion": "Boş tamamlama yeniden denemesi",
   "logs.detail.attempt.recovery.consoleGoUpload": "Console yüklemesi yeniden denendi",
+  "logs.detail.attempt.recovery.key401": "API anahtarı yeniden doğrulandı",
+  "logs.detail.attempt.recovery.oauthAccount429": "Hesap hız sınırına takıldı (429)",
+  "logs.detail.attempt.recovery.opaqueBlobRejection": "Eski şifreli durum bırakıldı",
+  "logs.detail.attempt.recovery.reasoningEffortDowngrade": "Akıl yürütme düzeyi düşürüldü",
+  "logs.detail.outcome.label": "Sonuç",
+  "logs.detail.outcome.completed": "Tamamlandı",
+  "logs.detail.outcome.failed": "Başarısız",
+  "logs.detail.outcome.incomplete": "Tamamlanmadı",
+  "logs.detail.outcome.aborted": "İptal edildi",
+  "logs.detail.sends.label": "Yukarı akış gönderimleri",
+  "logs.detail.sends.unresolved": "çözülmemiş",
   "logs.detail.attempt.recovery.unknown": "Bilinmeyen kurtarma nedeni",
+  "logs.detail.cause.label": "Hata nedeni",
+  "logs.detail.stage.label": "ulaşıldı",
+  "logs.detail.resend.label": "Yeniden gönder",
+  "logs.detail.cause.transportUnsent": "Sunucuya hiç gönderilmedi",
+  "logs.detail.cause.transportAmbiguous": "Bağlantı koptu, sunucu durumu bilinmiyor",
+  "logs.detail.cause.upstreamDeclined": "Sunucu başlamayı reddetti",
+  "logs.detail.cause.rateLimit": "Hız sınırına takıldı",
+  "logs.detail.cause.quotaExhausted": "Kota tükendi",
+  "logs.detail.cause.credentialRejected": "Kimlik bilgileri reddedildi",
+  "logs.detail.cause.policyRefusal": "İçerik politikası reddetti",
+  "logs.detail.cause.parameterRejected": "İstek parametresi reddedildi",
+  "logs.detail.cause.ciphertextRefusal": "Şifreli durum reddedildi",
+  "logs.detail.cause.payloadTooLarge": "Yük çok büyük",
+  "logs.detail.cause.payloadRejected": "Yük reddedildi",
+  "logs.detail.cause.upstreamFault": "Sunucu arızası",
+  "logs.detail.cause.emptyOutput": "Kullanılabilir çıktı yok",
+  "logs.detail.cause.clientCancelled": "İstemci iptal etti",
+  "logs.detail.cause.localRefusal": "Bu proxy reddetti",
+  "logs.detail.stage.preHeader": "yanıt başlığı yok",
+  "logs.detail.stage.headersOnly": "yalnızca başlıklar",
+  "logs.detail.stage.protocolPrelude": "protokol ön bölümü",
+  "logs.detail.stage.semanticOutput": "çıktı iletildi",
+  "logs.detail.stage.sideEffect": "yan etki üretildi",
+  "logs.detail.stage.terminal": "yanıt iletildi",
+  "logs.detail.resend.permitted": "Yeniden gönderilebilir",
+  "logs.detail.resend.permittedAfterRepair": "Onarımdan sonra yeniden gönderilebilir",
+  "logs.detail.resend.refusedAmbiguous": "Yeniden gönderilmedi: sunucu durumu bilinmiyor",
+  "logs.detail.resend.refusedCommitted": "Yeniden gönderilmedi: çağıran çıktıyı zaten gördü",
+  "logs.detail.resend.refusedFutile": "Yeniden gönderilmedi: aynı istek yine başarısız olur",
   "logs.detail.reason.usage_missing": "Kullanım bildirilmedi.",
   "logs.detail.reason.usage_unsupported": "Bu sağlayıcı kullanım bildirmeyebilir.",
   "logs.detail.reason.output_missing": "Çıktı jeton sayısı bildirilmedi.",
@@ -1010,6 +1053,82 @@ export const tr: Record<TKey, string> = {
   "usage.section.models": "Modeller",
   "usage.section.providers": "Sağlayıcılar",
   "usage.section.coverage": "Kapsam dağılımı",
+  "usage.section.companion": "Menü çubuğu ve widget",
+  "usage.companion.title": "Menü çubuğu ve widget",
+  "usage.companion.description": "Buradaki ayarlar OpenCodex masaüstü/menü çubuğu uygulamasını ve widget’ını yönetir.",
+  "usage.companion.installGuide": "Kurulum rehberi",
+  "usage.companion.loading": "Zaman çizelgesi yükleniyor…",
+  "usage.companion.timelineUnavailable": "Zaman çizelgesi kullanılamıyor",
+  "usage.companion.empty": "Son {hours} saatte kullanım yok",
+  "usage.companion.chartLabel": "Kullanım zaman çizelgesi",
+  "usage.companion.olderRecordsSkipped": "Eski kayıtlar atlandı",
+  "usage.companion.settingsUnavailable": "Yardımcı ayarları kullanılamıyor",
+  "usage.companion.corrupt": "Yardımcı ayarları dosyası bozuk. Denetimler varsayılan değerleri gösteriyor; dosyayı değiştirene kadar kaydetme duraklatıldı.",
+  "usage.companion.corruptReset": "Varsayılanlarla değiştir",
+  "usage.companion.saved": "Kaydedildi · {time}",
+  "usage.companion.saveFailed": "Kaydedilemedi: {error}",
+  "usage.companion.reset": "Varsayılanlara sıfırla",
+  "usage.companion.footer": "Widget, bugünkü istekleri, belirteçleri ve maliyeti ve burada yapılandırılan grafiği gösterir; uygulama yoklama yaptığında yenilenir.",
+  "usage.companion.menuBarShows": "Menü çubuğunda göster",
+  "usage.companion.menuRequests": "İstekler",
+  "usage.companion.menuTokens": "Tokenlar",
+  "usage.companion.menuCost": "Maliyet",
+  "usage.companion.menuQuota": "Kota",
+  "usage.companion.menuNone": "Yalnızca simge",
+  "usage.companion.window": "Aralık",
+  "usage.companion.window6": "6 sa",
+  "usage.companion.window24": "24 sa",
+  "usage.companion.window72": "3 gün",
+  "usage.companion.window168": "7 gün",
+  "usage.companion.style": "Stil",
+  "usage.companion.styleLine": "Çizgi",
+  "usage.companion.styleStacked": "Yığılmış",
+  "usage.companion.metric": "Metrik",
+  "usage.companion.metricTotal": "Toplam",
+  "usage.companion.metricInput": "Girdi",
+  "usage.companion.metricOutput": "Çıktı",
+  "usage.companion.metricCached": "Önbellek",
+  "usage.companion.groupBy": "Gruplama",
+  "usage.companion.groupModel": "Model",
+  "usage.companion.groupAccount": "Model + hesap",
+  "usage.companion.popoverSections": "Açılır pencere bölümleri",
+  "usage.companion.sectionToday": "Bugün",
+  "usage.companion.sectionChart": "Grafik",
+  "usage.companion.sectionModels": "Modeller",
+  "usage.companion.sectionCost": "Maliyet",
+  "usage.companion.sectionAccounts": "Hesaplar",
+  "usage.companion.advanced": "Gelişmiş",
+  "usage.companion.aggregation": "Toplama",
+  "usage.companion.aggregationSum": "Toplam",
+  "usage.companion.aggregationAverage": "Ortalama",
+  "usage.companion.aggregationMax": "Maksimum",
+  "usage.companion.menuText": "Menü çubuğu metni",
+  "usage.companion.placeholders": "Yer tutucular:",
+  "usage.companion.modelsOnChart": "Grafikteki modeller",
+  "usage.companion.connected": "Menü çubuğu uygulaması bağlı · {age}",
+  "usage.companion.connectedDesktop": "Masaüstü uygulaması bağlı · {age}",
+  "usage.companion.installTitle": "Masaüstü uygulamasını yükle",
+  "usage.companion.installOs": "İşletim sistemi",
+  "usage.companion.osMac": "macOS",
+  "usage.companion.osWindows": "Windows",
+  "usage.companion.osLinux": "Linux",
+  "usage.companion.runningInDesktop": "OpenCodex masaüstü uygulaması {version} içindesiniz",
+  "usage.companion.openInBrowser": "Tarayıcıda aç",
+  "usage.companion.installMacStep1": "En son sürümden OpenCodex-<version>-macos.dmg dosyasını indirin ve OpenCodex.app’i Uygulamalar’a sürükleyin.",
+  "usage.companion.installMacStep2": "İlk çalıştırma: OpenCodex.app’e sağ tıklayıp Aç’ı seçin (uygulama not edilene kadar Gatekeeper bir kez sorar).",
+  "usage.companion.installMacStep3": "Uygulama bu proxy’yi kendisi bulur; uygulama çalıştıktan sonra widget galeride görünür.",
+  "usage.companion.installWinStep1": "En son sürümden OpenCodex-<version>-windows-x64.msi dosyasını indirin ve çalıştırın.",
+  "usage.companion.installWinStep2": "SmartScreen uyarırsa Daha fazla bilgi → Yine de çalıştır seçeneğini seçin (yükleyici henüz kod imzalı değil).",
+  "usage.companion.installWinStep3": "OpenCodex sistem tepsisinde görünür ve bu proxy’ye bağlanır veya paketlenmiş olanı başlatır.",
+  "usage.companion.installLinuxStep1": "En son sürümden OpenCodex-<version>-linux-x86_64.AppImage (veya .deb) dosyasını indirin.",
+  "usage.companion.installLinuxStep2": "AppImage için chmod +x çalıştırıp başlatın; tepsi simgesi AppIndicator destekli bir masaüstü gerektirir.",
+  "usage.companion.installLinuxStep3": "Uygulama bu proxy’ye bağlanır veya paketlenmiş olanı başlatır.",
+  "usage.companion.notConnected": "Bu proxy'ye henüz hiçbir menü çubuğu uygulaması bağlanmadı.",
+  "usage.companion.lastSeen": "Son görülme {age}",
+  "usage.companion.installAnother": "Başka bir cihaza yükle",
+  "usage.companion.modelsCount": "Grafikte {selected}/{total}",
+  "usage.companion.modelsShowAll": "Tümünü göster",
+  "usage.companion.hideProviders": "Sağlayıcıları gizle",
   "usage.workspace.report": "Kullanım raporu",
   "usage.workspace.sections": "Kullanım bölümleri",
   "usage.coverage.measured": "Ölçülen",
@@ -1020,6 +1139,14 @@ export const tr: Record<TKey, string> = {
   "usage.col.requests": "İstekler",
   "usage.col.measured": "Ölçülen",
   "usage.col.reported": "Bildirilen",
+  "usage.col.inputTokens": "Girdi jetonları",
+  "usage.col.outputTokens": "Çıktı jetonları",
+  "usage.col.cacheHits": "Önbellek isabetleri",
+  "usage.col.cacheWrites": "Önbellek yazma",
+  "usage.col.cacheHitRate": "İsabet oranı",
+  "usage.cacheHitRate.partial": "Toplam {total} girdi jetonunun {measured} kadarı üzerinden ortalama hesaplandı; kalan isteklerde önbellek ayrıntısı bildirilmedi.",
+  "usage.cacheHitRate.unmeasured": "Bu satırdaki hiçbir istek önbellek ayrıntısı bildirmediği için hesaplanabilecek bir ortalama isabet oranı yok.",
+  "usage.unavailable": "—",
   "usage.col.tokens": "Jetonlar",
   "usage.col.apiListPrice": "API liste fiyatı",
   "usage.col.share": "Pay",
@@ -1843,6 +1970,7 @@ export const tr: Record<TKey, string> = {
   "integrations.status.installed": "Yüklü",
   "integrations.status.notInstalled": "Yüklü değil",
   "integrations.status.appliedAt": "Uygulandı",
+  "integrations.status.supersededStore": "Bu istemci sağlayıcılarını artık {path} dosyasından okuyor; opencodex bu dosyayı yazmadığı için buradan etkinleştirmek istemcinin yüklediklerini değiştirmez.",
   "integrations.status.backup": "Yedek",
   "integrations.status.lastRestore": "Son geri yükleme",
   "integrations.status.unknown": "Bilinmiyor",
@@ -1903,6 +2031,7 @@ export const tr: Record<TKey, string> = {
   "integrations.plan.refusal.conflict": "Yönetilen ayarlar mevcut dosyayla çakışıyor. Dosyayı inceleyin veya varsa Değiştir işlemini kullanın.",
   "integrations.plan.refusal.unsafe": "İstemci yapılandırması güvenle değiştirilemiyor. Yeniden denemeden önce dosyayı onarın veya değiştirin.",
   "integrations.plan.refusal.nonLoopback": "Bu istemci bir geri döngü proxy adresi gerektiriyor. localhost, tünel veya yerel yönlendirme kullanın.",
+  "integrations.plan.refusal.supersededStore": "Bu istemci sağlayıcılarını opencodex'in yazmadığı bir dosyadan okuyor; bu işlem istemcinin yüklediklerini değiştirmez.",
   "integrations.plan.refusal.driftRequiresConfirm": "Dosya bu geri alma noktasından sonra değişti. Geri yüklemeden önce değişikliği dikkate alan planı inceleyin.",
   "integrations.plan.refusal.snapshotExpired": "Bu geri alma noktasının yedeği sona erdiği için artık geri yüklenemez.",
   "integrations.plan.refusal.writeFailed": "Sunucu güvenli bir yazma işlemi hazırlayamadı. Yeniden denemeden önce entegrasyon durumunu yenileyin.",
@@ -2112,6 +2241,7 @@ export const tr: Record<TKey, string> = {
 
   "codexAuth.switched": "Sonraki istek için {email} seçildi",
   "codexAuth.loadFailed": "Codex hesap ayarları yüklenemedi.",
+  "codexAuth.accountsRefreshFailed": "Son hesap yenilemesi başarısız oldu. Aşağıda son doğrulanan hesaplar gösteriliyor.",
   "codexAuth.switchFailed": "Hesap değiştirilemedi.",
   "codexAuth.removeConfirm": "{id} kaldırılsın mı?",
   "codexAuth.removeFailed": "Hesap kaldırılamadı.",
@@ -2658,6 +2788,19 @@ export const tr: Record<TKey, string> = {
   "claudeDesktop.status.notActiveProfile": "Desktop başka bir profil kullanıyor",
   "claudeDesktop.status.disabled": "Claude Desktop entegrasyonu kapalı.",
   "claudeDesktop.enableApply": "Etkinleştir ve uygula",
+  "claudeDesktop.switchModeApply": "Modu değiştir ve uygula",
+  "claudeDesktop.status.appliedFirstParty": "First-party: Code sekmesi yerel proxy üzerinden",
+  "claudeDesktop.mode.legend": "Bağlantı modu",
+  "claudeDesktop.mode.firstParty": "First-party",
+  "claudeDesktop.mode.gateway": "Ağ geçidi (üçüncü taraf)",
+  "claudeDesktop.mode.defaultBadge": "varsayılan",
+  "claudeDesktop.mode.current": "geçerli",
+  "claudeDesktop.mode.firstPartyHint": "Desktop claude.ai'de oturum açık kalır (sohbet, bağlayıcılar, uzaktan kontrol). Yalnızca Code sekmesi, alt ajanları ve Claude Code CLI OpenCodex üzerinden geçer.",
+  "claudeDesktop.mode.gatewayHint": "Uygulamanın tamamı OpenCodex'i ağ geçidi olarak kullanır. Sohbet yerelde çalışır; claude.ai özellikleri kullanılamaz.",
+  "claudeDesktop.mode.switchNote": "Geçiş diğer modun yapılandırmasını kaldırır. Ardından Desktop'ı tamamen kapatıp yeniden açın.",
+  "claudeDesktop.firstParty.proxyRunning": "Yerel proxy 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "Yerel proxy 127.0.0.1:{port} çalışmıyor — OpenCodex'i yeniden başlatın",
+  "claudeDesktop.firstParty.interceptDisabled": "Yakalama proxy'si yapılandırmada kapalı (claudeCode.intercept.enabled)",
   "claudeDesktop.health.lastRequest": "Son istek",
   "claudeDesktop.health.stats": "{count} istek / {errors} hata",
   "claudeDesktop.effort.supported": "çaba",
diff --git a/gui/src/i18n/vi.ts b/gui/src/i18n/vi.ts
index 3d726cc35e7..b79db56b352 100644
--- a/gui/src/i18n/vi.ts
+++ b/gui/src/i18n/vi.ts
@@ -318,6 +318,8 @@ export const vi: Record<TKey, string> = {
   "dash.stop": "Dừng Proxy",
   "dash.stopConfirm": "Dừng proxy và khôi phục native Codex?",
   "dash.stopFailed": "Không thể dừng proxy (HTTP {status}).",
+  "dash.stopStillRunning": "Proxy vẫn đang phản hồi nên chưa dừng.",
+  "dash.stopUnknown": "Chưa xác nhận được việc dừng. Hãy kiểm tra proxy còn chạy không trước khi thử lại.",
   "dash.maSwitchFailed": "Chuyển đổi chế độ thất bại (HTTP {status}).",
   "dash.maNetworkError": "Lỗi mạng — có phải proxy đang chạy không?",
   "dash.stopping": "Đang dừng…",
@@ -368,7 +370,7 @@ export const vi: Record<TKey, string> = {
   "compactionRouting.dataNotice": "Yêu cầu nén thuộc phạm vi áp dụng sẽ gửi toàn bộ cuộc trò chuyện đến nhà cung cấp của model đã chọn để tóm tắt, ngay cả khi cuộc trò chuyện đang chạy ở nhà cung cấp khác.",
   "compactionRouting.autoNotice": "Nén tự động tự chạy, nên một cuộc trò chuyện dài có thể được gửi đến nhà cung cấp đó mà bạn không yêu cầu.",
   "compactionRouting.providerWarning": "Với thiết lập này, mỗi yêu cầu nén thuộc phạm vi áp dụng sẽ gửi toàn bộ nội dung cuộc trò chuyện đến {provider} để tóm tắt.",
-  "compactionRouting.comboWarning": "Với thiết lập này, mỗi yêu cầu nén thuộc phạm vi áp dụng sẽ gửi toàn bộ nội dung cuộc trò chuyện đến mọi đích của combo {combo} ({providers}), bao gồm cả đích dự phòng, để tóm tắt.",
+  "compactionRouting.comboWarning": "Với thiết lập này, mỗi yêu cầu nén thuộc phạm vi áp dụng sẽ gửi toàn bộ nội dung cuộc trò chuyện đến combo {combo} để tóm tắt. Combo thử lần lượt các đích ({providers}) và dùng đích trả lời đầu tiên, nên bất kỳ đích nào cũng có thể nhận cuộc trò chuyện.",
   "compactionRouting.comboProvidersUnknown": "các nhà cung cấp đích đã cấu hình của nó",
   "compactionRouting.loadFailed": "Không thể tải cài đặt nén.",
   "compactionRouting.saved": "Đã lưu cài đặt nén.",
@@ -465,6 +467,7 @@ export const vi: Record<TKey, string> = {
   "prov.aliasPrompt": "Tên hiển thị (để trống để xoá)",
   "prov.aliasSaved": "Đã lưu bí danh",
   "prov.aliasSaveFailed": "Không thể lưu bí danh",
+  "prov.aliasInvalid": "Dùng tối đa 80 ký tự, không chứa ký tự điều khiển.",
   "prov.accountId": "ID",
   "prov.pasteRedirect": "Dán URL chuyển hướng hoặc mã",
   "prov.pasteRedirectHint": "Nếu trình duyệt hiển thị lỗi localhost, hãy sao chép URL đầy đủ từ thanh địa chỉ và dán nó vào đây (hoặc dán authorization code).",
@@ -896,7 +899,47 @@ export const vi: Record<TKey, string> = {
   "logs.detail.attempt.recovery.image413": "Kích thước hình ảnh quá lớn (413)",
   "logs.detail.attempt.recovery.emptyCompletion": "Thử lại do hoàn thành rỗng (Empty completion retry)",
   "logs.detail.attempt.recovery.consoleGoUpload": "Thử lại tải lên Console",
+  "logs.detail.attempt.recovery.key401": "Xác thực lại khóa API",
+  "logs.detail.attempt.recovery.oauthAccount429": "Tài khoản bị giới hạn tần suất (429)",
+  "logs.detail.attempt.recovery.opaqueBlobRejection": "Đã bỏ trạng thái mã hóa cũ",
+  "logs.detail.attempt.recovery.reasoningEffortDowngrade": "Đã giảm mức suy luận",
+  "logs.detail.outcome.label": "Kết quả",
+  "logs.detail.outcome.completed": "Hoàn tất",
+  "logs.detail.outcome.failed": "Thất bại",
+  "logs.detail.outcome.incomplete": "Chưa hoàn tất",
+  "logs.detail.outcome.aborted": "Đã hủy",
+  "logs.detail.sends.label": "Số lần gửi lên nhà cung cấp",
+  "logs.detail.sends.unresolved": "chưa xác định",
   "logs.detail.attempt.recovery.unknown": "Lý do khôi phục không rõ",
+  "logs.detail.cause.label": "Nguyên nhân lỗi",
+  "logs.detail.stage.label": "đã đến",
+  "logs.detail.resend.label": "Gửi lại",
+  "logs.detail.cause.transportUnsent": "Chưa gửi lên thượng nguồn",
+  "logs.detail.cause.transportAmbiguous": "Mất kết nối, không rõ trạng thái thượng nguồn",
+  "logs.detail.cause.upstreamDeclined": "Thượng nguồn từ chối bắt đầu",
+  "logs.detail.cause.rateLimit": "Bị giới hạn tốc độ",
+  "logs.detail.cause.quotaExhausted": "Đã hết hạn mức",
+  "logs.detail.cause.credentialRejected": "Thông tin xác thực bị từ chối",
+  "logs.detail.cause.policyRefusal": "Bị chính sách nội dung từ chối",
+  "logs.detail.cause.parameterRejected": "Tham số yêu cầu bị từ chối",
+  "logs.detail.cause.ciphertextRefusal": "Trạng thái mã hoá bị từ chối",
+  "logs.detail.cause.payloadTooLarge": "Tải trọng quá lớn",
+  "logs.detail.cause.payloadRejected": "Tải trọng bị từ chối",
+  "logs.detail.cause.upstreamFault": "Lỗi thượng nguồn",
+  "logs.detail.cause.emptyOutput": "Không có đầu ra dùng được",
+  "logs.detail.cause.clientCancelled": "Ứng dụng khách đã huỷ",
+  "logs.detail.cause.localRefusal": "Proxy này từ chối",
+  "logs.detail.stage.preHeader": "không có đầu phản hồi",
+  "logs.detail.stage.headersOnly": "chỉ có tiêu đề",
+  "logs.detail.stage.protocolPrelude": "phần mở đầu giao thức",
+  "logs.detail.stage.semanticOutput": "đã gửi đầu ra",
+  "logs.detail.stage.sideEffect": "đã phát sinh tác dụng phụ",
+  "logs.detail.stage.terminal": "đã gửi câu trả lời",
+  "logs.detail.resend.permitted": "Có thể gửi lại",
+  "logs.detail.resend.permittedAfterRepair": "Có thể gửi lại sau khi sửa",
+  "logs.detail.resend.refusedAmbiguous": "Không gửi lại: không rõ trạng thái thượng nguồn",
+  "logs.detail.resend.refusedCommitted": "Không gửi lại: bên gọi đã thấy đầu ra",
+  "logs.detail.resend.refusedFutile": "Không gửi lại: yêu cầu tương tự vẫn sẽ lỗi",
   "logs.detail.reason.usage_missing": "Mức sử dụng không được báo cáo.",
   "logs.detail.reason.usage_unsupported": "Provider này không báo cáo mức sử dụng.",
   "logs.detail.reason.output_missing": "Không có số lượng output token dương nào được báo cáo.",
@@ -993,6 +1036,82 @@ export const vi: Record<TKey, string> = {
   "usage.section.models": "Models",
   "usage.section.providers": "Nhà cung cấp",
   "usage.section.coverage": "Chi tiết độ phủ (Coverage breakdown)",
+  "usage.section.companion": "Thanh menu và widget",
+  "usage.companion.title": "Thanh menu và widget",
+  "usage.companion.description": "Các cài đặt ở đây điều khiển ứng dụng máy tính/thanh menu OpenCodex và widget của ứng dụng.",
+  "usage.companion.installGuide": "Hướng dẫn cài đặt",
+  "usage.companion.loading": "Đang tải dòng thời gian…",
+  "usage.companion.timelineUnavailable": "Không có dòng thời gian",
+  "usage.companion.empty": "Không có lượt dùng trong {hours} giờ qua",
+  "usage.companion.chartLabel": "Dòng thời gian sử dụng",
+  "usage.companion.olderRecordsSkipped": "Đã bỏ qua các bản ghi cũ hơn",
+  "usage.companion.settingsUnavailable": "Không có cài đặt companion",
+  "usage.companion.corrupt": "Tệp cài đặt companion bị hỏng. Các điều khiển hiển thị giá trị mặc định; việc lưu bị tạm dừng cho đến khi bạn thay thế tệp.",
+  "usage.companion.corruptReset": "Thay thế bằng mặc định",
+  "usage.companion.saved": "Đã lưu · {time}",
+  "usage.companion.saveFailed": "Không thể lưu: {error}",
+  "usage.companion.reset": "Đặt lại mặc định",
+  "usage.companion.footer": "Widget hiển thị số yêu cầu, token và chi phí hôm nay cùng biểu đồ được cấu hình ở đây, rồi làm mới khi ứng dụng thăm dò.",
+  "usage.companion.menuBarShows": "Thanh menu hiển thị",
+  "usage.companion.menuRequests": "Yêu cầu",
+  "usage.companion.menuTokens": "Token",
+  "usage.companion.menuCost": "Chi phí",
+  "usage.companion.menuQuota": "Hạn mức",
+  "usage.companion.menuNone": "Chỉ biểu tượng",
+  "usage.companion.window": "Khoảng thời gian",
+  "usage.companion.window6": "6 giờ",
+  "usage.companion.window24": "24 giờ",
+  "usage.companion.window72": "3 ngày",
+  "usage.companion.window168": "7 ngày",
+  "usage.companion.style": "Kiểu",
+  "usage.companion.styleLine": "Đường",
+  "usage.companion.styleStacked": "Xếp chồng",
+  "usage.companion.metric": "Chỉ số",
+  "usage.companion.metricTotal": "Tổng",
+  "usage.companion.metricInput": "Đầu vào",
+  "usage.companion.metricOutput": "Đầu ra",
+  "usage.companion.metricCached": "Đã lưu đệm",
+  "usage.companion.groupBy": "Nhóm theo",
+  "usage.companion.groupModel": "Mô hình",
+  "usage.companion.groupAccount": "Mô hình + tài khoản",
+  "usage.companion.popoverSections": "Mục popover",
+  "usage.companion.sectionToday": "Hôm nay",
+  "usage.companion.sectionChart": "Biểu đồ",
+  "usage.companion.sectionModels": "Mô hình",
+  "usage.companion.sectionCost": "Chi phí",
+  "usage.companion.sectionAccounts": "Tài khoản",
+  "usage.companion.advanced": "Nâng cao",
+  "usage.companion.aggregation": "Tổng hợp",
+  "usage.companion.aggregationSum": "Tổng",
+  "usage.companion.aggregationAverage": "Trung bình",
+  "usage.companion.aggregationMax": "Tối đa",
+  "usage.companion.menuText": "Văn bản thanh menu",
+  "usage.companion.placeholders": "Trình giữ chỗ:",
+  "usage.companion.modelsOnChart": "Mô hình trên biểu đồ",
+  "usage.companion.connected": "Ứng dụng trên thanh menu đã kết nối · {age}",
+  "usage.companion.connectedDesktop": "Ứng dụng máy tính đã kết nối · {age}",
+  "usage.companion.installTitle": "Cài đặt ứng dụng máy tính",
+  "usage.companion.installOs": "Hệ điều hành",
+  "usage.companion.osMac": "macOS",
+  "usage.companion.osWindows": "Windows",
+  "usage.companion.osLinux": "Linux",
+  "usage.companion.runningInDesktop": "Bạn đang ở trong ứng dụng máy tính OpenCodex {version}",
+  "usage.companion.openInBrowser": "Mở trong trình duyệt",
+  "usage.companion.installMacStep1": "Tải OpenCodex-<version>-macos.dmg từ bản phát hành mới nhất và kéo OpenCodex.app vào Applications.",
+  "usage.companion.installMacStep2": "Lần đầu mở: nhấp chuột phải vào OpenCodex.app → Mở (Gatekeeper sẽ hỏi một lần cho đến khi ứng dụng được công chứng).",
+  "usage.companion.installMacStep3": "Ứng dụng tự tìm proxy này; widget xuất hiện trong thư viện widget sau khi ứng dụng chạy.",
+  "usage.companion.installWinStep1": "Tải OpenCodex-<version>-windows-x64.msi từ bản phát hành mới nhất và chạy trình cài đặt.",
+  "usage.companion.installWinStep2": "Nếu SmartScreen cảnh báo, chọn Thông tin thêm → Vẫn chạy (trình cài đặt chưa được ký mã).",
+  "usage.companion.installWinStep3": "OpenCodex xuất hiện trong khay hệ thống và kết nối proxy này, hoặc khởi chạy proxy đi kèm.",
+  "usage.companion.installLinuxStep1": "Tải OpenCodex-<version>-linux-x86_64.AppImage (hoặc .deb) từ bản phát hành mới nhất.",
+  "usage.companion.installLinuxStep2": "Chạy chmod +x cho AppImage rồi mở; biểu tượng khay cần môi trường desktop hỗ trợ AppIndicator.",
+  "usage.companion.installLinuxStep3": "Ứng dụng kết nối proxy này hoặc khởi chạy proxy đi kèm.",
+  "usage.companion.notConnected": "Chưa có ứng dụng trên thanh menu nào kết nối với proxy này.",
+  "usage.companion.lastSeen": "Lần kết nối gần nhất {age}",
+  "usage.companion.installAnother": "Cài đặt trên thiết bị khác",
+  "usage.companion.modelsCount": "{selected}/{total} trên biểu đồ",
+  "usage.companion.modelsShowAll": "Hiện tất cả",
+  "usage.companion.hideProviders": "Ẩn nhà cung cấp",
   "usage.workspace.report": "Báo cáo sử dụng",
   "usage.workspace.sections": "Các phần sử dụng",
   "usage.coverage.measured": "Đã đo",
@@ -1003,6 +1122,14 @@ export const vi: Record<TKey, string> = {
   "usage.col.requests": "Yêu cầu",
   "usage.col.measured": "Đã đo",
   "usage.col.reported": "Đã báo cáo",
+  "usage.col.inputTokens": "Token đầu vào",
+  "usage.col.outputTokens": "Token đầu ra",
+  "usage.col.cacheHits": "Lượt truy cập cache",
+  "usage.col.cacheWrites": "Lần ghi cache",
+  "usage.col.cacheHitRate": "Tỷ lệ truy cập cache",
+  "usage.cacheHitRate.partial": "Giá trị trung bình được tính dựa trên {measured} trong tổng số {total} token đầu vào; các yêu cầu còn lại không cung cấp thông tin chi tiết về cache.",
+  "usage.cacheHitRate.unmeasured": "Không có yêu cầu nào trong hàng này cung cấp thông tin chi tiết về cache, nên không thể tính tỷ lệ truy cập cache trung bình.",
+  "usage.unavailable": "—",
   "usage.col.tokens": "Tokens",
   "usage.col.apiListPrice": "Giá niêm yết API",
   "usage.col.share": "Tỷ trọng",
@@ -1846,6 +1973,7 @@ export const vi: Record<TKey, string> = {
   "integrations.status.installed": "Đã cài đặt",
   "integrations.status.notInstalled": "Chưa cài đặt",
   "integrations.status.appliedAt": "Đã áp dụng",
+  "integrations.status.supersededStore": "Máy khách này hiện đọc danh sách nhà cung cấp từ {path}, tệp mà opencodex không ghi, nên bật ở đây sẽ không thay đổi những gì nó tải.",
   "integrations.status.backup": "Sao lưu",
   "integrations.status.lastRestore": "Lần khôi phục cuối",
   "integrations.status.unknown": "Không xác định",
@@ -1906,6 +2034,7 @@ export const vi: Record<TKey, string> = {
   "integrations.plan.refusal.conflict": "Cài đặt được quản lý xung đột với tệp hiện tại. Hãy xem lại tệp hoặc dùng Thay thế khi có thể.",
   "integrations.plan.refusal.unsafe": "Không thể thay đổi cấu hình máy khách một cách an toàn. Hãy sửa hoặc thay tệp trước khi thử lại.",
   "integrations.plan.refusal.nonLoopback": "Máy khách này cần địa chỉ proxy loopback. Hãy dùng localhost, đường hầm hoặc chuyển tiếp cục bộ.",
+  "integrations.plan.refusal.supersededStore": "Máy khách này đọc danh sách nhà cung cấp từ một tệp mà opencodex không ghi, nên thao tác này sẽ không thay đổi những gì nó tải.",
   "integrations.plan.refusal.driftRequiresConfirm": "Tệp đã thay đổi sau điểm khôi phục này. Hãy xem kế hoạch có tính đến thay đổi trước khi khôi phục.",
   "integrations.plan.refusal.snapshotExpired": "Bản sao lưu cho điểm khôi phục này đã hết hạn nên không thể khôi phục nữa.",
   "integrations.plan.refusal.writeFailed": "Máy chủ không thể chuẩn bị thao tác ghi an toàn. Hãy làm mới trạng thái tích hợp trước khi thử lại.",
@@ -2109,6 +2238,7 @@ export const vi: Record<TKey, string> = {
   "accountPool.priorityUpdateFailed": "Không thể lưu thứ tự lựa chọn cho {email}. Giá trị được xác nhận gần nhất đang được hiển thị.",
   "codexAuth.switched": "Tài khoản được chọn cho request tiếp theo là {email}",
   "codexAuth.loadFailed": "Không thể tải cài đặt tài khoản Codex.",
+  "codexAuth.accountsRefreshFailed": "Lần làm mới tài khoản gần nhất thất bại. Dưới đây là các tài khoản được xác nhận gần nhất.",
   "codexAuth.switchExceedsThresholdWarning": "Mức sử dụng của tài khoản này đã đạt hoặc vượt ngưỡng chuyển đổi ({threshold}%). Lựa chọn đã ghim sẽ được giải phóng nếu không còn hạn ngạch khả dụng.",
   "codexAuth.switchFailed": "Không thể chuyển đổi tài khoản. Tùy chọn trước đó của bạn vẫn được giữ nguyên.",
   "codexAuth.removeConfirm": "Gỡ bỏ {id}?",
@@ -2647,6 +2777,19 @@ export const vi: Record<TKey, string> = {
   "claudeDesktop.status.notActiveProfile": "Desktop đang phục vụ một hồ sơ khác — hãy áp dụng lại",
   "claudeDesktop.status.disabled": "Tiện ích tích hợp Claude Desktop đang tắt. Hãy thoát hoàn toàn và mở lại Desktop sau khi bật nó.",
   "claudeDesktop.enableApply": "Bật và áp dụng",
+  "claudeDesktop.switchModeApply": "Đổi chế độ & áp dụng",
+  "claudeDesktop.status.appliedFirstParty": "First-party: tab Code đi qua proxy cục bộ",
+  "claudeDesktop.mode.legend": "Chế độ kết nối",
+  "claudeDesktop.mode.firstParty": "First-party",
+  "claudeDesktop.mode.gateway": "Gateway (bên thứ ba)",
+  "claudeDesktop.mode.defaultBadge": "mặc định",
+  "claudeDesktop.mode.current": "hiện tại",
+  "claudeDesktop.mode.firstPartyHint": "Desktop vẫn đăng nhập claude.ai (chat, connector, điều khiển từ xa). Chỉ tab Code, các subagent và Claude Code CLI đi qua OpenCodex.",
+  "claudeDesktop.mode.gatewayHint": "Toàn bộ ứng dụng chuyển sang dùng OpenCodex làm gateway. Chat chạy cục bộ; các tính năng claude.ai không khả dụng.",
+  "claudeDesktop.mode.switchNote": "Chuyển chế độ sẽ xóa cấu hình của chế độ kia. Sau đó hãy thoát hẳn Desktop rồi mở lại.",
+  "claudeDesktop.firstParty.proxyRunning": "Proxy cục bộ tại 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "Proxy cục bộ 127.0.0.1:{port} không chạy — khởi động lại OpenCodex",
+  "claudeDesktop.firstParty.interceptDisabled": "Proxy chặn bắt đã bị tắt trong cấu hình (claudeCode.intercept.enabled)",
   "claudeDesktop.health.lastRequest": "Yêu cầu cuối cùng (Last request)",
   "claudeDesktop.health.stats": "{count} req / {errors} err",
   "claudeDesktop.effort.supported": "suy luận (effort)",
diff --git a/gui/src/i18n/zh-TW.ts b/gui/src/i18n/zh-TW.ts
index cb4513ba7ef..b447f4dbcbd 100644
--- a/gui/src/i18n/zh-TW.ts
+++ b/gui/src/i18n/zh-TW.ts
@@ -221,6 +221,8 @@ export const zhTW: Record<TKey, string> = {
   "dash.stop": "停止代理",
   "dash.stopConfirm": "停止代理並恢復原生 Codex 配置？",
   "dash.stopFailed": "無法停止代理 (HTTP {status})。",
+  "dash.stopStillRunning": "代理仍在回應，未能停止。",
+  "dash.stopUnknown": "無法確認是否已停止。請先檢查代理是否仍在執行，再重試。",
   "dash.maSwitchFailed": "模式切換失敗 (HTTP {status})。",
   "dash.maNetworkError": "網路錯誤 — 代理是否正在執行？",
   "dash.stopping": "正在停止…",
@@ -265,7 +267,7 @@ export const zhTW: Record<TKey, string> = {
   "compactionRouting.dataNotice": "涵蓋的壓縮請求會將整個對話傳送給所選模型的供應商進行摘要，即使對話正在其他供應商上執行。",
   "compactionRouting.autoNotice": "自動壓縮會自行觸發，因此長對話可能在你沒有主動要求的情況下被傳送給該供應商。",
   "compactionRouting.providerWarning": "啟用此設定後，每個涵蓋的壓縮請求都會將完整對話內容傳送給 {provider} 進行摘要。",
-  "compactionRouting.comboWarning": "啟用此設定後，每個涵蓋的壓縮請求都會將完整對話內容傳送給組合 {combo} 的每個目標（{providers}），包括容錯移轉目標，以進行摘要。",
+  "compactionRouting.comboWarning": "啟用此設定後，每個涵蓋的壓縮請求都會將完整對話內容傳送給組合 {combo} 以進行摘要。該組合會依序嘗試其目標（{providers}），並使用第一個回應的目標，因此其中任一個都可能收到該對話。",
   "compactionRouting.comboProvidersUnknown": "其已設定的目標供應商",
   "compactionRouting.loadFailed": "無法載入壓縮設定。",
   "compactionRouting.saved": "壓縮設定已儲存。",
@@ -358,6 +360,7 @@ export const zhTW: Record<TKey, string> = {
   "prov.aliasPrompt": "顯示名稱（留空以清除）",
   "prov.aliasSaved": "別名已儲存",
   "prov.aliasSaveFailed": "無法儲存別名",
+  "prov.aliasInvalid": "請使用最多 80 個字元，且不含控制字元。",
   "prov.accountId": "ID",
   "prov.pasteRedirect": "貼上重定向 URL 或授權碼",
   "prov.pasteRedirectHint": "如果瀏覽器顯示 localhost 錯誤，請複製位址列中的完整 URL 並貼上到此處（或貼上授權碼）。",
@@ -812,6 +815,82 @@ export const zhTW: Record<TKey, string> = {
   "usage.section.models": "模型",
   "usage.section.providers": "供應商",
   "usage.section.coverage": "覆蓋率明細",
+  "usage.section.companion": "選單列與小工具",
+  "usage.companion.title": "選單列與小工具",
+  "usage.companion.description": "這裡的設定會控制 OpenCodex 桌面／選單列 App 與其小工具。",
+  "usage.companion.installGuide": "安裝指南",
+  "usage.companion.loading": "正在載入時間軸…",
+  "usage.companion.timelineUnavailable": "時間軸無法使用",
+  "usage.companion.empty": "過去 {hours} 小時沒有使用量",
+  "usage.companion.chartLabel": "使用量時間軸",
+  "usage.companion.olderRecordsSkipped": "已略過較早記錄",
+  "usage.companion.settingsUnavailable": "伴隨設定無法使用",
+  "usage.companion.corrupt": "伴隨設定檔已損毀。控制項顯示預設值；在替換檔案前將暫停儲存。",
+  "usage.companion.corruptReset": "替換為預設值",
+  "usage.companion.saved": "已儲存 · {time}",
+  "usage.companion.saveFailed": "無法儲存：{error}",
+  "usage.companion.reset": "重設為預設值",
+  "usage.companion.footer": "小工具會顯示今天的請求、權杖和費用，以及此處設定的圖表，並在 App 輪詢時重新整理。",
+  "usage.companion.menuBarShows": "選單列顯示",
+  "usage.companion.menuRequests": "要求",
+  "usage.companion.menuTokens": "權杖",
+  "usage.companion.menuCost": "成本",
+  "usage.companion.menuQuota": "配額",
+  "usage.companion.menuNone": "僅圖示",
+  "usage.companion.window": "時間範圍",
+  "usage.companion.window6": "6 小時",
+  "usage.companion.window24": "24 小時",
+  "usage.companion.window72": "3 天",
+  "usage.companion.window168": "7 天",
+  "usage.companion.style": "樣式",
+  "usage.companion.styleLine": "折線",
+  "usage.companion.styleStacked": "堆疊",
+  "usage.companion.metric": "指標",
+  "usage.companion.metricTotal": "總計",
+  "usage.companion.metricInput": "輸入",
+  "usage.companion.metricOutput": "輸出",
+  "usage.companion.metricCached": "快取",
+  "usage.companion.groupBy": "分組依據",
+  "usage.companion.groupModel": "模型",
+  "usage.companion.groupAccount": "模型 + 帳戶",
+  "usage.companion.popoverSections": "彈出視窗區段",
+  "usage.companion.sectionToday": "今天",
+  "usage.companion.sectionChart": "圖表",
+  "usage.companion.sectionModels": "模型",
+  "usage.companion.sectionCost": "成本",
+  "usage.companion.sectionAccounts": "帳戶",
+  "usage.companion.advanced": "進階",
+  "usage.companion.aggregation": "彙總",
+  "usage.companion.aggregationSum": "總和",
+  "usage.companion.aggregationAverage": "平均",
+  "usage.companion.aggregationMax": "最大值",
+  "usage.companion.menuText": "選單列文字",
+  "usage.companion.placeholders": "預留位置：",
+  "usage.companion.modelsOnChart": "圖表中的模型",
+  "usage.companion.connected": "選單列 App 已連線 · {age}",
+  "usage.companion.connectedDesktop": "桌面 App 已連線 · {age}",
+  "usage.companion.installTitle": "安裝桌面 App",
+  "usage.companion.installOs": "作業系統",
+  "usage.companion.osMac": "macOS 系統",
+  "usage.companion.osWindows": "Windows 系統",
+  "usage.companion.osLinux": "Linux 系統",
+  "usage.companion.runningInDesktop": "你正在使用 OpenCodex 桌面 App {version}",
+  "usage.companion.openInBrowser": "在瀏覽器中開啟",
+  "usage.companion.installMacStep1": "從最新版本下載 OpenCodex-<version>-macos.dmg，並將 OpenCodex.app 拖到應用程式。",
+  "usage.companion.installMacStep2": "首次啟動：在 OpenCodex.app 上按右鍵並選擇「開啟」（App 完成公證前，Gatekeeper 只會詢問一次）。",
+  "usage.companion.installMacStep3": "App 會自動找到此 Proxy；App 執行後，Widget 會出現在 Widget 圖庫中。",
+  "usage.companion.installWinStep1": "從最新版本下載 OpenCodex-<version>-windows-x64.msi 並執行。",
+  "usage.companion.installWinStep2": "如果 SmartScreen 發出警告，請選擇「更多資訊」→「仍要執行」（安裝程式尚未完成程式碼簽署）。",
+  "usage.companion.installWinStep3": "OpenCodex 會出現在系統匣並連線此 Proxy，或啟動內建 Proxy。",
+  "usage.companion.installLinuxStep1": "從最新版本下載 OpenCodex-<version>-linux-x86_64.AppImage（或 .deb）。",
+  "usage.companion.installLinuxStep2": "對 AppImage 執行 chmod +x 後啟動；系統匣圖示需要支援 AppIndicator 的桌面環境。",
+  "usage.companion.installLinuxStep3": "App 會連線此 Proxy，或啟動內建 Proxy。",
+  "usage.companion.notConnected": "尚未有選單列 App 連線到此 Proxy。",
+  "usage.companion.lastSeen": "上次連線 {age}",
+  "usage.companion.installAnother": "在另一台裝置上安裝",
+  "usage.companion.modelsCount": "圖表顯示 {selected}/{total}",
+  "usage.companion.modelsShowAll": "顯示全部",
+  "usage.companion.hideProviders": "隱藏提供者",
   "usage.coverage.measured": "已計量",
   "usage.coverage.reported": "供應商上報",
   "usage.coverage.estimated": "估算",
@@ -820,6 +899,14 @@ export const zhTW: Record<TKey, string> = {
   "usage.col.requests": "請求數",
   "usage.col.measured": "已計量",
   "usage.col.reported": "已上報",
+  "usage.col.inputTokens": "輸入 Token",
+  "usage.col.outputTokens": "輸出 Token",
+  "usage.col.cacheHits": "快取命中",
+  "usage.col.cacheWrites": "快取寫入",
+  "usage.col.cacheHitRate": "命中率",
+  "usage.cacheHitRate.partial": "全部 {total} 個輸入 Token 中，有 {measured} 個提供了快取明細，命中率取這些資料的平均值；其餘請求未回報快取明細。",
+  "usage.cacheHitRate.unmeasured": "此資料列的所有請求都未回報快取明細，因此無法計算平均命中率。",
+  "usage.unavailable": "—",
   "usage.col.tokens": "Token 數",
   "usage.col.apiListPrice": "API 標價",
   "usage.col.share": "佔比",
@@ -1587,6 +1674,7 @@ export const zhTW: Record<TKey, string> = {
   "accountPool.quotaWindowInert": "只有配額策略，或門檻大於 0 的填滿優先策略，才會依用量計分；在目前的輪換策略下，這項設定不會有任何作用。",
   "codexAuth.switched": "下一次請求將使用 {email}",
   "codexAuth.loadFailed": "無法載入 Codex 帳號設定。",
+  "codexAuth.accountsRefreshFailed": "最近一次帳號重新整理失敗。以下是最後一次確認的帳號。",
   "codexAuth.switchFailed": "無法切換帳號。之前的選擇保持不變。",
   "codexAuth.removeConfirm": "刪除 {id}？",
   "codexAuth.removeFailed": "無法移除帳號。未進行任何更改。",
@@ -2313,7 +2401,47 @@ export const zhTW: Record<TKey, string> = {
   "logs.detail.attempt.recovery.image413": "圖片承載過大 (413)",
   "logs.detail.attempt.recovery.emptyCompletion": "空白完成重試",
   "logs.detail.attempt.recovery.consoleGoUpload": "Console 上傳重試",
+  "logs.detail.attempt.recovery.key401": "API 金鑰重新驗證",
+  "logs.detail.attempt.recovery.oauthAccount429": "帳號速率受限 (429)",
+  "logs.detail.attempt.recovery.opaqueBlobRejection": "已捨棄過期加密狀態",
+  "logs.detail.attempt.recovery.reasoningEffortDowngrade": "已降低推理強度",
+  "logs.detail.outcome.label": "結果",
+  "logs.detail.outcome.completed": "已完成",
+  "logs.detail.outcome.failed": "失敗",
+  "logs.detail.outcome.incomplete": "未完成",
+  "logs.detail.outcome.aborted": "已中止",
+  "logs.detail.sends.label": "上游傳送次數",
+  "logs.detail.sends.unresolved": "未結算",
   "logs.detail.attempt.recovery.unknown": "未知的復原原因",
+  "logs.detail.cause.label": "失敗原因",
+  "logs.detail.stage.label": "到達階段",
+  "logs.detail.resend.label": "重送",
+  "logs.detail.cause.transportUnsent": "未傳送至上游",
+  "logs.detail.cause.transportAmbiguous": "連線中斷，上游狀態不明",
+  "logs.detail.cause.upstreamDeclined": "上游拒絕開始",
+  "logs.detail.cause.rateLimit": "速率受限",
+  "logs.detail.cause.quotaExhausted": "配額耗盡",
+  "logs.detail.cause.credentialRejected": "憑證遭拒",
+  "logs.detail.cause.policyRefusal": "遭內容政策拒絕",
+  "logs.detail.cause.parameterRejected": "請求參數遭拒",
+  "logs.detail.cause.ciphertextRefusal": "加密狀態遭拒",
+  "logs.detail.cause.payloadTooLarge": "酬載過大",
+  "logs.detail.cause.payloadRejected": "酬載遭拒",
+  "logs.detail.cause.upstreamFault": "上游故障",
+  "logs.detail.cause.emptyOutput": "沒有可用輸出",
+  "logs.detail.cause.clientCancelled": "用戶端已取消",
+  "logs.detail.cause.localRefusal": "遭此代理拒絕",
+  "logs.detail.stage.preHeader": "無回應標頭",
+  "logs.detail.stage.headersOnly": "僅標頭",
+  "logs.detail.stage.protocolPrelude": "協定前導",
+  "logs.detail.stage.semanticOutput": "已傳遞輸出",
+  "logs.detail.stage.sideEffect": "已產生副作用",
+  "logs.detail.stage.terminal": "已傳遞答覆",
+  "logs.detail.resend.permitted": "可以重送",
+  "logs.detail.resend.permittedAfterRepair": "修復後可以重送",
+  "logs.detail.resend.refusedAmbiguous": "未重送：上游狀態不明",
+  "logs.detail.resend.refusedCommitted": "未重送：呼叫端已收到輸出",
+  "logs.detail.resend.refusedFutile": "未重送：相同請求仍會失敗",
   "logs.detail.estimate.provider_cost_overlay": "已使用供應商設定的價格覆蓋。",
   "logs.detail.estimate.priority_lower_bound": "無法取得已確認的 Priority 價格；目前顯示的估算是已知下限。",
   "pws.cockpitImportDescription": "從此裝置匯入 Cockpit Tools Antigravity JSON 匯出檔。不會顯示檔案內容。",
@@ -2483,6 +2611,7 @@ export const zhTW: Record<TKey, string> = {
   "integrations.status.installed": "已安裝",
   "integrations.status.notInstalled": "未安裝",
   "integrations.status.appliedAt": "已套用",
+  "integrations.status.supersededStore": "此用戶端現在從 {path} 讀取供應商，而 opencodex 不會寫入該檔案，因此在這裡啟用不會改變它載入的內容。",
   "integrations.status.backup": "備份",
   "integrations.status.lastRestore": "上次還原",
   "integrations.status.unknown": "未知",
@@ -2543,6 +2672,7 @@ export const zhTW: Record<TKey, string> = {
   "integrations.plan.refusal.conflict": "受管理的設定與目前檔案衝突。請檢查檔案，或在可用時使用「替換」。",
   "integrations.plan.refusal.unsafe": "無法安全地變更用戶端設定。請修復或替換檔案後再試一次。",
   "integrations.plan.refusal.nonLoopback": "此用戶端需要迴路代理位址。請使用 localhost、通道或本機轉送後再試一次。",
+  "integrations.plan.refusal.supersededStore": "此用戶端從 opencodex 不會寫入的檔案讀取供應商，因此這項操作不會改變它載入的內容。",
   "integrations.plan.refusal.driftRequiresConfirm": "檔案在此回復點後已變更。請先檢視包含變更的計畫再還原。",
   "integrations.plan.refusal.snapshotExpired": "此回復點的備份已過期，無法再還原。",
   "integrations.plan.refusal.writeFailed": "伺服器無法準備安全寫入。請重新整理整合狀態後再試一次。",
@@ -2625,6 +2755,19 @@ export const zhTW: Record<TKey, string> = {
   "claudeDesktop.appliedMarkerUnsaved": "已套用到 Claude Desktop，但套用標記未能儲存 — 在你再次套用之前，下方的已儲存／已套用狀態可能顯示過時資訊。",
   "claudeDesktop.status.disabled": "Claude Desktop 整合已關閉。啟用後請完全結束並重新開啟 Desktop。",
   "claudeDesktop.enableApply": "啟用並套用",
+  "claudeDesktop.switchModeApply": "切換模式並套用",
+  "claudeDesktop.status.appliedFirstParty": "第一方：Code 分頁經由本機代理",
+  "claudeDesktop.mode.legend": "連線模式",
+  "claudeDesktop.mode.firstParty": "第一方",
+  "claudeDesktop.mode.gateway": "閘道（第三方）",
+  "claudeDesktop.mode.defaultBadge": "預設",
+  "claudeDesktop.mode.current": "目前",
+  "claudeDesktop.mode.firstPartyHint": "Desktop 維持登入 claude.ai（聊天、連接器、遠端控制）。僅 Code 分頁、其子代理與 Claude Code CLI 經由 OpenCodex。",
+  "claudeDesktop.mode.gatewayHint": "整個應用程式改用 OpenCodex 作為閘道。聊天在本機執行；claude.ai 功能無法使用。",
+  "claudeDesktop.mode.switchNote": "切換會移除另一模式的設定。套用後請完全結束並重新開啟 Desktop。",
+  "claudeDesktop.firstParty.proxyRunning": "本機代理 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "本機代理 127.0.0.1:{port} 未執行 — 請重新啟動 OpenCodex",
+  "claudeDesktop.firstParty.interceptDisabled": "設定中已停用攔截代理（claudeCode.intercept.enabled）",
   "lab.title": "相容性實驗室",
   "lab.subtitle": "以實驗室投影證據為基礎的唯讀相容性判定矩陣。",
   "lab.loadFailed": "無法載入相容性實驗室資料",
diff --git a/gui/src/i18n/zh.ts b/gui/src/i18n/zh.ts
index aa5049f34ce..533d21000f9 100644
--- a/gui/src/i18n/zh.ts
+++ b/gui/src/i18n/zh.ts
@@ -326,6 +326,8 @@ export const zh: Record<TKey, string> = {
   "dash.stop": "停止代理",
   "dash.stopConfirm": "停止代理并恢复原生 Codex 配置？",
   "dash.stopFailed": "无法停止代理 (HTTP {status})。",
+  "dash.stopStillRunning": "代理仍在响应，未能停止。",
+  "dash.stopUnknown": "无法确认是否已停止。请先检查代理是否仍在运行，再重试。",
   "dash.maSwitchFailed": "模式切换失败 (HTTP {status})。",
   "dash.maNetworkError": "网络错误 — 代理是否正在运行？",
   "dash.stopping": "正在停止…",
@@ -370,7 +372,7 @@ export const zh: Record<TKey, string> = {
   "compactionRouting.dataNotice": "被覆盖的压缩请求会将整个对话发送给所选模型的提供商进行摘要，即使对话正在其他提供商上运行。",
   "compactionRouting.autoNotice": "自动压缩会自行触发，因此长对话可能在你没有主动要求的情况下被发送给该提供商。",
   "compactionRouting.providerWarning": "启用此设置后，每个被覆盖的压缩请求都会将完整对话内容发送给 {provider} 进行摘要。",
-  "compactionRouting.comboWarning": "启用此设置后，每个被覆盖的压缩请求都会将完整对话内容发送给组合 {combo} 的每个目标（{providers}），包括故障转移目标，以进行摘要。",
+  "compactionRouting.comboWarning": "启用此设置后，每个被覆盖的压缩请求都会将完整对话内容发送给组合 {combo} 以进行摘要。该组合会按顺序尝试其目标（{providers}），并使用第一个响应的目标，因此其中任意一个都可能收到该对话。",
   "compactionRouting.comboProvidersUnknown": "其已配置的目标提供商",
   "compactionRouting.loadFailed": "无法加载压缩设置。",
   "compactionRouting.saved": "压缩设置已保存。",
@@ -467,6 +469,7 @@ export const zh: Record<TKey, string> = {
   "prov.aliasPrompt": "显示名称（留空以清除）",
   "prov.aliasSaved": "别名已保存",
   "prov.aliasSaveFailed": "无法保存别名",
+  "prov.aliasInvalid": "请使用最多 80 个字符，且不含控制字符。",
   "prov.accountId": "ID",
   "prov.pasteRedirect": "粘贴重定向 URL 或授权码",
   "prov.pasteRedirectHint": "如果浏览器显示 localhost 错误，请复制地址栏中的完整 URL 并粘贴到此处（或粘贴授权码）。",
@@ -885,7 +888,47 @@ export const zh: Record<TKey, string> = {
   "logs.detail.attempt.recovery.image413": "图片载荷过大 (413)",
   "logs.detail.attempt.recovery.emptyCompletion": "空完成重试",
   "logs.detail.attempt.recovery.consoleGoUpload": "Console 上传重试",
+  "logs.detail.attempt.recovery.key401": "API 密钥重新认证",
+  "logs.detail.attempt.recovery.oauthAccount429": "账号速率受限 (429)",
+  "logs.detail.attempt.recovery.opaqueBlobRejection": "已丢弃过期加密状态",
+  "logs.detail.attempt.recovery.reasoningEffortDowngrade": "已降低推理强度",
+  "logs.detail.outcome.label": "结果",
+  "logs.detail.outcome.completed": "已完成",
+  "logs.detail.outcome.failed": "失败",
+  "logs.detail.outcome.incomplete": "未完成",
+  "logs.detail.outcome.aborted": "已中止",
+  "logs.detail.sends.label": "上游发送次数",
+  "logs.detail.sends.unresolved": "未结算",
   "logs.detail.attempt.recovery.unknown": "未知的恢复原因",
+  "logs.detail.cause.label": "失败原因",
+  "logs.detail.stage.label": "到达阶段",
+  "logs.detail.resend.label": "重发",
+  "logs.detail.cause.transportUnsent": "未发送到上游",
+  "logs.detail.cause.transportAmbiguous": "连接中断，上游状态未知",
+  "logs.detail.cause.upstreamDeclined": "上游拒绝开始",
+  "logs.detail.cause.rateLimit": "速率受限",
+  "logs.detail.cause.quotaExhausted": "配额耗尽",
+  "logs.detail.cause.credentialRejected": "凭据被拒绝",
+  "logs.detail.cause.policyRefusal": "被内容策略拒绝",
+  "logs.detail.cause.parameterRejected": "请求参数被拒绝",
+  "logs.detail.cause.ciphertextRefusal": "加密状态被拒绝",
+  "logs.detail.cause.payloadTooLarge": "负载过大",
+  "logs.detail.cause.payloadRejected": "负载被拒绝",
+  "logs.detail.cause.upstreamFault": "上游故障",
+  "logs.detail.cause.emptyOutput": "没有可用输出",
+  "logs.detail.cause.clientCancelled": "客户端已取消",
+  "logs.detail.cause.localRefusal": "被此代理拒绝",
+  "logs.detail.stage.preHeader": "无响应头",
+  "logs.detail.stage.headersOnly": "仅响应头",
+  "logs.detail.stage.protocolPrelude": "协议前导",
+  "logs.detail.stage.semanticOutput": "已交付输出",
+  "logs.detail.stage.sideEffect": "已产生副作用",
+  "logs.detail.stage.terminal": "已交付答复",
+  "logs.detail.resend.permitted": "可以重发",
+  "logs.detail.resend.permittedAfterRepair": "修复后可以重发",
+  "logs.detail.resend.refusedAmbiguous": "未重发：上游状态未知",
+  "logs.detail.resend.refusedCommitted": "未重发：调用方已收到输出",
+  "logs.detail.resend.refusedFutile": "未重发：相同请求仍会失败",
   "logs.detail.reason.usage_missing": "未上报 usage。",
   "logs.detail.reason.usage_unsupported": "该提供方不支持上报 usage。",
   "logs.detail.reason.output_missing": "未上报正数输出 token。",
@@ -985,6 +1028,82 @@ export const zh: Record<TKey, string> = {
   "usage.section.models": "模型",
   "usage.section.providers": "提供方",
   "usage.section.coverage": "覆盖率明细",
+  "usage.section.companion": "菜单栏与小组件",
+  "usage.companion.title": "菜单栏与小组件",
+  "usage.companion.description": "这里的设置会控制 OpenCodex 桌面/菜单栏应用及其小组件。",
+  "usage.companion.installGuide": "安装指南",
+  "usage.companion.loading": "正在加载时间线…",
+  "usage.companion.timelineUnavailable": "时间线不可用",
+  "usage.companion.empty": "过去 {hours} 小时没有使用记录",
+  "usage.companion.chartLabel": "使用量时间线",
+  "usage.companion.olderRecordsSkipped": "已跳过较早记录",
+  "usage.companion.settingsUnavailable": "伴侣设置不可用",
+  "usage.companion.corrupt": "伴侣设置文件已损坏。控件显示默认值；替换文件前将暂停保存。",
+  "usage.companion.corruptReset": "替换为默认值",
+  "usage.companion.saved": "已保存 · {time}",
+  "usage.companion.saveFailed": "保存失败：{error}",
+  "usage.companion.reset": "恢复默认设置",
+  "usage.companion.footer": "小组件显示今天的请求数、令牌数和费用，以及此处配置的图表，并在应用轮询时刷新。",
+  "usage.companion.menuBarShows": "菜单栏显示",
+  "usage.companion.menuRequests": "请求",
+  "usage.companion.menuTokens": "令牌",
+  "usage.companion.menuCost": "费用",
+  "usage.companion.menuQuota": "配额",
+  "usage.companion.menuNone": "仅图标",
+  "usage.companion.window": "时间范围",
+  "usage.companion.window6": "6 小时",
+  "usage.companion.window24": "24 小时",
+  "usage.companion.window72": "3 天",
+  "usage.companion.window168": "7 天",
+  "usage.companion.style": "样式",
+  "usage.companion.styleLine": "折线",
+  "usage.companion.styleStacked": "堆叠",
+  "usage.companion.metric": "指标",
+  "usage.companion.metricTotal": "总计",
+  "usage.companion.metricInput": "输入",
+  "usage.companion.metricOutput": "输出",
+  "usage.companion.metricCached": "缓存",
+  "usage.companion.groupBy": "分组依据",
+  "usage.companion.groupModel": "模型",
+  "usage.companion.groupAccount": "模型 + 账户",
+  "usage.companion.popoverSections": "弹出窗口部分",
+  "usage.companion.sectionToday": "今天",
+  "usage.companion.sectionChart": "图表",
+  "usage.companion.sectionModels": "模型",
+  "usage.companion.sectionCost": "费用",
+  "usage.companion.sectionAccounts": "账户",
+  "usage.companion.advanced": "高级",
+  "usage.companion.aggregation": "聚合",
+  "usage.companion.aggregationSum": "总和",
+  "usage.companion.aggregationAverage": "平均",
+  "usage.companion.aggregationMax": "最大值",
+  "usage.companion.menuText": "菜单栏文本",
+  "usage.companion.placeholders": "占位符：",
+  "usage.companion.modelsOnChart": "图表中的模型",
+  "usage.companion.connected": "菜单栏应用已连接 · {age}",
+  "usage.companion.connectedDesktop": "桌面应用已连接 · {age}",
+  "usage.companion.installTitle": "安装桌面应用",
+  "usage.companion.installOs": "操作系统",
+  "usage.companion.osMac": "macOS",
+  "usage.companion.osWindows": "Windows",
+  "usage.companion.osLinux": "Linux",
+  "usage.companion.runningInDesktop": "你正在使用 OpenCodex 桌面应用 {version}",
+  "usage.companion.openInBrowser": "在浏览器中打开",
+  "usage.companion.installMacStep1": "从最新版本下载 OpenCodex-<version>-macos.dmg，并将 OpenCodex.app 拖到应用程序。",
+  "usage.companion.installMacStep2": "首次启动：右键点击 OpenCodex.app 并选择“打开”（应用完成公证前，Gatekeeper 只会询问一次）。",
+  "usage.companion.installMacStep3": "应用会自动找到此代理；应用运行后，小组件会出现在小组件图库中。",
+  "usage.companion.installWinStep1": "从最新版本下载 OpenCodex-<version>-windows-x64.msi 并运行。",
+  "usage.companion.installWinStep2": "如果 SmartScreen 发出警告，请选择“更多信息”→“仍要运行”（安装程序尚未经过代码签名）。",
+  "usage.companion.installWinStep3": "OpenCodex 会出现在系统托盘中并连接此代理，或启动内置代理。",
+  "usage.companion.installLinuxStep1": "从最新版本下载 OpenCodex-<version>-linux-x86_64.AppImage（或 .deb）。",
+  "usage.companion.installLinuxStep2": "对 AppImage 执行 chmod +x 后运行；托盘图标需要支持 AppIndicator 的桌面环境。",
+  "usage.companion.installLinuxStep3": "应用会连接此代理，或启动内置代理。",
+  "usage.companion.notConnected": "尚未有菜单栏应用连接到此代理。",
+  "usage.companion.lastSeen": "上次连接 {age}",
+  "usage.companion.installAnother": "在另一台设备上安装",
+  "usage.companion.modelsCount": "图表显示 {selected}/{total}",
+  "usage.companion.modelsShowAll": "显示全部",
+  "usage.companion.hideProviders": "隐藏提供商",
   "usage.workspace.report": "用量报告",
   "usage.workspace.sections": "用量分区",
   "usage.coverage.measured": "已计量",
@@ -995,6 +1114,14 @@ export const zh: Record<TKey, string> = {
   "usage.col.requests": "请求数",
   "usage.col.measured": "已计量",
   "usage.col.reported": "已上报",
+  "usage.col.inputTokens": "输入 Token",
+  "usage.col.outputTokens": "输出 Token",
+  "usage.col.cacheHits": "缓存命中",
+  "usage.col.cacheWrites": "缓存写入",
+  "usage.col.cacheHitRate": "命中率",
+  "usage.cacheHitRate.partial": "全部 {total} 个输入 Token 中，有 {measured} 个提供了缓存明细，命中率取这些数据的平均值；其余请求未报告缓存明细。",
+  "usage.cacheHitRate.unmeasured": "此行没有任何请求报告缓存明细，因此无法计算平均命中率。",
+  "usage.unavailable": "—",
   "usage.col.tokens": "Token 数",
   "usage.col.apiListPrice": "API 标价",
   "usage.col.share": "占比",
@@ -1326,6 +1453,7 @@ export const zh: Record<TKey, string> = {
   "integrations.status.installed": "已安装",
   "integrations.status.notInstalled": "未安装",
   "integrations.status.appliedAt": "已应用",
+  "integrations.status.supersededStore": "此客户端现在从 {path} 读取提供方，而 opencodex 不写入该文件，因此在这里启用不会改变它加载的内容。",
   "integrations.status.backup": "备份",
   "integrations.status.lastRestore": "上次恢复",
   "integrations.status.unknown": "未知",
@@ -1386,6 +1514,7 @@ export const zh: Record<TKey, string> = {
   "integrations.plan.refusal.conflict": "托管设置与当前文件冲突。请检查文件，或在可用时使用“替换”。",
   "integrations.plan.refusal.unsafe": "无法安全地更改客户端配置。请修复或替换文件后重试。",
   "integrations.plan.refusal.nonLoopback": "此客户端需要环回代理地址。请使用 localhost、隧道或本地转发后重试。",
+  "integrations.plan.refusal.supersededStore": "此客户端从 opencodex 不写入的文件读取提供方，因此该操作不会改变它加载的内容。",
   "integrations.plan.refusal.driftRequiresConfirm": "文件在此回滚点后发生了变化。请先查看包含变化的计划再恢复。",
   "integrations.plan.refusal.snapshotExpired": "此回滚点的备份已过期，无法再恢复。",
   "integrations.plan.refusal.writeFailed": "服务器无法准备安全写入。请刷新集成状态后重试。",
@@ -1594,6 +1723,7 @@ export const zh: Record<TKey, string> = {
   "accountPool.priorityUpdateFailed": "无法保存 {email} 的选择顺序。当前显示最后一次确认的值。",
   "codexAuth.switched": "下一次请求将使用 {email}",
   "codexAuth.loadFailed": "无法加载 Codex 账号设置。",
+  "codexAuth.accountsRefreshFailed": "最近一次账号刷新失败。以下是最后一次确认的账号。",
   "codexAuth.switchFailed": "无法切换账户。之前的选择保持不变。",
   "codexAuth.removeConfirm": "删除 {id}？",
   "codexAuth.removeFailed": "无法移除账户。未进行任何更改。",
@@ -2636,6 +2766,19 @@ export const zh: Record<TKey, string> = {
   "claudeDesktop.status.notActiveProfile": "Desktop 正在使用其他配置 — 请重新应用",
   "claudeDesktop.status.disabled": "Claude Desktop 集成已关闭。开启后请完全退出并重新打开 Desktop。",
   "claudeDesktop.enableApply": "开启并应用",
+  "claudeDesktop.switchModeApply": "切换模式并应用",
+  "claudeDesktop.status.appliedFirstParty": "第一方：Code 标签页经由本地代理",
+  "claudeDesktop.mode.legend": "连接模式",
+  "claudeDesktop.mode.firstParty": "第一方",
+  "claudeDesktop.mode.gateway": "网关（第三方）",
+  "claudeDesktop.mode.defaultBadge": "默认",
+  "claudeDesktop.mode.current": "当前",
+  "claudeDesktop.mode.firstPartyHint": "Desktop 保持登录 claude.ai（聊天、连接器、远程控制）。仅 Code 标签页、其子代理和 Claude Code CLI 经由 OpenCodex。",
+  "claudeDesktop.mode.gatewayHint": "整个应用改用 OpenCodex 作为网关。聊天在本地运行；claude.ai 功能不可用。",
+  "claudeDesktop.mode.switchNote": "切换会移除另一模式的配置。应用后请完全退出并重新打开 Desktop。",
+  "claudeDesktop.firstParty.proxyRunning": "本地代理 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "本地代理 127.0.0.1:{port} 未运行 — 请重启 OpenCodex",
+  "claudeDesktop.firstParty.interceptDisabled": "配置中已禁用拦截代理（claudeCode.intercept.enabled）",
   "claudeDesktop.health.lastRequest": "最后请求",
   "claudeDesktop.health.stats": "{count} 请求 / {errors} 错误",
   "claudeDesktop.effort.supported": "effort",
diff --git a/gui/src/lib/desktop-shell.ts b/gui/src/lib/desktop-shell.ts
new file mode 100644
index 00000000000..f6301ee1192
--- /dev/null
+++ b/gui/src/lib/desktop-shell.ts
@@ -0,0 +1,32 @@
+export type HostOs = "macos" | "windows" | "linux" | "unknown";
+
+function currentUserAgent(): string {
+  return typeof navigator === "undefined" ? "" : navigator.userAgent;
+}
+
+export function desktopShellVersion(ua = currentUserAgent()): string | null {
+  return ua.match(/OpenCodexDesktop\/(\S+)/)?.[1] ?? null;
+}
+
+export function isDesktopShell(ua = currentUserAgent()): boolean {
+  return desktopShellVersion(ua) !== null;
+}
+
+export function hostOs(ua = currentUserAgent()): HostOs {
+  if (/Windows/i.test(ua)) return "windows";
+  if (/Mac OS X|Macintosh/i.test(ua)) return "macos";
+  if (/Linux|X11/i.test(ua) && !/Android/i.test(ua)) return "linux";
+  return "unknown";
+}
+
+export function isExternalLink(
+  href: string,
+  origin = typeof location === "undefined" ? "" : location.origin,
+): boolean {
+  if (!/^https?:\/\//i.test(href)) return false;
+  try {
+    return new URL(href).origin !== origin;
+  } catch {
+    return false;
+  }
+}
diff --git a/gui/src/main.tsx b/gui/src/main.tsx
index 362c5bb351d..a5228663be1 100644
--- a/gui/src/main.tsx
+++ b/gui/src/main.tsx
@@ -6,6 +6,7 @@ import "./styles.css";
 import "./styles/usage-chart-accessibility.css";
 import "./styles/sidebar-brand.css";
 import "./styles/fast-rows-setting.css";
+import "./styles/claude-desktop-mode-picker.css";
 
 ReactDOM.createRoot(document.getElementById("root")!).render(
   <React.StrictMode>
diff --git a/gui/src/pages/ClaudeDesktop.tsx b/gui/src/pages/ClaudeDesktop.tsx
index 3878f7d5b42..f360a48ade5 100644
--- a/gui/src/pages/ClaudeDesktop.tsx
+++ b/gui/src/pages/ClaudeDesktop.tsx
@@ -42,8 +42,23 @@ interface DesktopModel {
   assignment: Assignment;
 }
 
+type DesktopMode = "first-party" | "gateway";
+const DESKTOP_MODES: readonly DesktopMode[] = ["first-party", "gateway"];
+
+interface DesktopFirstPartyStatus {
+  applied: boolean;
+  stale: boolean;
+  interceptEnabled: boolean;
+  interceptRunning: boolean;
+  proxyPort: number;
+  caCertPath: string;
+}
+
 interface DesktopStatus {
   desiredEnabled: boolean;
+  /** Effective mode: a gateway profile on disk wins; otherwise the saved/default mode. */
+  mode?: DesktopMode;
+  firstParty?: DesktopFirstPartyStatus;
   applied: boolean;
   appliedAt: string | null;
   stale: boolean;
@@ -65,6 +80,14 @@ function isDesktopStatus(value: unknown): value is DesktopStatus {
   if (typeof value !== "object" || value === null) return false;
   const v = value as Record<string, unknown>;
   const health = v.health as Record<string, unknown> | null | undefined;
+  if (v.mode !== undefined && !DESKTOP_MODES.includes(v.mode as DesktopMode)) return false;
+  if (v.firstParty !== undefined) {
+    const fp = v.firstParty as Record<string, unknown> | null;
+    if (typeof fp !== "object" || fp === null
+      || typeof fp.applied !== "boolean" || typeof fp.stale !== "boolean"
+      || typeof fp.interceptEnabled !== "boolean" || typeof fp.interceptRunning !== "boolean"
+      || typeof fp.proxyPort !== "number" || typeof fp.caCertPath !== "string") return false;
+  }
   return typeof v.desiredEnabled === "boolean"
     && typeof v.applied === "boolean"
     && (v.appliedAt === null || typeof v.appliedAt === "string")
@@ -201,6 +224,9 @@ export default function ClaudeDesktop({
   // a family's fold is a durable preference, but which single model you were inspecting
   // is not, and restoring five open rows on reload would rebuild the wall this removes.
   const [openRows, setOpenRows] = useState<Record<string, boolean>>({});
+  // The mode the user wants the next apply to use. null = follow whatever /status reports
+  // (first-party by default), so a page load never silently changes an existing install.
+  const [chosenMode, setChosenMode] = useState<DesktopMode | null>(null);
   const importRef = useRef<HTMLInputElement>(null);
   const fetchDesktop = useCallback(async (signal: AbortSignal): Promise<CachedDesktop> => {
     const response = await fetch(`${apiBase}/api/claude-desktop`, { signal });
@@ -309,6 +335,15 @@ export default function ClaudeDesktop({
   const statusState = statusResource.state;
   const status = statusState.data ?? cachedStatus;
   const statusFailed = statusState.showError;
+  // Until /status answers, the effective mode is unknown: the picker renders unchecked and
+  // disabled instead of flashing the first-party default at a gateway install. A confirmed
+  // /status failure unlocks it (the status bar already shows the error) so an apply can still
+  // be attempted, but no "current" badge is claimed.
+  const modeKnown = status !== null;
+  const modePickable = modeKnown || statusFailed;
+  const effectiveMode: DesktopMode = status?.mode ?? "first-party";
+  const selectedMode: DesktopMode = chosenMode ?? effectiveMode;
+  const modeDirty = modeKnown && selectedMode !== effectiveMode;
 
   const moveModel = (route: string, family: Family) => {
     if (!profile || profile.assignments[route]?.family === family) return;
@@ -353,7 +388,11 @@ export default function ClaudeDesktop({
 
       if (applyAfter) {
         setPending("apply");
-        const applyResponse = await fetch(`${apiBase}/api/claude-desktop/apply`, { method: "POST" });
+        const applyResponse = await fetch(`${apiBase}/api/claude-desktop/apply`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ mode: selectedMode }),
+        });
         const applyBody = await readJsonOrThrow<{ error?: string; saved?: boolean; warning?: string }>(
           applyResponse,
           t("claudeDesktop.applyFailed"),
@@ -368,6 +407,7 @@ export default function ClaudeDesktop({
           setMessage({ tone: "ok", text: t("claudeDesktop.savedApplied") });
           setAnnouncement(t("claudeDesktop.savedAppliedAnnounce"));
         }
+        setChosenMode(null);
       } else {
         setMessage({ tone: "ok", text: t("claudeDesktop.saved") });
         setAnnouncement(t("claudeDesktop.savedAnnounce"));
@@ -445,6 +485,30 @@ export default function ClaudeDesktop({
         </div>
       </div>
 
+      <fieldset className="claude-mode-picker" disabled={pending !== null || !modePickable}>
+        <legend>{t("claudeDesktop.mode.legend")}</legend>
+        {DESKTOP_MODES.map(mode => (
+          <label key={mode} className={`claude-mode-option${modePickable && selectedMode === mode ? " active" : ""}`}>
+            <input
+              type="radio"
+              name="claude-desktop-mode"
+              value={mode}
+              checked={modePickable && selectedMode === mode}
+              onChange={() => setChosenMode(mode)}
+            />
+            <span className="claude-mode-title">
+              {mode === "first-party" ? t("claudeDesktop.mode.firstParty") : t("claudeDesktop.mode.gateway")}
+              {mode === "first-party" && <span className="claude-mode-default">{t("claudeDesktop.mode.defaultBadge")}</span>}
+              {modeKnown && effectiveMode === mode && <span className="claude-mode-current">{t("claudeDesktop.mode.current")}</span>}
+            </span>
+            <span className="claude-mode-hint">
+              {mode === "first-party" ? t("claudeDesktop.mode.firstPartyHint") : t("claudeDesktop.mode.gatewayHint")}
+            </span>
+          </label>
+        ))}
+        {modeDirty && <span className="claude-mode-switch-note">{t("claudeDesktop.mode.switchNote")}</span>}
+      </fieldset>
+
       {/* Always mount the bar (pending strut when status is still cold) so a late /status
           response cannot insert a full row under the title and shove the lanes down. */}
       <div
@@ -455,7 +519,7 @@ export default function ClaudeDesktop({
               ? "pending"
               : !status.desiredEnabled
                 ? "not-applied"
-              : status.activeProfile === false
+              : effectiveMode === "gateway" && status.activeProfile === false
                 ? "not-applied"
                 : status.stale
                   ? "stale"
@@ -467,7 +531,8 @@ export default function ClaudeDesktop({
       >
         <span className="claude-status-dot" />
         {/* Desktop serving another profile outranks content drift: stale config that is
-            read still works, a config that is never read does not. */}
+            read still works, a config that is never read does not. First-party never
+            writes a Desktop profile, so that check only applies in gateway mode. */}
         <span>
           {statusFailed && !status
             ? t("claudeDesktop.loadFail")
@@ -475,14 +540,23 @@ export default function ClaudeDesktop({
               ? t("claudeDesktop.loading")
               : !status.desiredEnabled
                 ? t("claudeDesktop.status.disabled")
-              : status.activeProfile === false
+              : effectiveMode === "gateway" && status.activeProfile === false
                 ? t("claudeDesktop.status.notActiveProfile")
                 : status.stale
                   ? t("claudeDesktop.status.stale")
                   : status.applied
-                    ? t("claudeDesktop.status.applied")
+                    ? effectiveMode === "first-party" ? t("claudeDesktop.status.appliedFirstParty") : t("claudeDesktop.status.applied")
                     : t("claudeDesktop.status.notApplied")}
         </span>
+        {status?.firstParty && effectiveMode === "first-party" && status.desiredEnabled && (
+          <span className="claude-status-health">
+            {status.firstParty.interceptRunning
+              ? t("claudeDesktop.firstParty.proxyRunning", { port: status.firstParty.proxyPort })
+              : status.firstParty.interceptEnabled
+                ? t("claudeDesktop.firstParty.proxyStopped", { port: status.firstParty.proxyPort })
+                : t("claudeDesktop.firstParty.interceptDisabled")}
+          </span>
+        )}
         {status?.health.lastRequestAt && (
           <span className="claude-status-health">
             {t("claudeDesktop.health.lastRequest")}:{" "}
@@ -508,7 +582,7 @@ export default function ClaudeDesktop({
             {pending === "save" ? t("claudeDesktop.saving") : t("common.save")}
           </button>
           <button type="button" className="btn btn-primary" disabled={pending !== null} onClick={() => void save(true)}>
-            {pending === "apply" ? t("claudeDesktop.applying") : pending === "save" ? t("claudeDesktop.saving") : status?.desiredEnabled === false ? t("claudeDesktop.enableApply") : t("claudeDesktop.saveApply")}
+            {pending === "apply" ? t("claudeDesktop.applying") : pending === "save" ? t("claudeDesktop.saving") : status?.desiredEnabled === false ? t("claudeDesktop.enableApply") : modeDirty ? t("claudeDesktop.switchModeApply") : t("claudeDesktop.saveApply")}
           </button>
         </div>
       </div>
diff --git a/gui/src/pages/Logs.tsx b/gui/src/pages/Logs.tsx
index d7fc3ab5c49..9f55f37e45d 100644
--- a/gui/src/pages/Logs.tsx
+++ b/gui/src/pages/Logs.tsx
@@ -28,6 +28,19 @@ import {
   validCachedRouteDecision,
 } from "./log-route-decision";
 import { mergeLogDelta, parseLogPollResponse } from "./log-poll";
+import type {
+  AttemptRecoveryKind,
+  RequestFailureCause,
+  RequestFailureStage,
+  RequestSpendTotals,
+  ResendPermission,
+} from "../../../src/usage/telemetry-contract";
+import {
+  classifyRequestOutcome,
+  requestPhysicalSends,
+  requestUnresolvedSends,
+  type RequestOutcomeClass,
+} from "../../../src/usage/request-outcome";
 
 function logsCacheKey(apiBase: string): string {
   return `ocx.logs.list.v1:${apiBase}`;
@@ -102,21 +115,20 @@ interface LogDisplayMetrics {
 }
 
 /**
- * Recovery kinds recorded on a log attempt; rendered as localized labels in the logs
- * detail dialog instead of raw wire values.
+ * The durable attribution and the verdict the API derives from it.
+ *
+ * `resendPermission` arrives computed rather than stored: the tables that decide it live in the
+ * proxy and a row must not be able to assert a permission the current tables would refuse. The
+ * page renders the answer and derives nothing of its own, which is the same rule that keeps the
+ * outcome class agreeing with the exporter.
  */
-type AttemptRecoveryKind =
-  | "transient-5xx"
-  | "connection-reset"
-  | "oauth-401"
-  | "key-429"
-  | "rate-limit-429"
-  | "anthropic-oauth-429"
-  | "image-413"
-  | "empty-completion"
-  | "console-go-upload-retry";
-
-interface LogAttempt {
+interface LogFailureAttribution {
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
+  resendPermission?: ResendPermission;
+}
+
+interface LogAttempt extends LogFailureAttribution {
   ordinal: number;
   provider: string;
   model: string;
@@ -138,7 +150,7 @@ interface LogAttempt {
   displayMetrics?: LogDisplayMetrics;
 }
 
-export interface LogEntry {
+export interface LogEntry extends LogFailureAttribution {
   requestId?: string;
   timestamp: number;
   model: string;
@@ -172,6 +184,15 @@ export interface LogEntry {
   durationMs: number;
   errorCode?: string;
   upstreamError?: string;
+  /**
+   * Semantic terminal facts. `/api/logs` has always carried these -- `requestLogDto` spreads the
+   * whole durable entry -- but this page declared neither, so it classified every request by its
+   * numeric HTTP status alone and reported an incomplete 200 as a plain success.
+   */
+  terminalStatus?: string;
+  closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow";
+  /** Upstream spend for the whole logical request, aggregated across attempts and combo children. */
+  spend?: RequestSpendTotals;
   usageStatus?: LogUsageStatus;
   usage?: UsageBreakdown;
   totalTokens?: number;
@@ -298,17 +319,27 @@ const ESTIMATE_REASON_KEYS = {
 /**
  * i18n keys for every {@link AttemptRecoveryKind}, so the logs detail dialog renders a
  * localized label instead of the raw wire value (e.g. `rate-limit-429`).
+ *
+ * The union is now the durable roster rather than a copy of it. The copy had drifted to nine of
+ * thirteen members, so `key-401`, `oauth-account-429`, `opaque-blob-rejection` and
+ * `reasoning-effort-downgrade` all reached the operator as "Unknown recovery reason" -- four real
+ * causes rendered as an absence of information. `satisfies Record<AttemptRecoveryKind, string>` is
+ * what now makes the next added kind a typecheck failure here instead of a silent blank.
  */
 const RECOVERY_KIND_KEYS = {
   "transient-5xx": "logs.detail.attempt.recovery.transient5xx",
   "connection-reset": "logs.detail.attempt.recovery.connectionReset",
   "oauth-401": "logs.detail.attempt.recovery.oauth401",
+  "key-401": "logs.detail.attempt.recovery.key401",
   "key-429": "logs.detail.attempt.recovery.key429",
   "rate-limit-429": "logs.detail.attempt.recovery.rateLimit429",
   "anthropic-oauth-429": "logs.detail.attempt.recovery.anthropicOauth429",
+  "oauth-account-429": "logs.detail.attempt.recovery.oauthAccount429",
   "image-413": "logs.detail.attempt.recovery.image413",
   "empty-completion": "logs.detail.attempt.recovery.emptyCompletion",
   "console-go-upload-retry": "logs.detail.attempt.recovery.consoleGoUpload",
+  "opaque-blob-rejection": "logs.detail.attempt.recovery.opaqueBlobRejection",
+  "reasoning-effort-downgrade": "logs.detail.attempt.recovery.reasoningEffortDowngrade",
 } as const satisfies Record<AttemptRecoveryKind, string>;
 
 /** Map a metric-unavailable reason to its i18n key. */
@@ -334,6 +365,91 @@ function verificationKey(status: MatchedPriceInfo["status"]): "logs.detail.verif
   return status === "verified" ? "logs.detail.verification.verified" : "logs.detail.verification.derived";
 }
 
+/** i18n key for each shared outcome class, total by construction. */
+const OUTCOME_KEYS = {
+  completed: "logs.detail.outcome.completed",
+  failed: "logs.detail.outcome.failed",
+  incomplete: "logs.detail.outcome.incomplete",
+  aborted: "logs.detail.outcome.aborted",
+} as const satisfies Record<RequestOutcomeClass, string>;
+
+/**
+ * i18n key for each shared failure cause, total by construction.
+ *
+ * The `satisfies` clause is the point. The recovery-kind catalog on this page drifted to nine of
+ * the durable thirteen and four real causes reached the operator as "Unknown recovery reason" --
+ * an absence of a label rendered as an absence of a cause. A missing member here is a typecheck
+ * failure instead.
+ */
+const FAILURE_CAUSE_KEYS = {
+  "transport-unsent": "logs.detail.cause.transportUnsent",
+  "transport-ambiguous": "logs.detail.cause.transportAmbiguous",
+  "upstream-declined": "logs.detail.cause.upstreamDeclined",
+  "rate-limit": "logs.detail.cause.rateLimit",
+  "quota-exhausted": "logs.detail.cause.quotaExhausted",
+  "credential-rejected": "logs.detail.cause.credentialRejected",
+  "policy-refusal": "logs.detail.cause.policyRefusal",
+  "parameter-rejected": "logs.detail.cause.parameterRejected",
+  "ciphertext-refusal": "logs.detail.cause.ciphertextRefusal",
+  "payload-too-large": "logs.detail.cause.payloadTooLarge",
+  "payload-rejected": "logs.detail.cause.payloadRejected",
+  "upstream-fault": "logs.detail.cause.upstreamFault",
+  "empty-output": "logs.detail.cause.emptyOutput",
+  "client-cancelled": "logs.detail.cause.clientCancelled",
+  "local-refusal": "logs.detail.cause.localRefusal",
+} as const satisfies Record<RequestFailureCause, string>;
+
+/** i18n key for each stage the caller's view of the exchange reached. */
+const FAILURE_STAGE_KEYS = {
+  "pre-header": "logs.detail.stage.preHeader",
+  "headers-only": "logs.detail.stage.headersOnly",
+  "protocol-prelude": "logs.detail.stage.protocolPrelude",
+  "semantic-output": "logs.detail.stage.semanticOutput",
+  "side-effect": "logs.detail.stage.sideEffect",
+  "terminal": "logs.detail.stage.terminal",
+} as const satisfies Record<RequestFailureStage, string>;
+
+/** i18n key for each resend verdict; every refusal names which refusal it is. */
+const RESEND_PERMISSION_KEYS = {
+  "permitted": "logs.detail.resend.permitted",
+  "permitted-after-repair": "logs.detail.resend.permittedAfterRepair",
+  "refused-ambiguous": "logs.detail.resend.refusedAmbiguous",
+  "refused-committed": "logs.detail.resend.refusedCommitted",
+  "refused-futile": "logs.detail.resend.refusedFutile",
+} as const satisfies Record<ResendPermission, string>;
+
+/**
+ * How this request ended, using the same classifier the Prometheus exporter uses.
+ *
+ * Calling the shared function rather than reimplementing the precedence is the point: the numeric
+ * status beside it can be 200 while the answer was never delivered, and reading the status first
+ * is exactly the disagreement this removes.
+ */
+function outcomeKey(entry: Pick<LogEntry, "status" | "terminalStatus" | "closeReason">) {
+  return OUTCOME_KEYS[classifyRequestOutcome(entry)];
+}
+
+/**
+ * Localized cause, stage and resend verdict for a row that carries them.
+ *
+ * A stale or hand-edited row can carry a value outside the roster, so each lookup falls back to
+ * the wire value rather than handing `t()` an undefined key. Showing the raw member is more
+ * useful than showing nothing, which is the mistake the recovery catalog made.
+ */
+function failureAttributionLabels(
+  row: LogFailureAttribution,
+  t: TFn,
+): { cause?: string; stage?: string; resend?: string } {
+  const causeKey = row.failureCause === undefined ? undefined : FAILURE_CAUSE_KEYS[row.failureCause];
+  const stageKey = row.failureStage === undefined ? undefined : FAILURE_STAGE_KEYS[row.failureStage];
+  const resendKey = row.resendPermission === undefined ? undefined : RESEND_PERMISSION_KEYS[row.resendPermission];
+  return {
+    ...(row.failureCause ? { cause: causeKey ? t(causeKey) : row.failureCause } : {}),
+    ...(row.failureStage ? { stage: stageKey ? t(stageKey) : row.failureStage } : {}),
+    ...(row.resendPermission ? { resend: resendKey ? t(resendKey) : row.resendPermission } : {}),
+  };
+}
+
 function statusColor(status: number): string {
   if (status >= 200 && status < 300) return "var(--green)";
   if (status >= 400) return "var(--red)";
@@ -937,6 +1053,7 @@ function LogDetailDialog({
   const tokenSplit = cacheSplit(detail);
   const cost = detail.displayMetrics?.cost;
   const reasoningWire = reasoningWireLabel(detail);
+  const detailFailure = failureAttributionLabels(detail, t);
 
   const copyRequestId = async () => {
     if (!detail.requestId) return;
@@ -971,6 +1088,33 @@ function LogDetailDialog({
           <h4 id="log-detail-basic" className="log-detail-section-title">{t("logs.detail.section.basic")}</h4>
           <div className="log-detail-grid">
             <span className="muted">{t("logs.col.time")}</span><span className="mono">{formatLogDateTime(detail.timestamp, localeTag, serverTimeZone)}</span>
+            <span className="muted">{t("logs.detail.outcome.label")}</span>
+            <span>{t(outcomeKey(detail))}</span>
+            {detailFailure.cause && (
+              <>
+                <span className="muted">{t("logs.detail.cause.label")}</span>
+                <span>
+                  {detailFailure.cause}
+                  {detailFailure.stage && ` (${t("logs.detail.stage.label")}: ${detailFailure.stage})`}
+                </span>
+              </>
+            )}
+            {detailFailure.resend && (
+              <>
+                <span className="muted">{t("logs.detail.resend.label")}</span>
+                <span>{detailFailure.resend}</span>
+              </>
+            )}
+            {detail.spend && (
+              <>
+                <span className="muted">{t("logs.detail.sends.label")}</span>
+                <span className="mono">
+                  {requestPhysicalSends(detail.spend)}
+                  {requestUnresolvedSends(detail.spend) > 0
+                    && ` (${t("logs.detail.sends.unresolved")}: ${requestUnresolvedSends(detail.spend)})`}
+                </span>
+              </>
+            )}
             <span className="muted">{t("logs.col.request")}</span>
             <span className="log-detail-request-row">
               <span className="mono log-detail-break">{detail.requestId ?? "\u2014"}</span>
@@ -1121,7 +1265,13 @@ function LogDetailDialog({
                   const attemptCost = attempt.displayMetrics?.cost;
                   const attemptReasoningWire = reasoningWireLabel(attempt);
                   const matched = attemptCost?.kind === "value" ? attemptCost.estimate.price : undefined;
-                  const reason = attempt.errorCode
+                  const attemptFailure = failureAttributionLabels(attempt, t);
+                  // The derived cause leads, because it is the one value in this row that says
+                  // WHY in a vocabulary an operator can act on. `errorCode` stays behind it
+                  // rather than being dropped: it is the exact wire code, which is what a bug
+                  // report needs.
+                  const reason = attemptFailure.cause
+                    ?? attempt.errorCode
                     ?? (attempt.recoveryKinds.length
                       ? attempt.recoveryKinds.map(kind => t(recoveryKindKey(kind))).join(", ")
                       : undefined)
diff --git a/gui/src/pages/Models.tsx b/gui/src/pages/Models.tsx
index c9c8ddb5736..7d099bd877f 100644
--- a/gui/src/pages/Models.tsx
+++ b/gui/src/pages/Models.tsx
@@ -5,8 +5,10 @@ import ModelPriceDialog from "../components/ModelPriceDialog";
 import { fetchCodexAppServerState } from "../codex-app-server-state";
 import type { AppServerStateOutcome } from "../codex-app-server-state";
 import { useCodexRestart } from "../use-codex-restart";
+import { confirmAction } from "../action-dialogs";
+import { editModelAlias, editProviderAlias } from "./models-alias-editing";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { Switch, Notice, EmptyState, Select, Tooltip } from "../ui";
+import { Switch, Notice, EmptyState, Select, Tooltip, type NoticeTone } from "../ui";
 import { IconChevron, IconBoxes, IconInfo, IconCheck, IconAlert, IconRefresh, IconPencil } from "../icons";
 import { useT } from "../i18n/shared";
 import type { TFn, TKey } from "../i18n/shared";
@@ -140,7 +142,7 @@ interface AliasView {
   defaults: { global: boolean; providers: Record<string, boolean> };
 }
 
-export default function Models({ apiBase, restartEpoch = 0, catalogSyncedAt }: { apiBase: string; restartEpoch?: number; catalogSyncedAt?: string }) {
+export default function Models({ apiBase, restartEpoch = 0, catalogSyncedAt, reportRestart }: { apiBase: string; restartEpoch?: number; catalogSyncedAt?: string; reportRestart: (message: string, tone: NoticeTone) => void }) {
   // Codex app-server staleness (devlog/_fin/260815_gui_codex_restart). Named
   // appServerState, not catalogState: this file already binds that name to the
   // model-catalog resource state, which is an unrelated concept. (Spelling the
@@ -188,6 +190,10 @@ export default function Models({ apiBase, restartEpoch = 0, catalogSyncedAt }: {
   // this page, and a restart succeeding there must still clear the banner here.
   const { restarting: codexRestarting, restart: handleCodexRestart } = useCodexRestart(apiBase, {
     onSettled: () => { void reloadAppServerState(); },
+    // Reported through the shell, not this page's toast: a restart takes up to 30s and
+    // outlives a navigation away, and an outcome that says app-servers are still running
+    // must not be discarded because the user moved on while waiting for it.
+    report: reportRestart,
   });
 
   useEffect(() => {
@@ -380,29 +386,11 @@ export default function Models({ apiBase, restartEpoch = 0, catalogSyncedAt }: {
     return () => controller.abort();
   }, [reloadAliases]);
 
-  const saveProviderAlias = async (provider: string) => {
-    const entered = window.prompt(t("models.aliasPrompt"), aliases.providers[provider] ?? "");
-    if (entered === null) return;
-    const response = await fetch(`${apiBase}/api/providers/${encodeURIComponent(provider)}/alias`, {
-      method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify({ alias: entered.trim() || null }),
-    });
-    if (!response.ok) { publishFeedback(false, t("models.aliasConflict")); return; }
-    await reloadAliases();
-    publishFeedback(true, t("models.aliasSaved"));
-  };
-
-  const saveModelAlias = async (provider: string, model: string) => {
-    const current = aliases.models[provider]?.[model]?.alias ?? "";
-    const entered = window.prompt(t("models.modelAliasPrompt"), current);
-    if (entered === null) return;
-    const body = entered.trim() ? { set: { [model]: entered.trim() } } : { remove: [model] };
-    const response = await fetch(`${apiBase}/api/providers/${encodeURIComponent(provider)}/model-aliases`, {
-      method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
-    });
-    if (!response.ok) { publishFeedback(false, t("models.aliasConflict")); return; }
-    await reloadAliases();
-    publishFeedback(true, t("models.aliasSaved"));
-  };
+  const aliasEditingDeps = { apiBase, t, reloadAliases, publishFeedback };
+  const saveProviderAlias = (provider: string) =>
+    editProviderAlias(provider, aliases.providers[provider] ?? "", aliasEditingDeps);
+  const saveModelAlias = (provider: string, model: string) =>
+    editModelAlias(provider, model, aliases.models[provider]?.[model]?.alias ?? "", aliasEditingDeps);
 
   const setDefaultAliases = async (enabled: boolean, provider?: string) => {
     const response = await fetch(`${apiBase}/api/default-aliases`, {
@@ -1196,7 +1184,12 @@ export default function Models({ apiBase, restartEpoch = 0, catalogSyncedAt }: {
     await Promise.all([loadModelDiscovery(), load()]);
   };
 
-  const applyPreset = async (provider: string, mode: "preset" | "all") => {
+  const applyPreset = async (provider: string, mode: "preset" | "all", replacing?: { presetCount: number }) => {
+    // Consent lives with the write, not with the button, so every caller is gated.
+    if (replacing && !(await confirmAction({
+      message: t("models.presetConfirmReplace", { count: String(replacing.presetCount) }),
+      tone: "danger",
+    }))) return;
     if (catalogMutationRef.current) return;
     catalogMutationRef.current = true;
     setPresetBusy(provider);
@@ -1367,7 +1360,8 @@ export default function Models({ apiBase, restartEpoch = 0, catalogSyncedAt }: {
     }
   };
 
-  const deleteCustomModel = async (id: string) => {
+  const deleteCustomModel = async (id: string, name: string) => {
+    if (!(await confirmAction({ message: t("models.customDeleteConfirm", { name }), confirmLabel: t("common.delete"), tone: "danger" }))) return;
     try {
       const r = await fetch(`${apiBase}/api/custom-models/${encodeURIComponent(id)}`, { method: "DELETE" });
       if (r.ok) {
@@ -1553,13 +1547,11 @@ export default function Models({ apiBase, restartEpoch = 0, catalogSyncedAt }: {
                            color: preset.mode === mode ? undefined : "var(--muted)",
                          }}
                          disabled={busy || busyHere || selectionPending}
-                         onClick={(e) => {
-                           e.stopPropagation();
-                           // Switching from a custom selection destroys it, so confirm first.
-                           if (mode === "preset" && preset.mode === "custom"
-                             && !confirm(t("models.presetConfirmReplace", { count: String(preset.presetCount) }))) return;
-                           void applyPreset(provider, mode);
-                         }}
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          // Switching from a custom selection destroys it, so consent first.
+                          void applyPreset(provider, mode, mode === "preset" && preset.mode === "custom" ? preset : undefined);
+                        }}
                        >
                          {t(`models.presetMode_${mode}` as TKey)}
                        </button>
@@ -1867,12 +1859,13 @@ export default function Models({ apiBase, restartEpoch = 0, catalogSyncedAt }: {
                                type="button"
                                className="btn btn-ghost btn-sm text-caption"
                                style={{ color: "var(--red)" }}
-                               onClick={() => {
-                                 if (window.confirm(t("models.customDeleteConfirm", { name: m.displayName ?? m.id }))) {
-                                   void deleteCustomModel(m.customId!);
-                                 }
-                                 setHoveredModel(null);
-                               }}
+                              onClick={() => {
+                                // Hover is cleared AFTER the dialog closes, not before it
+                                // opens: dropping it first unmounts this button, and the
+                                // dialog then has nothing to return focus to.
+                                void deleteCustomModel(m.customId!, m.displayName ?? m.id)
+                                  .finally(() => setHoveredModel(null));
+                              }}
                              >{t("models.customDelete")}</button>
                            </div>
                          )}
diff --git a/gui/src/pages/RemoteWorkspace.tsx b/gui/src/pages/RemoteWorkspace.tsx
index d6eebb3258e..928a7f7ec25 100644
--- a/gui/src/pages/RemoteWorkspace.tsx
+++ b/gui/src/pages/RemoteWorkspace.tsx
@@ -4,6 +4,7 @@ import { readJsonOrThrow } from "../fetch-json";
 import { IconLink, IconMonitor, IconPlus, IconRefresh, IconTerminal, IconTrash } from "../icons";
 import { type TKey, useT } from "../i18n/shared";
 import { Notice, Select } from "../ui";
+import { confirmAction } from "../action-dialogs";
 import { remoteWorkspacePairingCommands } from "../remote-workspace-command";
 
 type RuntimeProfile = "codex" | "claude" | "pi";
@@ -249,7 +250,7 @@ export default function RemoteWorkspace({ apiBase, hubOrigin }: { apiBase: strin
   };
 
   const revokeDevice = async (device: RemoteDevice) => {
-    if (!confirm(t("remote.revokeConfirm", { name: device.name }))) return;
+    if (!(await confirmAction({ message: t("remote.revokeConfirm", { name: device.name }), confirmLabel: t("common.remove"), tone: "danger" }))) return;
     setBusy("revoke");
     try {
       await mutate(`/api/remote-workspace/devices/${device.id}`, { method: "DELETE" }, t("remote.requestFailed"));
diff --git a/gui/src/pages/RoutingProfiles.tsx b/gui/src/pages/RoutingProfiles.tsx
index de737f803af..065df7a8153 100644
--- a/gui/src/pages/RoutingProfiles.tsx
+++ b/gui/src/pages/RoutingProfiles.tsx
@@ -18,6 +18,7 @@ import {
 } from "../routing-profile-editor-data";
 import { readJsonIfOk } from "../fetch-json";
 import { Notice } from "../ui";
+import { confirmAction } from "../action-dialogs";
 import { useI18n, useT } from "../i18n/shared";
 import { ROUTING_COMPATIBILITY_FIELD_LABELS } from "../i18n/routing-compatibility-labels";
 
@@ -486,7 +487,7 @@ export default function RoutingProfiles({
 
   const removeProfile = async () => {
     if (!selected || saving) return;
-    if (!window.confirm(t("routing.removeConfirm", { id: selected.id }))) return;
+    if (!(await confirmAction({ message: t("routing.removeConfirm", { id: selected.id }), confirmLabel: t("common.remove"), tone: "danger" }))) return;
     setSaving(true);
     setStatus(null);
     try {
diff --git a/gui/src/pages/Usage.tsx b/gui/src/pages/Usage.tsx
index de96b16e115..b645b362b40 100644
--- a/gui/src/pages/Usage.tsx
+++ b/gui/src/pages/Usage.tsx
@@ -15,6 +15,7 @@ import { DataSurfaceSkeleton } from "../components/data-surface";
 import { SectionTabs } from "../components/section-tabs";
 import { sectionAnchorId } from "../section-anchors";
 import { parseUsageTimeRange, type UsageRangeError, type UsageTimeWindow } from "../usage-time-range";
+import UsageCompanionPanel from "./usage-companion-panel";
 
 type Range = "all" | "30d" | "7d";
 type UsageSurface = "all" | "codex" | "claude" | "grok";
@@ -67,6 +68,12 @@ interface UsageModel {
   totalTokens: number;
   inputTokens: number;
   outputTokens: number;
+  cachedInputTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+  cacheHitRate?: number | null;
+  /** Input tokens whose cache detail was observed; hit rate is not model-wide below inputTokens. */
+  cacheObservedInputTokens?: number;
   /** API list-price estimate for the priced portion of this row. */
   estimatedCostUsd?: number;
   /** Requests included in the API list-price estimate. */
@@ -128,6 +135,12 @@ type UsageCostRow = Pick<UsageModel, "estimatedCostUsd" | "pricedRequests" | "un
  * Newer proxies return the coverage fields even when every request is
  * unpriced; older proxies have none of them, so their cells stay unavailable
  * rather than making an unknown amount look free.
+ *
+ * The coverage caption is `usage-cost-note`, which the stylesheet makes a block so it always
+ * begins the line under the amount instead of trailing it and folding mid-phrase. Its leading
+ * space stays in the markup: a block box drops leading white space when it lays out, so the cell
+ * reads the same either way, and the space keeps the rendered text exactly what it was for
+ * anything reading the cell as one string.
  */
 function UsageListPrice({ row, locale, t }: { row: UsageCostRow; locale: Locale; t: TFn }) {
   const hasPriceData = row.estimatedCostUsd !== undefined
@@ -145,7 +158,7 @@ function UsageListPrice({ row, locale, t }: { row: UsageCostRow; locale: Locale;
       <>
         <span className="muted">—</span>
         {excludedRequests > 0 && (
-          <span className="muted text-caption"> {excludedCaption}</span>
+          <span className="muted text-caption usage-cost-note"> {excludedCaption}</span>
         )}
       </>
     );
@@ -154,12 +167,43 @@ function UsageListPrice({ row, locale, t }: { row: UsageCostRow; locale: Locale;
     <>
       <span className="mono">{formatUsdEstimate(row.estimatedCostUsd ?? 0, locale)}</span>
       {excludedRequests > 0 && (
-        <span className="muted text-caption"> {excludedCaption}</span>
+        <span className="muted text-caption usage-cost-note"> {excludedCaption}</span>
       )}
     </>
   );
 }
 
+function formatOptionalTokens(value: number | undefined, locale: Locale, unavailable: string): string {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? formatTokens(value, locale)
+    : unavailable;
+}
+
+function formatOptionalPct(value: number | null | undefined, unavailable: string): string {
+  return typeof value === "number" && Number.isFinite(value) ? formatPct(value) : unavailable;
+}
+
+/**
+ * Why a row's hit rate covers less than its input, or why it has none at all.
+ *
+ * The rate is an average over the input tokens whose cache detail was actually reported, so a
+ * provider that reports reads and never reports writes still has one. Only a row where nothing
+ * reported cache detail has nothing to average, and that is the row that shows an em dash.
+ */
+function cacheHitRateTitle(model: UsageModel, locale: Locale, t: TFn): string | undefined {
+  if (typeof model.cacheHitRate !== "number" || !Number.isFinite(model.cacheHitRate)) {
+    return t("usage.cacheHitRate.unmeasured");
+  }
+  const observed = model.cacheObservedInputTokens;
+  if (typeof observed !== "number" || !Number.isFinite(observed) || observed >= model.inputTokens) {
+    return undefined;
+  }
+  return t("usage.cacheHitRate.partial", {
+    measured: formatTokens(observed, locale),
+    total: formatTokens(model.inputTokens, locale),
+  });
+}
+
 // Stable per-model bar color: hash the provider/model id to a hue so the same model keeps its color
 // across days and renders. Saturation/lightness are fixed for a cohesive palette on the dark chart.
 function modelColor(model: string, provider: string): string {
@@ -695,6 +739,7 @@ function UsageModelsTable({
   const sectionLabel = t("usage.section.models");
   const titleId = "usage-models-title";
   const listPriceDisclaimerId = "usage-models-list-price-disclaimer";
+  const unavailable = t("usage.unavailable");
   const searchInput = (
     <input
       className="input"
@@ -706,30 +751,61 @@ function UsageModelsTable({
   );
   const table = (
     <div className="tbl-wrap">
-      <table className="tbl">
+      {/*
+        Identity, then the three figures a reader compares models on, then the detail behind
+        them. The pair in front is also the pair the stylesheet pins while the rest scrolls
+        sideways, so their position here is load-bearing rather than cosmetic.
+      */}
+      <table className="tbl usage-models-tbl">
         <thead>
           <tr>
             <th>{t("logs.col.model")}</th>
             <th>{t("logs.col.provider")}</th>
-            <th className="num">{t("usage.col.requests")}</th>
-            <th className="num">{t("usage.col.measured")}</th>
+            <th>{t("usage.col.share")}</th>
             <th className="num">{t("usage.col.tokens")}</th>
             <th className="num" aria-describedby={listPriceDisclaimerId}>{t("usage.col.apiListPrice")}</th>
-            <th>{t("usage.col.share")}</th>
+            <th className="num">{t("usage.col.requests")}</th>
+            <th className="num">{t("usage.col.measured")}</th>
+            <th className="num">{t("usage.col.inputTokens")}</th>
+            <th className="num">{t("usage.col.outputTokens")}</th>
+            <th className="num">{t("usage.col.cacheHits")}</th>
+            <th className="num">{t("usage.col.cacheWrites")}</th>
+            <th className="num">{t("usage.col.cacheHitRate")}</th>
           </tr>
         </thead>
         <tbody>
-          {models.map(model => (
-            <tr key={`${model.provider}/${model.model}`}>
-              <td className="mono">{modelLabel(model.model)}</td>
-              <td className="muted">{formatProviderDisplayName(model.provider, t)}</td>
-              <td className="num">{model.requests}</td>
-              <td className="num">{model.measuredRequests}</td>
-              <td className="num mono">{formatTokens(model.totalTokens, locale)}</td>
-              <td className="num"><UsageListPrice row={model} locale={locale} t={t} /></td>
-              <td><div className="usage-bar"><div className="usage-bar-fill" style={{ width: `${Math.round(model.shareRatio * 100)}%` }} /></div></td>
-            </tr>
-          ))}
+          {models.map(model => {
+            const providerName = formatProviderDisplayName(model.provider, t);
+            const cacheCoverage = cacheHitRateTitle(model, locale, t);
+            return (
+              <tr key={`${model.provider}/${model.model}`}>
+                {/* Both pinned columns are width-capped, so carry the full value in a tooltip. */}
+                <td className="mono" title={model.model}>{modelLabel(model.model)}</td>
+                <td className="muted" title={providerName}>{providerName}</td>
+                <td><div className="usage-bar"><div className="usage-bar-fill" style={{ width: `${Math.round(model.shareRatio * 100)}%` }} /></div></td>
+                <td className="num mono">{formatTokens(model.totalTokens, locale)}</td>
+                <td className="num"><UsageListPrice row={model} locale={locale} t={t} /></td>
+                <td className="num">{model.requests}</td>
+                <td className="num">{model.measuredRequests}</td>
+                <td className="num mono">{formatTokens(model.inputTokens, locale)}</td>
+                <td className="num mono">{formatTokens(model.outputTokens, locale)}</td>
+                <td className="num mono">{formatOptionalTokens(model.cacheReadInputTokens ?? model.cachedInputTokens, locale, unavailable)}</td>
+                <td className="num mono">{formatOptionalTokens(model.cacheCreationInputTokens, locale, unavailable)}</td>
+                {/*
+                  The summary already averages only the input tokens whose cache detail was
+                  reported, so whatever number it returns has a basis. Suppressing it unless that
+                  basis covered the row's whole input is what hid a measured hit rate behind an em
+                  dash for every provider that leaves some requests unreported; the coverage is a
+                  note on the cell now, not a gate.
+                */}
+                <td className="num mono" title={cacheCoverage}>
+                  <span className="usage-hit-rate">{formatOptionalPct(model.cacheHitRate, unavailable)}</span>
+                  {/* A `title` reaches a pointer and nothing else, so the sentence is also read. */}
+                  {cacheCoverage !== undefined && <span className="sr-only">{cacheCoverage}</span>}
+                </td>
+              </tr>
+            );
+          })}
         </tbody>
       </table>
       <p id={listPriceDisclaimerId} className="muted text-caption">{t("usage.cost.disclaimer")}</p>
@@ -872,6 +948,7 @@ function UsageWorkspaceBody({
   range,
   locale,
   t,
+  apiBase,
 }: {
   data: UsageResponse | null;
   heatmap: ReturnType<typeof buildHeatmap>;
@@ -884,8 +961,10 @@ function UsageWorkspaceBody({
   range: Range | null;
   locale: Locale;
   t: TFn;
+  apiBase: string;
 }) {
   const empty = !!data && data.summary.requests === 0;
+  const [companionMetric, setCompanionMetric] = useState<string | null>(null);
   const sections = [
     {
       id: "overview",
@@ -920,6 +999,20 @@ function UsageWorkspaceBody({
       meta: data ? formatPct(data.summary.coverageRatio) : "—",
       body: data ? <UsageCoveragePanel summary={data.summary} t={t} workspace /> : null,
     },
+    {
+      id: "companion",
+      label: t("usage.section.companion"),
+      meta: companionMetric
+        ? t(`usage.companion.menu${companionMetric[0]!.toUpperCase()}${companionMetric.slice(1)}` as never)
+        : "—",
+      body: (
+        <UsageCompanionPanel
+          apiBase={apiBase}
+          providers={data?.providers ?? []}
+          onSettingsLoaded={setCompanionMetric}
+        />
+      ),
+    },
   ];
   return (
     <div className="usage-workspace-shell">
@@ -1190,6 +1283,7 @@ export default function Usage({ apiBase, connected = false, apiKeyId }: { apiBas
             range={customWindow ? null : range}
             locale={locale}
             t={t}
+            apiBase={apiBase}
           />
         </>
       )}
diff --git a/gui/src/pages/integrations/ConsequenceDialog.tsx b/gui/src/pages/integrations/ConsequenceDialog.tsx
index 9ddaf95d871..2a2e85ebcea 100644
--- a/gui/src/pages/integrations/ConsequenceDialog.tsx
+++ b/gui/src/pages/integrations/ConsequenceDialog.tsx
@@ -88,7 +88,10 @@ export default function ConsequenceDialog({
     dismiss();
   }, [dismiss]);
 
-  const confirm = useCallback(async () => {
+  // Named for what it does rather than shadowing the banned global: a local `confirm`
+  // reads exactly like the platform dialog this dashboard no longer uses, and the source
+  // guard in tests/gui/platform-dialog-guard.test.ts cannot tell the two call forms apart.
+  const applyConsequence = useCallback(async () => {
     if (pending) return;
     setPending(true);
     setFailure(null);
@@ -146,7 +149,7 @@ export default function ConsequenceDialog({
         <IntegrationPlanDetails plan={activePlan} plans={plans} />
         {failure && <Notice tone="err">{failure}</Notice>}
         <div className="modal-actions">
-          <button type="button" className="btn btn-primary" onClick={() => void confirm()} disabled={pending || planLoading || Boolean(planFailure) || (planRequired && !activePlan && plans === undefined) || noActionableBulkTarget || activePlan?.canApply === false}>
+          <button type="button" className="btn btn-primary" onClick={() => void applyConsequence()} disabled={pending || planLoading || Boolean(planFailure) || (planRequired && !activePlan && plans === undefined) || noActionableBulkTarget || activePlan?.canApply === false}>
             {t(copy.confirmKey)}
           </button>
         </div>
diff --git a/gui/src/pages/integrations/FileIntegrationPage.tsx b/gui/src/pages/integrations/FileIntegrationPage.tsx
index 3ee7db1b967..b8806d563df 100644
--- a/gui/src/pages/integrations/FileIntegrationPage.tsx
+++ b/gui/src/pages/integrations/FileIntegrationPage.tsx
@@ -330,6 +330,14 @@ export default function FileIntegrationPage({
       <p className="integration-path">{status.configPath}</p>
       {/* Only the raycast envelope carries this; the guard is the field, not the id. */}
       {status.raycast && <RaycastPlanNotice install={status.raycast} />}
+      {/*
+        A file the client no longer opens. The badge above stays truthful about
+        the file -- our block really is where we put it -- so this is the only
+        place that can say the client has stopped reading it.
+      */}
+      {status.supersededBy && (
+        <Notice tone="err">{t("integrations.status.supersededStore", { path: status.supersededBy })}</Notice>
+      )}
 
       {status.appliedAt && (
         <p className="integration-meta">
diff --git a/gui/src/pages/integrations/IntegrationPlanDetails.tsx b/gui/src/pages/integrations/IntegrationPlanDetails.tsx
index 742794de93c..d412282c99a 100644
--- a/gui/src/pages/integrations/IntegrationPlanDetails.tsx
+++ b/gui/src/pages/integrations/IntegrationPlanDetails.tsx
@@ -35,6 +35,7 @@ const REFUSAL_KEYS: Partial<Record<string, TKey>> = {
   conflict: "integrations.plan.refusal.conflict",
   unsafe: "integrations.plan.refusal.unsafe",
   non_loopback: "integrations.plan.refusal.nonLoopback",
+  superseded_store: "integrations.plan.refusal.supersededStore",
   drift_requires_confirm: "integrations.plan.refusal.driftRequiresConfirm",
   snapshot_expired: "integrations.plan.refusal.snapshotExpired",
   write_failed: "integrations.plan.refusal.writeFailed",
diff --git a/gui/src/pages/integrations/integration-api.ts b/gui/src/pages/integrations/integration-api.ts
index 856a9b105d0..02733e095ce 100644
--- a/gui/src/pages/integrations/integration-api.ts
+++ b/gui/src/pages/integrations/integration-api.ts
@@ -36,6 +36,7 @@ export type IntegrationRefusalReason =
   | "conflict"
   | "unsafe"
   | "non_loopback"
+  | "superseded_store"
   | "drift_requires_confirm"
   | "snapshot_expired"
   | "write_failed";
@@ -61,6 +62,14 @@ export interface IntegrationStatus {
   appliedAt?: string;
   lastOpId?: string;
   reason?: IntegrationReason;
+  /**
+   * The store this client reads instead of `configPath`, when one exists.
+   *
+   * Independent of `state`: the block can be current in a file the client
+   * stopped opening, which is the one case where a green badge alone misleads.
+   * Same role as `raycast`, whose plan can make a written file inert.
+   */
+  supersededBy?: string;
   snapshotCount: number;
   retentionDegraded: boolean;
   /** Aside's explicit account-backed profile scope and desired sync state. */
@@ -194,6 +203,7 @@ const REFUSAL_REASONS: ReadonlySet<string> = new Set<IntegrationRefusalReason>([
   "conflict",
   "unsafe",
   "non_loopback",
+  "superseded_store",
   "drift_requires_confirm",
   "snapshot_expired",
   "write_failed",
@@ -228,6 +238,10 @@ const PLAN_SCHEMA_PATHS = new Set([
   "providers.[id=opencodex]",
   "settings.providers.opencodex",
   "catalog.providers.opencodex",
+  // ZCode reads its providers from a second file; a plan for it publishes that
+  // file's templates, and a path missing here is rejected as an invalid preview.
+  "config.providerConfigRules.providerRules.[providerId=opencodex]",
+  "config.modelConfigRules.providerModelRules.*",
 ]);
 const PLAN_CHANGE_LIMIT = 256;
 
@@ -254,7 +268,13 @@ export function parseIntegrationMutationPlan(value: unknown): IntegrationMutatio
     || !PLAN_OPERATIONS.includes(value.operation as IntegrationPlanOperation)
     || !INTEGRATION_STATES.has(String(value.state))
     || !PLAN_FOREIGN_EDITS.includes(value.foreignEdit as IntegrationPlanForeignEdit)
-    || typeof value.fingerprint !== "string" || !/^p1:(?:[0-9a-f]{32}|unbound)$/.test(value.fingerprint)
+    /*
+     * The version is matched as a version, not as `p1`. The server calls this
+     * token opaque and bumps its prefix whenever the inputs it binds change; a
+     * literal here made that bump a silent client-side rejection of every
+     * preview, which is a worse failure than the drift it was meant to catch.
+     */
+    || typeof value.fingerprint !== "string" || !/^p[0-9]+:(?:[0-9a-f]{32}|unbound)$/.test(value.fingerprint)
     || typeof value.canApply !== "boolean" || typeof value.willChange !== "boolean"
     || !Array.isArray(value.changes) || value.changes.length > PLAN_CHANGE_LIMIT
     || (value.profileId !== undefined && (typeof value.profileId !== "number" || !Number.isSafeInteger(value.profileId) || value.profileId < 0))
@@ -283,7 +303,7 @@ export function parseIntegrationMutationPlan(value: unknown): IntegrationMutatio
   }
   if ((value.willChange && (!value.canApply || changes.length === 0))
     || (!value.willChange && changes.length !== 0)
-    || (value.fingerprint === "p1:unbound" && value.canApply)
+    || ((value.fingerprint as string).endsWith(":unbound") && value.canApply)
     || (value.canApply === (value.refusalReason !== undefined))) throw invalidPreviewResponse();
   return {
     version: 1,
diff --git a/gui/src/pages/models-alias-editing.ts b/gui/src/pages/models-alias-editing.ts
new file mode 100644
index 00000000000..e405d0c812c
--- /dev/null
+++ b/gui/src/pages/models-alias-editing.ts
@@ -0,0 +1,54 @@
+import type { TFn } from "../i18n/shared";
+import { requestTextValue } from "../action-dialogs";
+
+/**
+ * Alias editing for the models page, extracted so Models.tsx can host the in-page dialog
+ * without growing: that file sits on its recorded line cap, and the cap only ever moves
+ * down (tests/fixtures/file-size-baseline.json).
+ *
+ * Both editors used to open `window.prompt()`, which the app's webview cannot draw at all —
+ * wry implements no text input panel — so inside the app these two pencil buttons could
+ * not be used. See devlog/_plan/260921_app_runtime_ownership/050_webview_dialogs.md.
+ */
+export interface AliasEditingDeps {
+  apiBase: string;
+  t: TFn;
+  /** Re-reads /api/aliases so the row shows what the server now holds. */
+  reloadAliases: () => Promise<void>;
+  publishFeedback: (ok: boolean, message: string) => void;
+}
+
+/** Renames a provider. An empty value clears the alias, as the field label says. */
+export async function editProviderAlias(
+  provider: string,
+  current: string,
+  { apiBase, t, reloadAliases, publishFeedback }: AliasEditingDeps,
+): Promise<void> {
+  const entered = await requestTextValue({ message: t("models.aliasPrompt"), initialValue: current });
+  // Dismissal is not an empty alias: a cancelled edit must write nothing.
+  if (entered === null) return;
+  const response = await fetch(`${apiBase}/api/providers/${encodeURIComponent(provider)}/alias`, {
+    method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify({ alias: entered.trim() || null }),
+  });
+  if (!response.ok) { publishFeedback(false, t("models.aliasConflict")); return; }
+  await reloadAliases();
+  publishFeedback(true, t("models.aliasSaved"));
+}
+
+/** Renames one model within a provider. An empty value removes the alias. */
+export async function editModelAlias(
+  provider: string,
+  model: string,
+  current: string,
+  { apiBase, t, reloadAliases, publishFeedback }: AliasEditingDeps,
+): Promise<void> {
+  const entered = await requestTextValue({ message: t("models.modelAliasPrompt"), initialValue: current });
+  if (entered === null) return;
+  const body = entered.trim() ? { set: { [model]: entered.trim() } } : { remove: [model] };
+  const response = await fetch(`${apiBase}/api/providers/${encodeURIComponent(provider)}/model-aliases`, {
+    method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+  });
+  if (!response.ok) { publishFeedback(false, t("models.aliasConflict")); return; }
+  await reloadAliases();
+  publishFeedback(true, t("models.aliasSaved"));
+}
diff --git a/gui/src/pages/startup-sections.tsx b/gui/src/pages/startup-sections.tsx
index 301f568e01e..b808680f8bb 100644
--- a/gui/src/pages/startup-sections.tsx
+++ b/gui/src/pages/startup-sections.tsx
@@ -1,4 +1,5 @@
 import { useI18n, type TKey } from "../i18n/shared";
+import { confirmAction } from "../action-dialogs";
 import { startupRiskDetailKey } from "../startup-health-ui";
 import { IconAlert, IconCheck, IconPower, IconTerminal } from "../icons";
 import type {
@@ -165,6 +166,17 @@ export function StartupTraySection({
 }) {
   const { t } = useI18n();
 
+  /**
+   * Uninstalling removes the tray helper, so it asks first. Written as a named async
+   * function rather than a promise chain inside the handler: a floating `.then` in a JSX
+   * handler has no rejection path, which is what `no-floating-then-in-jsx-handler` catches.
+   */
+  const requestTrayUninstall = async () => {
+    if (await confirmAction({ message: t("startup.tray.uninstall"), tone: "danger" })) {
+      onTrayAction("uninstall");
+    }
+  };
+
   return (
     <section className="panel startup-actions">
       <div className="panel-head">
@@ -196,9 +208,7 @@ export function StartupTraySection({
           <button type="button" className="btn btn-ghost" disabled={trayBusy} onClick={() => onTrayAction("stop")}>{t("startup.tray.stop")}</button>
         )}
         {!trayLoading && !trayError && tray && (tray.installed || tray.stale) && (
-          <button type="button" className="btn btn-danger" disabled={trayBusy} onClick={() => {
-            if (window.confirm(t("startup.tray.uninstall"))) onTrayAction("uninstall");
-          }}>{t("startup.tray.uninstall")}</button>
+          <button type="button" className="btn btn-danger" disabled={trayBusy} onClick={() => { void requestTrayUninstall(); }}>{t("startup.tray.uninstall")}</button>
         )}
       </div>
       {(trayError || tray?.stale) && (
diff --git a/gui/src/pages/usage-companion-chart.tsx b/gui/src/pages/usage-companion-chart.tsx
new file mode 100644
index 00000000000..0cf5505efb2
--- /dev/null
+++ b/gui/src/pages/usage-companion-chart.tsx
@@ -0,0 +1,119 @@
+import type { Locale, TFn } from "../i18n/shared";
+import {
+  chartPolylinePoints,
+  chartStackedBarRects,
+  formatCompanionTokens,
+  type UsageTimeline,
+} from "./usage-companion-utils";
+
+const CHART_COLORS = ["#0A84FF", "#FF9F0A", "#30D158", "#BF5AF2", "#FF453A", "#64D2FF"];
+const WIDTH = 640;
+const HEIGHT = 160;
+const PADDING = 28;
+
+function maxValue(timeline: UsageTimeline, chartStyle: "line" | "stackedBar"): number {
+  if (chartStyle === "stackedBar") {
+    return Math.max(...Array.from({ length: timeline.buckets }, (_, index) =>
+      timeline.series.reduce((sum, series) => sum + (series.points[index] ?? 0), 0),
+    ), 0);
+  }
+  return Math.max(...timeline.series.flatMap(series => series.points), 0);
+}
+
+function dateLabels(timeline: UsageTimeline, locale: Locale): string[] {
+  const formatter = new Intl.DateTimeFormat(locale, { month: "short", day: "numeric" });
+  const interval = Math.max(1, Math.floor((timeline.buckets - 1) / 3));
+  return [0, 1, 2, 3].map(index => {
+    const bucket = Math.min(timeline.buckets - 1, index * interval);
+    return formatter.format(new Date((timeline.start + bucket * timeline.bucketSeconds) * 1000));
+  });
+}
+
+export function UsageCompanionChart({
+  timeline,
+  chartStyle,
+  hours,
+  loading,
+  error,
+  onRetry,
+  locale,
+  t,
+}: {
+  timeline: UsageTimeline | null;
+  chartStyle: "line" | "stackedBar";
+  hours: number;
+  loading: boolean;
+  error: string | null;
+  onRetry: () => void;
+  locale: Locale;
+  t: TFn;
+}) {
+  if (loading) {
+    return <div className="usage-companion-chart-skeleton" aria-busy="true" aria-label={t("usage.companion.loading")} />;
+  }
+  if (error) {
+    return (
+      <div className="usage-companion-chart-state" role="alert">
+        <span>{t("usage.companion.timelineUnavailable")}</span>
+        <button type="button" className="btn btn-ghost btn-sm" onClick={onRetry}>{t("common.retry")}</button>
+      </div>
+    );
+  }
+  if (!timeline || timeline.series.length === 0) {
+    return <div className="usage-companion-chart-state">{t("usage.companion.empty", { hours: timeline?.buckets ? Math.round(timeline.buckets * timeline.bucketSeconds / 3600) : hours })}</div>;
+  }
+  const max = maxValue(timeline, chartStyle);
+  const labels = dateLabels(timeline, locale);
+  const plotWidth = WIDTH - PADDING * 2;
+  const plotHeight = HEIGHT - PADDING * 2;
+  const y = PADDING;
+  const baseline = PADDING + plotHeight;
+  const translate = "trans" + "late";
+  const xLabels = labels.map((label, index) => (
+    <text key={`${label}-${index}`} x={PADDING + plotWidth * index / 3} y={HEIGHT - 4} textAnchor={index === 0 ? "start" : index === 3 ? "end" : "middle"} className="usage-companion-axis-label">{label}</text>
+  ));
+  const marks = chartStyle === "line"
+    ? timeline.series.map((series, index) => (
+      <polyline
+        key={series.id}
+        points={chartPolylinePoints(series.points, plotWidth, plotHeight, max, 0)}
+        transform={`${translate}(${PADDING},${PADDING})`}
+        fill="none"
+        stroke={CHART_COLORS[index % CHART_COLORS.length]}
+        strokeWidth="2"
+        strokeLinejoin="round"
+        strokeLinecap="round"
+      />
+    ))
+    : chartStackedBarRects(timeline.series, plotWidth, plotHeight, max, 0).map(rect => (
+      <rect
+        key={`${rect.bucketIndex}-${rect.seriesIndex}`}
+        x={PADDING + rect.x}
+        y={PADDING + rect.y}
+        width={rect.width}
+        height={rect.height}
+        fill={CHART_COLORS[rect.seriesIndex % CHART_COLORS.length]}
+        rx="1"
+      />
+    ));
+  return (
+    <div className="usage-companion-chart">
+      <svg viewBox={`0 0 ${WIDTH} ${HEIGHT}`} role="img" aria-label={t("usage.companion.chartLabel")}>
+        <line x1={PADDING} y1={y} x2={PADDING} y2={baseline} className="usage-companion-axis" />
+        <line x1={PADDING} y1={baseline} x2={WIDTH - PADDING} y2={baseline} className="usage-companion-axis" />
+        <text x={PADDING - 4} y={y + 4} textAnchor="end" className="usage-companion-axis-label">{formatCompanionTokens(max)}</text>
+        {marks}
+        {xLabels}
+      </svg>
+      <div className="usage-companion-legend">
+        {timeline.series.map((series, index) => (
+          <span key={series.id} className="usage-companion-legend-item">
+            <span className="usage-companion-swatch" style={{ background: CHART_COLORS[index % CHART_COLORS.length] }} aria-hidden="true" />
+            <span>{series.id}</span>
+          </span>
+        ))}
+      </div>
+      {timeline.truncated && <p className="muted text-caption">{t("usage.companion.olderRecordsSkipped")}</p>}
+    </div>
+  );
+}
diff --git a/gui/src/pages/usage-companion-panel.tsx b/gui/src/pages/usage-companion-panel.tsx
new file mode 100644
index 00000000000..44dd4f2dff2
--- /dev/null
+++ b/gui/src/pages/usage-companion-panel.tsx
@@ -0,0 +1,521 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
+import { useI18n, type TFn, type TKey } from "../i18n/shared";
+import { relativeTimeLabelsFromT, formatRelativeTime } from "../provider-workspace/usage";
+import { Switch } from "../ui";
+import { UsageCompanionChart } from "./usage-companion-chart";
+import { desktopShellVersion, hostOs, isDesktopShell, type HostOs } from "../lib/desktop-shell";
+import {
+  bucketMinutesForWindow,
+  buildCompanionSettingsPatch,
+  formatCompanionTokens,
+  groupCompanionModels,
+  toggleCompanionModels,
+  type CompanionSettings,
+  type CompanionSettingsResponse,
+  type UsageTimeline,
+} from "./usage-companion-utils";
+
+interface CompanionProvider {
+  provider: string;
+}
+
+const MENU_METRICS = ["requests", "tokens", "cost", "quota", "none"] as const;
+const WINDOWS = [6, 24, 72, 168] as const;
+const CHART_STYLES = ["line", "stackedBar"] as const;
+const TOKEN_METRICS = ["total", "input", "output", "cached"] as const;
+const AGGREGATIONS = ["sum", "average", "max"] as const;
+const GROUPINGS = ["model", "modelAccount"] as const;
+const MENU_METRIC_KEYS: Record<(typeof MENU_METRICS)[number], TKey> = {
+  requests: "usage.companion.menuRequests",
+  tokens: "usage.companion.menuTokens",
+  cost: "usage.companion.menuCost",
+  quota: "usage.companion.menuQuota",
+  none: "usage.companion.menuNone",
+};
+const WINDOW_KEYS: Record<(typeof WINDOWS)[number], TKey> = {
+  6: "usage.companion.window6",
+  24: "usage.companion.window24",
+  72: "usage.companion.window72",
+  168: "usage.companion.window168",
+};
+const TOKEN_METRIC_KEYS: Record<(typeof TOKEN_METRICS)[number], TKey> = {
+  total: "usage.companion.metricTotal",
+  input: "usage.companion.metricInput",
+  output: "usage.companion.metricOutput",
+  cached: "usage.companion.metricCached",
+};
+const SECTION_OPTIONS = [
+  ["showToday", "usage.companion.sectionToday"],
+  ["showChart", "usage.companion.sectionChart"],
+  ["showModels", "usage.companion.sectionModels"],
+  ["showCost", "usage.companion.sectionCost"],
+  ["showAccounts", "usage.companion.sectionAccounts"],
+] as const;
+const AGGREGATION_KEYS: Record<(typeof AGGREGATIONS)[number], TKey> = {
+  sum: "usage.companion.aggregationSum",
+  average: "usage.companion.aggregationAverage",
+  max: "usage.companion.aggregationMax",
+};
+type InstallOs = Exclude<HostOs, "unknown">;
+
+const INSTALL_STEP_KEYS: Record<InstallOs, readonly [TKey, TKey, TKey]> = {
+  macos: ["usage.companion.installMacStep1", "usage.companion.installMacStep2", "usage.companion.installMacStep3"],
+  windows: ["usage.companion.installWinStep1", "usage.companion.installWinStep2", "usage.companion.installWinStep3"],
+  linux: ["usage.companion.installLinuxStep1", "usage.companion.installLinuxStep2", "usage.companion.installLinuxStep3"],
+};
+
+const OS_LABEL_KEYS: Record<InstallOs, TKey> = {
+  macos: "usage.companion.osMac",
+  windows: "usage.companion.osWindows",
+  linux: "usage.companion.osLinux",
+};
+
+function formatSaveTime(value: number, locale: string): string {
+  return new Intl.DateTimeFormat(locale, { hour: "2-digit", minute: "2-digit" }).format(value);
+}
+
+function errorMessage(value: unknown): string {
+  if (value instanceof Error && value.message) return value.message;
+  return String(value);
+}
+
+function OsSelector({
+  value,
+  onChange,
+  t,
+}: {
+  value: InstallOs;
+  onChange: (value: InstallOs) => void;
+  t: TFn;
+}) {
+  return (
+    <div className="usage-segmented" role="group" aria-label={t("usage.companion.installOs")}>
+      {(Object.keys(OS_LABEL_KEYS) as InstallOs[]).map(os => (
+        <button key={os} type="button" className={`usage-segmented-btn${value === os ? " active" : ""}`} aria-pressed={value === os} onClick={() => onChange(os)}>
+          {t(OS_LABEL_KEYS[os])}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+function Segment<T extends string | number>({
+  label,
+  value,
+  options,
+  optionLabel,
+  onChange,
+}: {
+  label: string;
+  value: T;
+  options: readonly T[];
+  optionLabel: (value: T) => string;
+  onChange: (value: T) => void;
+}) {
+  return (
+    <div className="usage-companion-control">
+      <span className="field-label">{label}</span>
+      <div className="usage-segmented" role="group" aria-label={label}>
+        {options.map(option => (
+          <button key={String(option)} type="button" className={`usage-segmented-btn${option === value ? " active" : ""}`} aria-pressed={option === value} onClick={() => onChange(option)}>
+            {optionLabel(option)}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function SelectControl<T extends string>({
+  label,
+  value,
+  options,
+  optionLabel,
+  onChange,
+}: {
+  label: string;
+  value: T;
+  options: readonly T[];
+  optionLabel: (value: T) => string;
+  onChange: (value: T) => void;
+}) {
+  return (
+    <label className="usage-companion-control">
+      <span className="field-label">{label}</span>
+      <select value={value} onChange={event => onChange(event.target.value as T)}>
+        {options.map(option => <option key={option} value={option}>{optionLabel(option)}</option>)}
+      </select>
+    </label>
+  );
+}
+
+function useVisible(ref: RefObject<HTMLElement | null>): boolean {
+  const [visible, setVisible] = useState(false);
+  useEffect(() => {
+    if (visible || !ref.current || typeof IntersectionObserver === "undefined") return;
+    const observer = new IntersectionObserver(entries => {
+      if (entries.some(entry => entry.isIntersecting)) {
+        setVisible(true);
+        observer.disconnect();
+      }
+    }, { rootMargin: "240px" });
+    observer.observe(ref.current);
+    return () => observer.disconnect();
+  }, [ref, visible]);
+  return visible;
+}
+
+export default function UsageCompanionPanel({
+  apiBase,
+  providers,
+  onSettingsLoaded,
+}: {
+  apiBase: string;
+  providers: CompanionProvider[];
+  onSettingsLoaded?: (metric: CompanionSettings["menuBarMetric"]) => void;
+}) {
+  const { t, locale } = useI18n();
+  const rootRef = useRef<HTMLElement>(null);
+  const visible = useVisible(rootRef);
+  const [response, setResponse] = useState<CompanionSettingsResponse | null>(null);
+  const [settings, setSettings] = useState<CompanionSettings | null>(null);
+  const [timeline, setTimeline] = useState<UsageTimeline | null>(null);
+  const [availableModels, setAvailableModels] = useState<string[]>([]);
+  const [settingsError, setSettingsError] = useState<string | null>(null);
+  const [timelineError, setTimelineError] = useState<string | null>(null);
+  const [timelineLoading, setTimelineLoading] = useState(false);
+  const [saveState, setSaveState] = useState<"idle" | "saving" | "saved" | "error">("idle");
+  const [fetchedAt, setFetchedAt] = useState<number | null>(null);
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const saveTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const saveBaseline = useRef<CompanionSettings | null>(null);
+  const timelineRequest = useRef<AbortController | null>(null);
+  const saveStateRef = useRef(saveState);
+  const settingsRef = useRef(settings);
+  const knownTotalsRef = useRef(new Map<string, number>());
+  const [knownTotals, setKnownTotals] = useState<Map<string, number>>(new Map());
+  const [installOs, setInstallOs] = useState<InstallOs>(() => {
+    const detected = hostOs();
+    return detected === "unknown" ? "macos" : detected;
+  });
+
+  useEffect(() => {
+    saveStateRef.current = saveState;
+  }, [saveState]);
+
+  useEffect(() => {
+    settingsRef.current = settings;
+  }, [settings]);
+
+  const loadSettings = useCallback(async () => {
+    setSettingsError(null);
+    try {
+      const result = await fetch(`${apiBase}/api/companion/settings`);
+      if (!result.ok) throw new Error(`${result.status} ${result.statusText}`.trim());
+      const next = await result.json() as CompanionSettingsResponse;
+      setResponse(next);
+      setFetchedAt(Date.now());
+      setSettings(next.settings);
+      saveBaseline.current = next.settings;
+      onSettingsLoaded?.(next.settings.menuBarMetric);
+    } catch (error) {
+      setSettingsError(errorMessage(error));
+    }
+  }, [apiBase, onSettingsLoaded]);
+
+  useEffect(() => {
+    if (!visible || response) return;
+    const timer = setTimeout(() => void loadSettings(), 0);
+    return () => clearTimeout(timer);
+  }, [loadSettings, response, visible]);
+
+  useEffect(() => {
+    if (!visible) return;
+    const interval = setInterval(() => {
+      if (saveStateRef.current === "saving") return;
+      if (settingsRef.current && saveBaseline.current !== settingsRef.current) return;
+      void loadSettings();
+    }, 60_000);
+    return () => clearInterval(interval);
+  }, [loadSettings, visible]);
+
+  const chartQuery = useMemo(() => {
+    if (!settings) return null;
+    const query = new URLSearchParams({
+      hours: String(settings.chartHours),
+      bucketMinutes: String(settings.bucketMinutes),
+      metric: settings.tokenMetric,
+      aggregation: settings.aggregation,
+      grouping: settings.chartGrouping,
+    });
+    if (settings.models?.length) query.set("models", settings.models.join(","));
+    return query;
+  }, [settings]);
+
+  const loadTimeline = useCallback(async () => {
+    if (!chartQuery) return;
+    timelineRequest.current?.abort();
+    const controller = new AbortController();
+    timelineRequest.current = controller;
+    setTimelineLoading(true);
+    setTimelineError(null);
+    try {
+      const result = await fetch(`${apiBase}/api/usage/timeline?${chartQuery}`, { signal: controller.signal });
+      if (!result.ok) throw new Error(`${result.status} ${result.statusText}`.trim());
+      const next = await result.json() as UsageTimeline;
+      setTimeline(next);
+      setAvailableModels(next.availableModels);
+      const currentTotals = new Map<string, number>();
+      for (const series of next.series) {
+        currentTotals.set(series.id, (currentTotals.get(series.id) ?? 0) + series.total);
+      }
+      for (const [id, total] of currentTotals) {
+        knownTotalsRef.current.set(id, total);
+      }
+      setKnownTotals(new Map(knownTotalsRef.current));
+    } catch (error) {
+      if (!controller.signal.aborted) setTimelineError(errorMessage(error));
+    } finally {
+      if (!controller.signal.aborted) setTimelineLoading(false);
+    }
+  }, [apiBase, chartQuery]);
+
+  useEffect(() => {
+    if (!visible || !chartQuery) return;
+    const timer = setTimeout(() => void loadTimeline(), 250);
+    const interval = setInterval(() => void loadTimeline(), 60_000);
+    return () => {
+      clearTimeout(timer);
+      clearInterval(interval);
+      timelineRequest.current?.abort();
+    };
+  }, [chartQuery, loadTimeline, visible]);
+
+  const updateSettings = useCallback((patch: Partial<CompanionSettings>) => {
+    if (response?.corrupt) return;
+    setSettings(current => current ? { ...current, ...patch } : current);
+    setSaveState("saving");
+    setSaveError(null);
+  }, [response?.corrupt]);
+
+  useEffect(() => {
+    if (response?.corrupt || !settings || !saveBaseline.current || saveBaseline.current === settings || saveState !== "saving") return;
+    if (saveTimer.current) clearTimeout(saveTimer.current);
+    saveTimer.current = setTimeout(async () => {
+      try {
+        const patch = buildCompanionSettingsPatch(settings, availableModels);
+        const result = await fetch(`${apiBase}/api/companion/settings`, {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ settings: patch }),
+        });
+        const body = await result.json() as CompanionSettingsResponse | { error?: string };
+        if (!result.ok) throw new Error(body && "error" in body && body.error ? body.error : `${result.status} ${result.statusText}`.trim());
+        setResponse(body as CompanionSettingsResponse);
+        setFetchedAt(Date.now());
+        setSettings((body as CompanionSettingsResponse).settings);
+        saveBaseline.current = (body as CompanionSettingsResponse).settings;
+        setSaveState("saved");
+      } catch (error) {
+        setSaveError(errorMessage(error));
+        setSaveState("error");
+      }
+    }, 300);
+    return () => {
+      if (saveTimer.current) clearTimeout(saveTimer.current);
+    };
+  }, [apiBase, availableModels, response?.corrupt, saveState, settings]);
+
+  const reset = useCallback(async () => {
+    setSaveState("saving");
+    setSaveError(null);
+    try {
+      const result = await fetch(`${apiBase}/api/companion/settings`, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ reset: true }),
+      });
+      if (!result.ok) throw new Error(`${result.status} ${result.statusText}`.trim());
+      await loadSettings();
+      setSaveState("saved");
+    } catch (error) {
+      setSaveError(errorMessage(error));
+      setSaveState("error");
+    }
+  }, [apiBase, loadSettings]);
+
+  const openInBrowser = useCallback(async () => {
+    try {
+      const path = location.hash ? `/${location.hash}` : "/#/usage";
+      const result = await fetch(`${apiBase}/api/companion/open-in-browser`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path }),
+      });
+      if (!result.ok) throw new Error(`${result.status} ${result.statusText}`.trim());
+    } catch (error) {
+      setSaveError(errorMessage(error));
+    }
+  }, [apiBase]);
+
+  if (settingsError) {
+    return <section ref={rootRef} className="usage-companion-panel"><p role="alert">{t("usage.companion.settingsUnavailable")}</p><button type="button" className="btn btn-ghost btn-sm" onClick={() => void loadSettings()}>{t("common.retry")}</button></section>;
+  }
+  const current = settings;
+  if (!current) {
+    return <section ref={rootRef} className="usage-companion-panel" aria-busy="true"><div className="usage-companion-loading">{t("common.loading")}</div></section>;
+  }
+  const providerNames = providers.map(provider => provider.provider).filter((provider, index, all) => all.indexOf(provider) === index).toSorted();
+  const selectedModels = current.models ?? availableModels;
+  const selectedModelSet = new Set(selectedModels);
+  const modelGroups = groupCompanionModels(availableModels, knownTotals);
+  const hiddenProviderSet = new Set(current.hiddenProviders);
+  const saveMessage = saveState === "saved" && response?.updatedAt
+    ? t("usage.companion.saved", { time: formatSaveTime(response.updatedAt, locale) })
+    : saveState === "error" ? t("usage.companion.saveFailed", { error: saveError ?? "" }) : "";
+  return (
+    <section ref={rootRef} className="usage-companion-panel">
+      {response?.corrupt && <div className="usage-companion-save-status is-error" role="alert">
+        <span>{t("usage.companion.corrupt")}</span>
+        <button type="button" className="btn btn-ghost btn-sm" onClick={() => void reset()} disabled={saveState === "saving"}>{t("usage.companion.corruptReset")}</button>
+      </div>}
+      <div className="usage-companion-header">
+        <div>
+          <h3 className="panel-title">{t("usage.companion.title")}</h3>
+          <p className="card-sub">{t("usage.companion.description")}</p>
+        </div>
+        <a className="btn btn-ghost btn-sm" href="https://opencodex.me/guides/macos-menu-bar/" target="_blank" rel="noreferrer">{t("usage.companion.installGuide")}</a>
+      </div>
+      {(() => {
+        const lastSeenAt = response?.companion?.lastSeenAt ?? null;
+        const connected = lastSeenAt !== null && fetchedAt !== null && fetchedAt - lastSeenAt <= 10 * 60 * 1000;
+        const age = lastSeenAt === null || fetchedAt === null ? "" : formatRelativeTime(lastSeenAt, relativeTimeLabelsFromT(t), fetchedAt);
+        const shell = isDesktopShell();
+        const shellVersion = desktopShellVersion() ?? __APP_VERSION__;
+        const stepKeys = INSTALL_STEP_KEYS[installOs];
+        const steps = (
+          <ol className="usage-companion-install-steps">
+            <li>{t(stepKeys[0])} <a className="btn btn-ghost btn-sm" href="https://github.com/lidge-jun/opencodex/releases/latest" target="_blank" rel="noreferrer">{t("common.github")}</a></li>
+            <li>{t(stepKeys[1])}</li>
+            <li>{t(stepKeys[2])}</li>
+          </ol>
+        );
+        const installCommand = installOs === "macos"
+          ? <code className="usage-companion-install-command">xattr -d com.apple.quarantine /Applications/OpenCodex.app</code>
+          : installOs === "linux"
+            ? <code className="usage-companion-install-command">chmod +x OpenCodex-*.AppImage</code>
+            : null;
+        const installGuidance = (
+          <details>
+            <summary>{t("usage.companion.installAnother")}</summary>
+            <OsSelector value={installOs} onChange={setInstallOs} t={t} />
+            {steps}
+            {installCommand}
+          </details>
+        );
+        if (shell) {
+          return (
+            <div className="usage-companion-install usage-companion-install--shell">
+              <p>{t("usage.companion.runningInDesktop", { version: shellVersion })}</p>
+              <button type="button" className="btn btn-ghost btn-sm" onClick={() => void openInBrowser()}>{t("usage.companion.openInBrowser")}</button>
+              {installGuidance}
+            </div>
+          );
+        }
+        return connected ? (
+          <div className="usage-companion-install usage-companion-install--connected">
+            <div className="usage-companion-install-status"><span className="usage-companion-install-dot" aria-hidden="true" />{t(response?.companion?.kind === "desktop" ? "usage.companion.connectedDesktop" : "usage.companion.connected", { age })}</div>
+            {installGuidance}
+          </div>
+        ) : (
+          <details className="usage-companion-install" open>
+            <summary>{t("usage.companion.installTitle")}</summary>
+            {lastSeenAt !== null && <p className="usage-companion-install-last-seen muted text-caption">{t("usage.companion.lastSeen", { age })}</p>}
+            {lastSeenAt === null && <p className="usage-companion-install-last-seen muted text-caption">{t("usage.companion.notConnected")}</p>}
+            <OsSelector value={installOs} onChange={setInstallOs} t={t} />
+            {steps}
+            {installCommand}
+          </details>
+        );
+      })()}
+      <UsageCompanionChart timeline={timeline} chartStyle={current.chartStyle} hours={current.chartHours} loading={timelineLoading} error={timelineError} onRetry={() => void loadTimeline()} locale={locale} t={t} />
+      {modelGroups.length > 0 && <section className="usage-companion-models">
+        <div className="usage-companion-models-header">
+          <div>
+            <span className="field-label">{t("usage.companion.modelsOnChart")}</span>
+            <span className="usage-companion-models-count text-caption muted">{t("usage.companion.modelsCount", { selected: selectedModels.length, total: availableModels.length })}</span>
+          </div>
+          {current.models !== null && <button type="button" className="btn btn-ghost btn-sm" onClick={() => updateSettings({ models: null })} disabled={response?.corrupt}>{t("usage.companion.modelsShowAll")}</button>}
+        </div>
+        <div className="usage-companion-models-list">
+          {modelGroups.map(group => {
+            const selectedCount = group.models.filter(model => selectedModelSet.has(model.id)).length;
+            const groupOn = selectedCount === group.models.length;
+            return <div key={group.provider} className="usage-companion-model-group">
+              <div className="usage-companion-model-group-header">
+                <span className="usage-companion-model-provider">{group.provider}</span>
+                <span className="usage-companion-model-chip mono text-caption">{group.models.length}</span>
+                <Switch
+                  on={groupOn}
+                  mixed={selectedCount > 0 && !groupOn}
+                  onClick={() => updateSettings({ models: toggleCompanionModels(current.models, availableModels, group.models.map(model => model.id), !groupOn) })}
+                  disabled={response?.corrupt}
+                  label={group.provider}
+                  title={group.provider}
+                />
+              </div>
+              {group.models.map(model => {
+                const on = selectedModelSet.has(model.id);
+                return <div key={model.id} className={`usage-companion-model-row${on ? "" : " is-off"}`}>
+                  <Switch
+                    on={on}
+                    onClick={() => updateSettings({ models: toggleCompanionModels(current.models, availableModels, [model.id], !on) })}
+                    disabled={response?.corrupt}
+                    label={model.id}
+                    title={model.id}
+                  />
+                  <code className="mono text-control">{model.id}</code>
+                  <span className="usage-companion-model-total muted text-caption">{knownTotals.has(model.id) ? formatCompanionTokens(model.total) : "—"}</span>
+                </div>;
+              })}
+            </div>;
+          })}
+        </div>
+      </section>}
+      <fieldset className="usage-companion-controls" disabled={response?.corrupt}>
+        <Segment label={t("usage.companion.menuBarShows")} value={current.menuBarMetric} options={MENU_METRICS} optionLabel={value => t(MENU_METRIC_KEYS[value])} onChange={value => updateSettings({ menuBarMetric: value })} />
+        <Segment label={t("usage.companion.window")} value={current.chartHours} options={WINDOWS} optionLabel={value => t(WINDOW_KEYS[value])} onChange={value => updateSettings({ chartHours: value, bucketMinutes: bucketMinutesForWindow(value) })} />
+        <Segment label={t("usage.companion.style")} value={current.chartStyle} options={CHART_STYLES} optionLabel={value => value === "line" ? t("usage.companion.styleLine") : t("usage.companion.styleStacked")} onChange={value => updateSettings({ chartStyle: value })} />
+        <SelectControl label={t("usage.companion.metric")} value={current.tokenMetric} options={TOKEN_METRICS} optionLabel={value => t(TOKEN_METRIC_KEYS[value])} onChange={value => updateSettings({ tokenMetric: value })} />
+        <SelectControl label={t("usage.companion.groupBy")} value={current.chartGrouping} options={GROUPINGS} optionLabel={value => value === "model" ? t("usage.companion.groupModel") : t("usage.companion.groupAccount")} onChange={value => updateSettings({ chartGrouping: value })} />
+        <fieldset className="usage-companion-switches">
+          <legend className="field-label">{t("usage.companion.popoverSections")}</legend>
+          {SECTION_OPTIONS.map(([key, label]) => (
+            <div key={key} className="usage-companion-switch">
+              <span>{t(label)}</span>
+              <button type="button" className={`toggle ${current[key] ? "on" : ""}`} aria-label={t(label)} aria-pressed={current[key]} onClick={() => updateSettings({ [key]: !current[key] })}><span className="toggle-knob" /></button>
+            </div>
+          ))}
+        </fieldset>
+        <details className="usage-companion-advanced">
+          <summary>{t("usage.companion.advanced")}</summary>
+          <div className="usage-companion-advanced-body">
+            <SelectControl label={t("usage.companion.aggregation")} value={current.aggregation} options={AGGREGATIONS} optionLabel={value => t(AGGREGATION_KEYS[value])} onChange={value => updateSettings({ aggregation: value })} />
+            <label className="usage-companion-control">
+              <span className="field-label">{t("usage.companion.menuText")}</span>
+              <input value={current.menuBarTemplate ?? ""} onChange={event => updateSettings({ menuBarTemplate: event.target.value })} maxLength={200} />
+              <span className="muted text-caption">{t("usage.companion.placeholders")} <code>{"{requests} {totalTokens} {inputTokens} {outputTokens} {costUsd} {quotaPercent}"}</code></span>
+            </label>
+            {providerNames.length > 0 && <fieldset className="usage-companion-check-list"><legend className="field-label">{t("usage.companion.hideProviders")}</legend>{providerNames.map(provider => <label key={provider}><input type="checkbox" checked={hiddenProviderSet.has(provider)} onChange={event => updateSettings({ hiddenProviders: event.target.checked ? [...current.hiddenProviders, provider] : current.hiddenProviders.filter(item => item !== provider) })} /> <span>{provider}</span></label>)}</fieldset>}
+          </div>
+        </details>
+      </fieldset>
+      <div className={`usage-companion-save-status${saveState === "error" ? " is-error" : ""}`} role={saveState === "error" ? "alert" : "status"}>
+        {saveMessage || "\u00a0"}
+        {saveState === "error" && <button type="button" className="btn btn-ghost btn-sm" onClick={() => { setSaveState("saving"); }}>{t("common.retry")}</button>}
+      </div>
+      <button type="button" className="btn btn-ghost btn-sm" onClick={() => void reset()}>{t("usage.companion.reset")}</button>
+      <p className="muted text-caption">{t("usage.companion.footer")}</p>
+    </section>
+  );
+}
diff --git a/gui/src/pages/usage-companion-utils.ts b/gui/src/pages/usage-companion-utils.ts
new file mode 100644
index 00000000000..9c14c85c117
--- /dev/null
+++ b/gui/src/pages/usage-companion-utils.ts
@@ -0,0 +1,215 @@
+export type TimelineMetric = "total" | "input" | "output" | "cached";
+export type TimelineAggregation = "sum" | "average" | "max";
+export type TimelineGrouping = "model" | "modelAccount";
+export type CompanionMenuBarMetric = "requests" | "tokens" | "cost" | "quota" | "none";
+export type CompanionChartStyle = "line" | "stackedBar";
+export type ChartHours = 6 | 24 | 72 | 168;
+
+export interface CompanionSettings {
+  menuBarMetric: CompanionMenuBarMetric;
+  menuBarTemplate: string | null;
+  showToday: boolean;
+  showChart: boolean;
+  showModels: boolean;
+  showCost: boolean;
+  showAccounts: boolean;
+  chartHours: ChartHours;
+  bucketMinutes: number;
+  chartStyle: CompanionChartStyle;
+  tokenMetric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  chartGrouping: TimelineGrouping;
+  models: string[] | null;
+  hiddenProviders: string[];
+}
+
+export interface TimelineSeries {
+  id: string;
+  provider: string;
+  model: string;
+  accountLogLabel?: string;
+  total: number;
+  points: number[];
+}
+
+export interface UsageTimeline {
+  start: number;
+  end: number;
+  bucketSeconds: number;
+  buckets: number;
+  metric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  grouping: TimelineGrouping;
+  series: TimelineSeries[];
+  availableModels: string[];
+  missingMeasurements: number;
+  truncated: boolean;
+}
+
+export interface CompanionSettingsResponse {
+  settings: CompanionSettings;
+  updatedAt: number | null;
+  defaults: CompanionSettings;
+  corrupt?: boolean;
+  companion?: {
+    lastSeenAt: number | null;
+    kind?: "menuBar" | "desktop";
+  };
+}
+
+export const CHART_BUCKET_MINUTES: Record<ChartHours, number> = {
+  6: 15,
+  24: 60,
+  72: 180,
+  168: 360,
+};
+
+export function bucketMinutesForWindow(hours: ChartHours): number {
+  return CHART_BUCKET_MINUTES[hours];
+}
+
+export function formatCompanionTokens(value: number): string {
+  if (value < 1_000) return String(Math.round(value));
+  const units = [
+    [1_000_000_000_000, "T"],
+    [1_000_000_000, "B"],
+    [1_000_000, "M"],
+    [1_000, "K"],
+  ] as const;
+  for (let index = 0; index < units.length; index += 1) {
+    const [threshold, suffix] = units[index]!;
+    if (value >= threshold) {
+      const rounded = Math.round(value / threshold);
+      if (rounded >= 1000 && index > 0) {
+        const [largerThreshold, largerSuffix] = units[index - 1]!;
+        return `${Math.round(value / largerThreshold)}${largerSuffix}`;
+      }
+      return `${rounded}${suffix}`;
+    }
+  }
+  return String(Math.round(value));
+}
+
+export interface CompanionModelGroup {
+  provider: string;
+  models: { id: string; total: number }[];
+  total: number;
+}
+
+export function groupCompanionModels(
+  available: string[],
+  totals: Map<string, number>,
+): CompanionModelGroup[] {
+  const groups = new Map<string, CompanionModelGroup>();
+  for (const id of available) {
+    const provider = id.includes("/") ? id.slice(0, id.indexOf("/")) : id;
+    const group = groups.get(provider) ?? { provider, models: [], total: 0 };
+    const total = totals.get(id) ?? 0;
+    group.models.push({ id, total });
+    group.total += total;
+    groups.set(provider, group);
+  }
+  return Array.from(groups.values())
+    .map(group => ({
+      ...group,
+      models: group.models.toSorted((a, b) => b.total - a.total || a.id.localeCompare(b.id)),
+    }))
+    .toSorted((a, b) => b.total - a.total || a.provider.localeCompare(b.provider));
+}
+
+export function toggleCompanionModels(
+  selected: string[] | null,
+  available: string[],
+  ids: string[],
+  on: boolean,
+): string[] | null {
+  const availableSet = new Set(available);
+  const next = new Set((selected ?? available).filter(id => availableSet.has(id)));
+  for (const id of ids) {
+    if (on) next.add(id);
+    else next.delete(id);
+  }
+  if (available.length > 0 && available.every(id => next.has(id))) return null;
+  return available.filter(id => next.has(id));
+}
+
+export function buildCompanionSettingsPatch(
+  patch: Partial<CompanionSettings>,
+  availableModels: readonly string[] = [],
+): Partial<CompanionSettings> {
+  const next = { ...patch };
+  if (typeof next.menuBarTemplate === "string" && next.menuBarTemplate.trim() === "") {
+    next.menuBarTemplate = null;
+  }
+  if (next.models !== undefined && availableModels.length > 0) {
+    const selected = next.models ?? [];
+    const selectedSet = new Set(selected);
+    const allSelected = selected.length === availableModels.length
+      && availableModels.every(model => selectedSet.has(model));
+    if (allSelected) next.models = null;
+  }
+  return next;
+}
+
+export function chartPolylinePoints(
+  points: readonly number[],
+  width: number,
+  height: number,
+  maxValue: number,
+  padding = 8,
+): string {
+  const plotWidth = Math.max(0, width - padding * 2);
+  const plotHeight = Math.max(0, height - padding * 2);
+  const denominator = Math.max(maxValue, 1);
+  const divisor = Math.max(points.length - 1, 1);
+  return points.map((value, index) => {
+    const x = padding + plotWidth * index / divisor;
+    const y = padding + plotHeight * (1 - Math.max(0, value) / denominator);
+    return `${x},${y}`;
+  }).join(" ");
+}
+
+export interface StackedBarRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  seriesIndex: number;
+  bucketIndex: number;
+}
+
+export function chartStackedBarRects(
+  series: readonly Pick<TimelineSeries, "points">[],
+  width: number,
+  height: number,
+  maxValue: number,
+  padding = 8,
+): StackedBarRect[] {
+  const buckets = series[0]?.points.length ?? 0;
+  if (buckets === 0) return [];
+  const plotWidth = Math.max(0, width - padding * 2);
+  const plotHeight = Math.max(0, height - padding * 2);
+  const denominator = Math.max(maxValue, 1);
+  const gap = Math.min(3, plotWidth / Math.max(buckets * 8, 1));
+  const barWidth = Math.max(0, plotWidth / buckets - gap);
+  const rects: StackedBarRect[] = [];
+  for (let bucketIndex = 0; bucketIndex < buckets; bucketIndex += 1) {
+    let offset = 0;
+    for (let seriesIndex = 0; seriesIndex < series.length; seriesIndex += 1) {
+      const value = Math.max(0, series[seriesIndex]?.points[bucketIndex] ?? 0);
+      const barHeight = plotHeight * value / denominator;
+      if (barHeight > 0) {
+        rects.push({
+          x: padding + bucketIndex * (plotWidth / buckets) + gap / 2,
+          y: padding + plotHeight - offset - barHeight,
+          width: barWidth,
+          height: barHeight,
+          seriesIndex,
+          bucketIndex,
+        });
+      }
+      offset += barHeight;
+    }
+  }
+  return rects;
+}
diff --git a/gui/src/provider-icons.ts b/gui/src/provider-icons.ts
index e7906e773cd..11bc1be0c2d 100644
--- a/gui/src/provider-icons.ts
+++ b/gui/src/provider-icons.ts
@@ -84,6 +84,7 @@ const PROVIDER_ICON_ALIASES: Record<string, string> = {
   parallel: "parallel.svg",
   sambanova: "sambanova.svg",
   scaleway: "scaleway.svg",
+  stepfun: "stepfun-color.svg",
   siliconflow: "siliconflow.svg",
   synthetic: "synthetic.svg",
   together: "together.svg",
@@ -168,6 +169,7 @@ const PROVIDER_DISPLAY_NAMES: Record<string, string> = {
   huggingface: "Hugging Face",
   "qwen-cloud": "Qwen Cloud",
   siliconflow: "SiliconFlow",
+  stepfun: "StepFun",
   "tencent-coding-plan": "Tencent Cloud Coding Plan",
   codebuddy: "CodeBuddy",
   "codebuddy-cn": "CodeBuddy CN",
diff --git a/gui/src/stop-proxy.ts b/gui/src/stop-proxy.ts
index 0798f9b8f0b..23a2e68688f 100644
--- a/gui/src/stop-proxy.ts
+++ b/gui/src/stop-proxy.ts
@@ -1,7 +1,21 @@
-export interface ProxyStopOutcome {
-  accepted: boolean;
-  message?: string;
-}
+/**
+ * Three answers, because the button having been pressed is not evidence that the server
+ * accepted anything.
+ *
+ * `accepted` means the proxy said so, or stopped answering afterwards — the normal shape of
+ * a clean shutdown, since the process that would send the response is the one going away.
+ * `rejected` means it answered and refused. `unknown` means the request's fate is genuinely
+ * not known: it may never have arrived, or it arrived and the answer was lost. These used to
+ * collapse into `accepted`, which turned "the user clicked" into "the server acted" and left
+ * the dashboard claiming a stop that had not happened.
+ *
+ * An unknown is resolved by READING the instance again, never by sending the mutation a
+ * second time: a stop that did arrive would be repeated against whatever now holds the port.
+ */
+export type ProxyStopOutcome =
+  | { status: "accepted"; message?: undefined }
+  | { status: "rejected"; message: string }
+  | { status: "unknown"; message: string };
 
 interface ProxyStopPayload {
   success?: unknown;
@@ -10,12 +24,20 @@ interface ProxyStopPayload {
 }
 
 const DEFAULT_STOP_TIMEOUT_MS = 15_000;
+/** Short on purpose: this runs after the user has already waited out the stop request. */
+const DEFAULT_LIVENESS_TIMEOUT_MS = 3_000;
 
 export interface ProxyStopOptions {
   fetchFn?: typeof fetch;
   timeoutMs?: number;
   formatFailure?: (status: number) => string;
+  /** Shown when the follow-up read finds the proxy still answering. */
+  formatStillRunning?: () => string;
+  /** Shown when neither the request nor the follow-up read settled the question. */
+  formatUnknown?: () => string;
   mode?: "standalone" | "client";
+  /** Budget for the follow-up liveness read. */
+  livenessTimeoutMs?: number;
 }
 
 function failureMessage(
@@ -28,16 +50,34 @@ function failureMessage(
   return formatFailure(status);
 }
 
-function isAbortError(error: unknown): boolean {
-  return error instanceof DOMException
-    ? error.name === "AbortError"
-    : error instanceof Error && error.name === "AbortError";
+/**
+ * Reads `/healthz` to find out whether the runtime the stop targeted is still there.
+ *
+ * A refused connection is the answer we want: nothing is listening, so the stop took effect.
+ * A successful read is the opposite. Anything else stays undecided rather than being rounded
+ * to either.
+ */
+async function readLiveness(
+  apiBase: string,
+  fetchFn: typeof fetch,
+  timeoutMs: number,
+): Promise<"gone" | "answering" | "undecided"> {
+  try {
+    const response = await fetchFn(`${apiBase}/healthz`, {
+      method: "GET",
+      cache: "no-store",
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return response.ok ? "answering" : "undecided";
+  } catch {
+    return "gone";
+  }
 }
 
 /**
- * A dropped connection is expected once shutdown starts. A received response, however,
- * is authoritative: either a non-2xx status or `{ success: false }` means the UI must
- * leave its pending state and surface the server's restore error.
+ * A received response is authoritative: a non-2xx status or `{ success: false }` is a refusal
+ * the UI must surface. A lost connection is authoritative about nothing, so it is resolved by
+ * reading the instance rather than assumed.
  */
 export async function requestProxyStop(
   apiBase: string,
@@ -47,7 +87,10 @@ export async function requestProxyStop(
     fetchFn = fetch,
     timeoutMs = DEFAULT_STOP_TIMEOUT_MS,
     formatFailure = status => `Failed to stop proxy (HTTP ${status}).`,
+    formatStillRunning = () => "The proxy is still answering, so it did not stop.",
+    formatUnknown = () => "The proxy did not confirm the stop. Check whether it is still running.",
     mode = "standalone",
+    livenessTimeoutMs = DEFAULT_LIVENESS_TIMEOUT_MS,
   } = options;
   let response: Response;
   try {
@@ -57,14 +100,33 @@ export async function requestProxyStop(
       ...(mode === "client" ? { headers: { "Content-Type": "application/json" }, body: "{}" } : {}),
       signal: AbortSignal.timeout(timeoutMs),
     });
-  } catch (error) {
-    if (isAbortError(error)) return { accepted: true };
-    return { accepted: true };
+  } catch {
+    /*
+     * Timeout, abort, a refused connection and a connection dropped mid-response all land
+     * here and are different events. Disconnecting a client does not end the process, so
+     * there is nothing to re-read and the question stays open. Stopping the proxy does end
+     * it, so its absence afterwards is the evidence.
+     */
+    if (mode === "client") return { status: "unknown", message: formatUnknown() };
+    const liveness = await readLiveness(apiBase, fetchFn, livenessTimeoutMs);
+    if (liveness === "gone") return { status: "accepted" };
+    if (liveness === "answering") return { status: "unknown", message: formatStillRunning() };
+    return { status: "unknown", message: formatUnknown() };
   }
 
-  const payload = await response.json().catch(() => null) as ProxyStopPayload | null;
+  let payload: ProxyStopPayload | null = null;
+  let bodyRead = true;
+  try {
+    payload = await response.json() as ProxyStopPayload;
+  } catch {
+    // The status line arrived and the body did not. On a refusal that is already enough to
+    // report; on an apparent success it is not, because `success: false` rides in the body
+    // this just lost.
+    bodyRead = false;
+  }
   if (!response.ok || payload?.success === false) {
-    return { accepted: false, message: failureMessage(payload, response.status, formatFailure) };
+    return { status: "rejected", message: failureMessage(payload, response.status, formatFailure) };
   }
-  return { accepted: true };
+  if (!bodyRead) return { status: "unknown", message: formatUnknown() };
+  return { status: "accepted" };
 }
diff --git a/gui/src/styles-usage-workspace.css b/gui/src/styles-usage-workspace.css
index aa9e3bb45c6..91485e1a217 100644
--- a/gui/src/styles-usage-workspace.css
+++ b/gui/src/styles-usage-workspace.css
@@ -214,6 +214,206 @@
   gap: 6px;
 }
 
+.usage-companion-panel {
+  display: grid;
+  gap: 16px;
+  padding-top: 4px;
+}
+.usage-companion-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+}
+.usage-companion-header .panel-title { margin: 0; }
+.usage-companion-header .card-sub { margin: 4px 0 0; }
+.usage-companion-install {
+  display: grid;
+  gap: 10px;
+  padding: 12px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--surface);
+}
+.usage-companion-install summary { cursor: pointer; color: var(--text); font-size: 12px; font-weight: 600; }
+.usage-companion-install-status { display: flex; align-items: center; gap: 8px; color: var(--text); font-size: 12px; }
+.usage-companion-install-dot { width: 8px; height: 8px; border-radius: 50%; background: var(--green); }
+.usage-companion-install-steps { display: grid; gap: 8px; margin: 0; padding-left: 20px; color: var(--muted); font-size: 12px; }
+.usage-companion-install-steps .btn { margin-left: 6px; }
+.usage-companion-install-last-seen { margin: 0; }
+.usage-companion-install-command { display: block; overflow-x: auto; padding: 7px 9px; border-radius: var(--radius-xs); background: var(--raised); color: var(--text); font-size: 11px; }
+.usage-companion-models { display: grid; gap: 8px; }
+.usage-companion-models-header { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
+.usage-companion-models-header > div { display: flex; align-items: baseline; gap: 8px; min-width: 0; }
+.usage-companion-models-count { white-space: nowrap; }
+.usage-companion-models-list { max-height: 280px; overflow-y: auto; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface); }
+.usage-companion-model-group + .usage-companion-model-group { border-top: 1px solid var(--border-soft); }
+.usage-companion-model-group-header { position: sticky; top: 0; z-index: 1; display: flex; align-items: center; gap: 7px; padding: 8px 10px; background: color-mix(in srgb, var(--surface) 92%, var(--raised)); }
+.usage-companion-model-provider { flex: 1; min-width: 0; overflow: hidden; color: var(--text); font-size: 12px; font-weight: 600; text-overflow: ellipsis; white-space: nowrap; }
+.usage-companion-model-chip { padding: 2px 5px; border: 1px solid var(--border); border-radius: 999px; color: var(--muted); }
+.usage-companion-model-group-header .switch { flex: 0 0 auto; }
+.usage-companion-model-row { display: flex; align-items: center; gap: 8px; min-width: 0; padding: 7px 10px 7px 18px; }
+.usage-companion-model-row .switch { flex: 0 0 auto; }
+.usage-companion-model-row code { min-width: 0; overflow: hidden; color: var(--text); text-overflow: ellipsis; white-space: nowrap; }
+.usage-companion-model-row.is-off code { color: var(--faint); text-decoration: line-through; }
+.usage-companion-model-total { flex: 0 0 auto; margin-left: auto; font-variant-numeric: tabular-nums; }
+.usage-companion-chart { min-width: 0; }
+.usage-companion-chart svg { display: block; width: 100%; height: 160px; overflow: visible; }
+.usage-companion-axis { stroke: var(--border); stroke-width: 1; }
+.usage-companion-axis-label { fill: var(--muted); font-size: 10px; }
+.usage-companion-legend { display: flex; flex-wrap: wrap; gap: 8px 14px; margin-top: 8px; }
+.usage-companion-legend-item { display: inline-flex; align-items: center; gap: 5px; color: var(--muted); font-size: 11px; }
+.usage-companion-swatch { width: 8px; height: 8px; border-radius: 50%; }
+.usage-companion-chart-skeleton {
+  height: 160px;
+  border: 1px solid var(--border-soft);
+  background: var(--surface);
+  animation: pulse 1.2s ease-in-out infinite alternate;
+}
+.usage-companion-chart-state { display: flex; align-items: center; gap: 10px; min-height: 160px; color: var(--muted); }
+.usage-companion-controls { display: grid; gap: 14px; border: 0; padding: 0; margin: 0; min-width: 0; }
+.usage-companion-control { display: grid; gap: 6px; min-width: 0; }
+.usage-companion-control > select, .usage-companion-control > input {
+  min-height: 34px; width: 100%; padding: 6px 9px;
+  border: 1px solid var(--border); border-radius: var(--radius-xs);
+  background: var(--raised); color: var(--text); font: inherit;
+}
+.usage-companion-control > .usage-segmented { width: fit-content; max-width: 100%; }
+.field-label { color: var(--muted); font-size: 11.5px; font-weight: 550; }
+.usage-companion-switches, .usage-companion-check-list {
+  display: grid; gap: 8px; border: 0; padding: 0; margin: 0;
+}
+.usage-companion-switches legend { padding: 0; margin-bottom: 2px; }
+.usage-companion-switch { display: flex; align-items: center; justify-content: space-between; gap: 12px; color: var(--text); font-size: 12px; }
+.usage-companion-switch .toggle { flex: 0 0 auto; }
+.usage-companion-advanced { border-top: 1px solid var(--border-soft); padding-top: 12px; }
+.usage-companion-advanced summary { cursor: pointer; color: var(--text); font-size: 12px; font-weight: 600; }
+.usage-companion-advanced-body { display: grid; gap: 14px; padding-top: 12px; }
+.usage-companion-check-list label { display: flex; align-items: center; gap: 7px; color: var(--text); font-size: 12px; }
+.usage-companion-save-status { display: flex; align-items: center; gap: 8px; min-height: 26px; color: var(--muted); font-size: 11.5px; }
+.usage-companion-save-status.is-error { color: var(--red); }
+.usage-companion-loading { min-height: 160px; color: var(--muted); }
+
 @media (max-width: 640px) {
   .usage-source-row { align-items: flex-start; flex-direction: column; }
+  .usage-companion-header { align-items: stretch; flex-direction: column; }
+  .usage-companion-header .btn { align-self: flex-start; }
+  .usage-companion-control > .usage-segmented { width: 100%; }
+  .usage-companion-control > .usage-segmented .usage-segmented-btn { flex: 1 1 0; min-width: 0; padding-inline: 6px; }
+}
+
+/* ── Models table ─────────────────────────────────────── */
+
+/*
+  `.tbl` is `width: 100%`, which divides the shell's width across this table's twelve columns
+  until an eight-digit token total folds onto a second line. Give the table the width its content
+  asks for and let the shell scroll sideways instead; `.tbl-wrap` is already `overflow-x: auto`,
+  so `min-width: 100%` is what keeps the table filling a shell wide enough to hold it.
+
+  Every selector here is doubled as `.tbl.usage-models-tbl`, which is not decoration. This file is
+  `@import`ed from the top of `styles.css`, so the whole of `styles.css` cascades after it: a bare
+  `.usage-models-tbl { width: max-content }` ties `.tbl { width: 100% }` on specificity and loses
+  on source order, and the squeeze comes straight back. The rules that already lived in this file
+  buy the same margin with a descendant `.usw-section` prefix.
+*/
+.tbl.usage-models-tbl {
+  --usage-models-model-col: 14rem;
+  --usage-models-provider-col: 11rem;
+  width: max-content;
+  min-width: 100%;
+}
+
+.tbl.usage-models-tbl th,
+.tbl.usage-models-tbl td {
+  white-space: nowrap;
+}
+
+/* The share bar carries no text, so its column has no intrinsic width to size to. */
+.tbl.usage-models-tbl th:nth-child(3),
+.tbl.usage-models-tbl td:nth-child(3) {
+  min-width: 9rem;
+}
+
+/*
+  Model and provider stay legible while the numbers scroll under them. The scrollport is
+  `.tbl-wrap`, whose own `var(--space-3)` padding scrolls with the content, so — the same trick
+  the sticky header above plays with `top` — each offset is one padding step negative and the
+  stuck cell repaints that strip with its own background. The widths are fixed because the second
+  column's offset is the first column's width, and `box-sizing: border-box` is global, so the
+  declared width is the rendered width. A value too long for its column clips and keeps its full
+  text in the cell's `title`.
+*/
+.tbl.usage-models-tbl th:nth-child(1),
+.tbl.usage-models-tbl td:nth-child(1),
+.tbl.usage-models-tbl th:nth-child(2),
+.tbl.usage-models-tbl td:nth-child(2) {
+  position: sticky;
+  z-index: 2;
+  background: var(--surface);
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.tbl.usage-models-tbl th:nth-child(1),
+.tbl.usage-models-tbl td:nth-child(1) {
+  left: calc(-1 * var(--space-3));
+  width: var(--usage-models-model-col);
+  min-width: var(--usage-models-model-col);
+  max-width: var(--usage-models-model-col);
+}
+
+.tbl.usage-models-tbl th:nth-child(2),
+.tbl.usage-models-tbl td:nth-child(2) {
+  left: calc(var(--usage-models-model-col) - var(--space-3));
+  width: var(--usage-models-provider-col);
+  min-width: var(--usage-models-provider-col);
+  max-width: var(--usage-models-provider-col);
+}
+
+/*
+  Seam between the pinned pair and the scrolling columns, on the body rows only: the sticky
+  header cells already carry a `box-shadow` that repaints the header strip, and a second
+  declaration here would replace it rather than add to it.
+*/
+.tbl.usage-models-tbl tbody td:nth-child(2) {
+  box-shadow: inset -1px 0 0 var(--border-soft);
+}
+
+/*
+  A pinned cell has to stay opaque on hover. Two separate reasons, and missing either one lets
+  the scrolled columns read straight through the pinned pair: `.tbl tbody tr:hover td` outranks
+  the opaque fill above on its own, and `--hover` is a 3% overlay rather than a colour, so
+  assigning it alone replaces the surface with something almost entirely transparent. Paint the
+  overlay as a layer over the surface instead of in place of it.
+*/
+.tbl.usage-models-tbl tbody tr:hover td:nth-child(1),
+.tbl.usage-models-tbl tbody tr:hover td:nth-child(2) {
+  background: linear-gradient(var(--hover), var(--hover)), var(--surface);
+}
+
+/* The corner cells sit above both the scrolling body and the rest of the sticky header row. */
+.tbl.usage-models-tbl thead th:nth-child(1),
+.tbl.usage-models-tbl thead th:nth-child(2) {
+  z-index: 3;
+}
+
+/* The exclusion caption is a line under the amount, never a wrap of the same line. */
+.usage-cost-note {
+  display: block;
+}
+
+/* Narrower than this, two pinned columns cost more reading room than scrolling the table does. */
+@media (max-width: 720px) {
+  .tbl.usage-models-tbl th:nth-child(1),
+  .tbl.usage-models-tbl td:nth-child(1),
+  .tbl.usage-models-tbl th:nth-child(2),
+  .tbl.usage-models-tbl td:nth-child(2) {
+    position: static;
+    width: auto;
+    min-width: 0;
+    max-width: none;
+  }
+  .tbl.usage-models-tbl tbody td:nth-child(2) {
+    box-shadow: none;
+  }
 }
diff --git a/gui/src/styles.css b/gui/src/styles.css
index 28c9277c1ed..9bdd757f6ae 100644
--- a/gui/src/styles.css
+++ b/gui/src/styles.css
@@ -87,8 +87,8 @@
   --radius-round: 50%;
   --radius-pill: 999px;
 
-  /* typography: product UI first, Korean-safe fallbacks, mono only for machine data */
-  --font-ui: "OpenAI Sans", "Pretendard Variable", Pretendard, "Noto Sans KR", "Apple SD Gothic Neo", "Malgun Gothic", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, system-ui, sans-serif;
+  /* Keep product fonts first, then system UI fonts before Korean fallbacks that also cover Latin. */
+  --font-ui: "OpenAI Sans", "Pretendard Variable", Pretendard, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, system-ui, "Apple SD Gothic Neo", "Noto Sans KR", "Malgun Gothic", sans-serif;
   --font-code: ui-monospace, "SFMono-Regular", "Cascadia Code", "JetBrains Mono", "Noto Sans Mono CJK KR", Menlo, Consolas, monospace;
   --font: var(--font-ui);
   --mono: var(--font-code);
diff --git a/gui/src/styles/claude-desktop-mode-picker.css b/gui/src/styles/claude-desktop-mode-picker.css
new file mode 100644
index 00000000000..ee6db473520
--- /dev/null
+++ b/gui/src/styles/claude-desktop-mode-picker.css
@@ -0,0 +1,22 @@
+/* ── Desktop connection mode picker (first-party default / gateway opt-in) ── */
+.claude-mode-picker {
+  display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 10px;
+  margin: 0 0 14px; padding: 10px 14px 12px; border: 1px solid var(--border); border-radius: var(--radius);
+  background: var(--surface);
+}
+.claude-mode-picker legend { padding: 0 6px; font-size: 12px; font-weight: 600; color: var(--muted); }
+.claude-mode-picker:disabled { opacity: 0.6; }
+.claude-mode-option {
+  display: grid; grid-template-columns: auto 1fr; column-gap: 10px; align-items: start;
+  padding: 10px 12px; border: 1px solid var(--border); border-radius: var(--radius); cursor: pointer;
+}
+.claude-mode-option.active { border-color: var(--accent); }
+.claude-mode-option input { margin-top: 3px; }
+.claude-mode-title { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; font-size: 13px; font-weight: 600; }
+.claude-mode-hint { grid-column: 2; margin-top: 4px; font-size: 12px; color: var(--muted); line-height: 1.4; }
+.claude-mode-default, .claude-mode-current {
+  padding: 1px 6px; border-radius: var(--radius-xs); font-size: 10px; font-weight: 600; letter-spacing: 0.02em;
+}
+.claude-mode-default { background: color-mix(in srgb, var(--accent) 12%, transparent); color: var(--accent); }
+.claude-mode-current { background: color-mix(in srgb, var(--green) 15%, transparent); color: var(--green); }
+.claude-mode-switch-note { grid-column: 1 / -1; font-size: 12px; color: var(--amber); }
diff --git a/gui/src/styles/provider-workspace-settings.css b/gui/src/styles/provider-workspace-settings.css
index 34a9e808971..5dc15873e1f 100644
--- a/gui/src/styles/provider-workspace-settings.css
+++ b/gui/src/styles/provider-workspace-settings.css
@@ -29,6 +29,7 @@
   background: var(--raised); border-radius: var(--radius-xs);
 }
 .pwi-auth-state--error { color: var(--red); background: var(--red-soft); justify-content: space-between; }
+.pwi-auth-state--stale { color: var(--amber); background: var(--amber-soft); justify-content: space-between; }
 .pwi-auth-state--empty { justify-content: center; }
 
 .pwi-auth-actions { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; margin-top: 8px; }
diff --git a/gui/src/use-codex-restart.ts b/gui/src/use-codex-restart.ts
index ba6d6c7bdb5..30c85d42a92 100644
--- a/gui/src/use-codex-restart.ts
+++ b/gui/src/use-codex-restart.ts
@@ -2,11 +2,13 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import { useI18n } from "./i18n/shared";
 import { requestCodexRestart } from "./codex-restart";
 import type { CodexRestartCode } from "./codex-restart";
+import { confirmAction } from "./action-dialogs";
+import type { NoticeTone } from "./ui";
 
 export interface CodexRestartController {
   restarting: boolean;
   /**
-   * Resolves to the response code, or null when the user declined the confirm or
+   * Resolves to the response code, or null when the user declined the consent gate or
    * the call failed. Callers that track staleness must treat BOTH `stopped` and
    * `nothing_running` as "no stale app-server remains" — the second is the race
    * where the target exited on its own, and refreshing on only the first would
@@ -23,6 +25,17 @@ export interface CodexRestartOptions {
    * models page.
    */
   onSettled?: (code: CodexRestartCode) => void;
+  /**
+   * Where the outcome is shown. Required, and deliberately not defaulted: this used to
+   * be `alert()`, which draws nothing inside the app, so every result — including a
+   * partial stop that left app-servers running — was reported to no one. A consumer that
+   * forgets to render it now fails to compile instead of failing silently.
+   *
+   * The sink has to outlive the surface that called `restart`. Enumeration can take tens
+   * of seconds, and a user who navigates away meanwhile is exactly the user who needs to
+   * be told that app-servers survived, so both consumers report through the shell.
+   */
+  report: (message: string, tone: NoticeTone) => void;
 }
 
 /** True when the outcome means nothing stale is left running. */
@@ -33,14 +46,18 @@ export function isRestartSettled(code: CodexRestartCode): boolean {
 /**
  * Shared restart action for the sidebar and the models page.
  *
- * The confirm is not ceremony: stopping an app-server can interrupt a Codex turn
+ * The consent gate is not ceremony: stopping an app-server can interrupt a Codex turn
  * that is running right now. That is precisely the consent the startup path
  * refuses to assume on the user's behalf (src/codex/app-server-processes.ts),
  * and a dashboard click is where the user gives it.
+ *
+ * It is an in-page dialog rather than `confirm()` because the app's webview implements
+ * no JavaScript panel delegate: `confirm()` returned false there without drawing
+ * anything, so this button took its early return on every click and did nothing at all.
  */
 export function useCodexRestart(
   apiBase: string,
-  options: CodexRestartOptions = {},
+  options: CodexRestartOptions,
 ): CodexRestartController {
   const { t } = useI18n();
   const [restarting, setRestarting] = useState(false);
@@ -48,20 +65,60 @@ export function useCodexRestart(
   // completion path must not touch state after unmount.
   const mounted = useRef(true);
   const onSettled = useRef(options.onSettled);
+  const report = useRef(options.report);
+  /*
+   * The subject the consent is about. A restart names one backend, and the dialog is
+   * asynchronous now, so the target can change or the surface can go away while the question
+   * is still on screen. Holding the current base in a ref lets the confirmed path check that
+   * what the user approved is still what would be stopped.
+   */
+  const currentApiBase = useRef(apiBase);
+  /** The consent currently on screen, so a changed subject can withdraw it. */
+  const pendingConsent = useRef<AbortController | null>(null);
 
   useEffect(() => {
     // Written in an effect, not during render: a ref assignment in the render
     // body is exactly what the react-compiler lint forbids.
     onSettled.current = options.onSettled;
-  }, [options.onSettled]);
+    report.current = options.report;
+  }, [options.onSettled, options.report]);
+
+  useEffect(() => {
+    // A new base is a new subject: a consent granted for the old one no longer describes
+    // what would happen, so it is withdrawn rather than silently re-pointed.
+    currentApiBase.current = apiBase;
+    return () => {
+      pendingConsent.current?.abort();
+      pendingConsent.current = null;
+    };
+  }, [apiBase]);
 
   useEffect(() => {
     mounted.current = true;
-    return () => { mounted.current = false; };
+    return () => {
+      mounted.current = false;
+      pendingConsent.current?.abort();
+      pendingConsent.current = null;
+    };
   }, []);
 
   const restart = useCallback(async (): Promise<CodexRestartCode | null> => {
-    if (!confirm(t("dash.codexRestartConfirm"))) return null;
+    const consent = new AbortController();
+    pendingConsent.current?.abort();
+    pendingConsent.current = consent;
+    const consented = await confirmAction({
+      message: t("dash.codexRestartConfirm"),
+      confirmLabel: t("dash.codexRestart"),
+      tone: "danger",
+      signal: consent.signal,
+    });
+    if (pendingConsent.current === consent) pendingConsent.current = null;
+    /*
+     * Confirmed for THIS base, while this surface was still mounted. Either could have
+     * changed while the dialog was open, and sending anyway would apply the user's approval
+     * to a subject they were never shown.
+     */
+    if (!consented || !mounted.current || currentApiBase.current !== apiBase) return null;
     setRestarting(true);
     const outcome = await requestCodexRestart(apiBase, {
       formatFailure: status => t("dash.codexRestartFailed", { status: String(status) }),
@@ -71,20 +128,21 @@ export function useCodexRestart(
     });
     if (mounted.current) setRestarting(false);
 
-    if (!outcome.ok || !outcome.result) {
-      alert(outcome.message);
+    if (!outcome.ok) {
+      report.current(outcome.message, "err");
       return null;
     }
 
     const result = outcome.result;
     if (result.code === "stopped") {
-      alert(t("dash.codexRestartDone", { count: String(result.stopped.length) }));
+      report.current(t("dash.codexRestartDone", { count: String(result.stopped.length) }), "ok");
     } else if (result.code === "nothing_running") {
-      alert(t("dash.codexRestartNothing"));
+      report.current(t("dash.codexRestartNothing"), "ok");
     } else if (result.code === "enumeration_unavailable") {
-      alert(t("dash.codexRestartUnknown"));
+      report.current(t("dash.codexRestartUnknown"), "warn");
     } else {
-      alert(t("dash.codexRestartPartial", { count: String(result.surviving.length) }));
+      // Degraded, not failed: something is still running, so it must not read as success.
+      report.current(t("dash.codexRestartPartial", { count: String(result.surviving.length) }), "warn");
     }
 
     // Only while mounted: a settled callback typically starts a refresh fetch,
@@ -95,4 +153,3 @@ export function useCodexRestart(
 
   return { restarting, restart };
 }
-
diff --git a/gui/tests/action-dialogs.test.ts b/gui/tests/action-dialogs.test.ts
new file mode 100644
index 00000000000..e2646587f77
--- /dev/null
+++ b/gui/tests/action-dialogs.test.ts
@@ -0,0 +1,293 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import { confirmAction, requestTextValue } from "../src/action-dialogs";
+
+/**
+ * Runtime behaviour of the in-page replacements for confirm/alert/prompt.
+ *
+ * These tests assert the ABSENCE of the platform dialogs rather than stubbing them in. The
+ * original defect survived CI precisely because the GUI tests encoded browser dialogs as
+ * available — one stubbed `confirm()` to true, another forced confirmation, a third
+ * asserted that `alert()` existed — so a dashboard that could not draw any of them still
+ * looked correct. Every test here installs a throwing stub for all three: reaching one is a
+ * failure, not a mock.
+ */
+/*
+ * `HTMLElement` is deliberately absent. These helpers are reached from a dozen components,
+ * and an `instanceof HTMLElement` focus check bound every one of their callers to a realm
+ * that happens to expose the constructor — which most of this package's DOM tests do not.
+ * Leaving the global out is what keeps that from coming back.
+ */
+const globals = ["document", "window", "navigator", "localStorage", "confirm", "alert", "prompt"] as const;
+let previous: Record<(typeof globals)[number], unknown>;
+let win: Window;
+let touched: string[];
+
+function forbidPlatformDialogs(): void {
+  for (const name of ["confirm", "alert", "prompt"] as const) {
+    const trap = () => { touched.push(name); throw new Error(`${name}() must not be reached`); };
+    Object.defineProperty(globalThis, name, { configurable: true, value: trap });
+    Object.defineProperty(win, name, { configurable: true, value: trap });
+  }
+}
+
+beforeEach(() => {
+  previous = Object.fromEntries(globals.map(key => [key, Reflect.get(globalThis, key)])) as typeof previous;
+  touched = [];
+  win = new Window({ url: "http://localhost/" });
+  Object.defineProperty(win.navigator, "language", { configurable: true, value: "en-US" });
+  Object.defineProperties(globalThis, {
+    document: { configurable: true, value: win.document },
+    window: { configurable: true, value: win },
+    navigator: { configurable: true, value: win.navigator },
+    localStorage: { configurable: true, value: win.localStorage },
+  });
+  forbidPlatformDialogs();
+});
+
+afterEach(() => {
+  for (const key of globals) Object.defineProperty(globalThis, key, { configurable: true, value: previous[key] });
+  expect(touched).toEqual([]);
+});
+
+/** The one dialog currently mounted, which is what every assertion below reads. */
+function openDialog(): HTMLDialogElement {
+  const dialog = win.document.querySelector("dialog");
+  if (!dialog) throw new Error("no dialog was opened");
+  return dialog as unknown as HTMLDialogElement;
+}
+
+function buttonLabelled(text: string): HTMLButtonElement {
+  const match = [...openDialog().querySelectorAll("button")]
+    .find(button => button.textContent?.trim() === text);
+  if (!match) throw new Error(`no button labelled ${text}`);
+  return match as unknown as HTMLButtonElement;
+}
+
+/** Lets the dialog's queued focus call run before the assertion reads activeElement. */
+const settled = () => new Promise<void>(resolve => { queueMicrotask(resolve); });
+
+test("a refusal resolves false and leaves nothing mounted", async () => {
+  const answer = confirmAction({ message: "Stop the proxy?" });
+  await settled();
+  buttonLabelled("Cancel").click();
+  expect(await answer).toBe(false);
+  expect(win.document.querySelector("dialog")).toBeNull();
+});
+
+test("accepting resolves true", async () => {
+  const answer = confirmAction({ message: "Stop the proxy?", confirmLabel: "Stop" });
+  await settled();
+  buttonLabelled("Stop").click();
+  expect(await answer).toBe(true);
+});
+
+test("Escape is a refusal, not an unanswered close", async () => {
+  // A native <dialog> closes on Escape without saying so. Reported as a refusal, the
+  // caller's early return still runs and no request is issued.
+  const answer = confirmAction({ message: "Remove the account?" });
+  await settled();
+  openDialog().dispatchEvent(new win.Event("cancel", { cancelable: true }) as unknown as Event);
+  expect(await answer).toBe(false);
+});
+
+test("the backdrop dismisses as a refusal", async () => {
+  const answer = confirmAction({ message: "Remove the key?" });
+  await settled();
+  (openDialog().querySelector(".modal-backdrop-dismiss") as unknown as HTMLButtonElement).click();
+  expect(await answer).toBe(false);
+});
+
+test("focus returns to the control that opened the dialog", async () => {
+  const trigger = win.document.createElement("button");
+  win.document.body.appendChild(trigger);
+  trigger.focus();
+
+  const answer = confirmAction({ message: "Revoke the device?" });
+  await settled();
+  expect(win.document.activeElement).not.toBe(trigger);
+  buttonLabelled("Cancel").click();
+  await answer;
+  expect(win.document.activeElement).toBe(trigger);
+});
+
+test("a destructive action does not put the accepting button under Enter", async () => {
+  const danger = confirmAction({ message: "Delete it?", confirmLabel: "Delete", tone: "danger" });
+  await settled();
+  expect(win.document.activeElement?.textContent).toBe("Cancel");
+  buttonLabelled("Cancel").click();
+  await danger;
+
+  const ordinary = confirmAction({ message: "Switch account mode?" });
+  await settled();
+  expect(win.document.activeElement?.textContent).toBe("OK");
+  buttonLabelled("Cancel").click();
+  await ordinary;
+});
+
+test("the message names the dialog and keeps its paragraphs", async () => {
+  const answer = confirmAction({ message: "Draining takes 20s.\n\nNo supervisor is running." });
+  await settled();
+  const dialog = openDialog();
+  const named = dialog.getAttribute("aria-labelledby");
+  const body = dialog.querySelector(`#${named}`);
+  expect(body).not.toBeNull();
+  expect([...body!.querySelectorAll("p")].map(p => p.textContent)).toEqual([
+    "Draining takes 20s.",
+    "No supervisor is running.",
+  ]);
+  buttonLabelled("Cancel").click();
+  await answer;
+});
+
+test("text entry resolves the value and cancels to null", async () => {
+  const entry = requestTextValue({ message: "Display name", initialValue: "old" });
+  await settled();
+  const input = openDialog().querySelector("input") as unknown as HTMLInputElement;
+  expect(input.value).toBe("old");
+  input.value = "new name";
+  (openDialog().querySelector("form") as unknown as HTMLFormElement)
+    .dispatchEvent(new win.Event("submit", { cancelable: true, bubbles: true }) as unknown as Event);
+  expect(await entry).toBe("new name");
+
+  const cancelled = requestTextValue({ message: "Display name", initialValue: "old" });
+  await settled();
+  buttonLabelled("Cancel").click();
+  // Null, not "": a dismissal must not be read as a request to clear the alias.
+  expect(await cancelled).toBeNull();
+});
+
+test("a rejected value keeps the dialog open and reports beside the field", async () => {
+  const entry = requestTextValue({
+    message: "Display name",
+    maxLength: 80,
+    validate: value => (value.trim().length > 80 ? "too long" : null),
+  });
+  await settled();
+  const dialog = openDialog();
+  const input = dialog.querySelector("input") as unknown as HTMLInputElement;
+  const form = dialog.querySelector("form") as unknown as HTMLFormElement;
+  expect(input.getAttribute("maxlength")).toBe("80");
+
+  input.value = "x".repeat(81);
+  form.dispatchEvent(new win.Event("submit", { cancelable: true, bubbles: true }) as unknown as Event);
+  // Still mounted, still unresolved: a rejected value is not an answer.
+  expect(win.document.querySelector("dialog")).not.toBeNull();
+  const error = dialog.querySelector("[role=alert]");
+  expect(error?.textContent).toBe("too long");
+  expect((error as unknown as HTMLElement).hidden).toBe(false);
+  expect(input.getAttribute("aria-invalid")).toBe("true");
+
+  // Editing clears the report and re-arms the button, so its state always describes the
+  // value currently in the field.
+  input.value = "short";
+  input.dispatchEvent(new win.Event("input", { bubbles: true }) as unknown as Event);
+  expect((dialog.querySelector("[role=alert]") as unknown as HTMLElement).hidden).toBe(true);
+  expect(input.getAttribute("aria-invalid")).toBeNull();
+
+  form.dispatchEvent(new win.Event("submit", { cancelable: true, bubbles: true }) as unknown as Event);
+  expect(await entry).toBe("short");
+});
+
+test("two dialogs opened in one document do not share element ids", async () => {
+  const first = confirmAction({ message: "First" });
+  await settled();
+  const firstId = openDialog().getAttribute("aria-labelledby");
+  buttonLabelled("Cancel").click();
+  await first;
+
+  const second = confirmAction({ message: "Second" });
+  await settled();
+  expect(openDialog().getAttribute("aria-labelledby")).not.toBe(firstId);
+  buttonLabelled("Cancel").click();
+  await second;
+});
+
+test("navigating away is a refusal, and leaves no dialog behind", async () => {
+  /*
+   * The dialog is mounted on <body>, so it outlives the React subtree that opened it.
+   * Without this, Back/Forward while a consent dialog is open would leave it on screen and
+   * accepting it afterwards would resume a closed-over handler against a page the user had
+   * already left — removing an account from a surface they cannot see.
+   */
+  const answer = confirmAction({ message: "Remove the account?", tone: "danger" });
+  await settled();
+  expect(win.document.querySelector("dialog")).not.toBeNull();
+
+  win.dispatchEvent(new win.Event("popstate") as unknown as Event);
+  expect(await answer).toBe(false);
+  expect(win.document.querySelector("dialog")).toBeNull();
+});
+
+test("a hash change is the same refusal", async () => {
+  const answer = confirmAction({ message: "Revoke the device?", tone: "danger" });
+  await settled();
+  win.dispatchEvent(new win.Event("hashchange") as unknown as Event);
+  expect(await answer).toBe(false);
+});
+
+test("Escape is answered at the document when the dialog is not modal", async () => {
+  /*
+   * Forces the branch that merely sets `open`, because this DOM does implement
+   * `showModal` and would otherwise never reach it. That branch is not modal: a listener on
+   * the dialog element would miss Escape as soon as focus sat anywhere else, so the
+   * listener lives on the document for exactly this case.
+   */
+  const dialogPrototype = win.HTMLDialogElement.prototype as unknown as { showModal?: unknown };
+  const nativeShowModal = dialogPrototype.showModal;
+  delete dialogPrototype.showModal;
+  try {
+    const answer = requestTextValue({ message: "Display name" });
+    await settled();
+    win.document.dispatchEvent(
+      new win.KeyboardEvent("keydown", { key: "Escape", bubbles: true }) as unknown as Event,
+    );
+    expect(await answer).toBeNull();
+    expect(win.document.querySelector("dialog")).toBeNull();
+  } finally {
+    if (nativeShowModal !== undefined) dialogPrototype.showModal = nativeShowModal;
+  }
+});
+
+test("a settled dialog stops listening for navigation", async () => {
+  // The window listeners must come off in finish(), or every dialog ever opened would keep
+  // a closure alive and a later navigation would re-enter it.
+  const answer = confirmAction({ message: "Stop the proxy?" });
+  await settled();
+  buttonLabelled("Cancel").click();
+  expect(await answer).toBe(false);
+  // A navigation after settlement must be inert: no dialog, no second resolution, no throw.
+  win.dispatchEvent(new win.Event("popstate") as unknown as Event);
+  win.document.dispatchEvent(
+    new win.KeyboardEvent("keydown", { key: "Escape", bubbles: true }) as unknown as Event,
+  );
+  expect(win.document.querySelector("dialog")).toBeNull();
+});
+
+test("a withdrawn consent resolves as a refusal", async () => {
+  /*
+   * A consent names a subject. Once the dialog is asynchronous the subject can change or go
+   * away while the question is still on screen, and answering it then would apply the user's
+   * approval to something they were never shown. Withdrawing resolves it as a refusal.
+   */
+  const withdrawal = new AbortController();
+  const answer = confirmAction({ message: "Restart Codex?", signal: withdrawal.signal });
+  await settled();
+  expect(win.document.querySelector("dialog")).not.toBeNull();
+
+  withdrawal.abort();
+  expect(await answer).toBe(false);
+  expect(win.document.querySelector("dialog")).toBeNull();
+});
+
+test("a consent withdrawn before it opens is never drawn", async () => {
+  const withdrawal = new AbortController();
+  withdrawal.abort();
+  const answer = confirmAction({ message: "Restart Codex?", signal: withdrawal.signal });
+  expect(await answer).toBe(false);
+  expect(win.document.querySelector("dialog")).toBeNull();
+
+  const entry = requestTextValue({ message: "Display name", signal: withdrawal.signal });
+  expect(await entry).toBeNull();
+  expect(win.document.querySelector("dialog")).toBeNull();
+});
diff --git a/gui/tests/app-stop.test.ts b/gui/tests/app-stop.test.ts
index c0711fa0fed..633f89155a5 100644
--- a/gui/tests/app-stop.test.ts
+++ b/gui/tests/app-stop.test.ts
@@ -15,8 +15,8 @@ describe("App proxy stop", () => {
       seen.push({ url: String(input), method: String(init?.method), body: init?.body });
       return response({ success: true }, init?.body ? 202 : 200);
     }) as typeof fetch;
-    expect((await requestProxyStop("http://machine", { fetchFn })).accepted).toBe(true);
-    expect((await requestProxyStop("http://machine", { fetchFn, mode: "client" })).accepted).toBe(true);
+    expect((await requestProxyStop("http://machine", { fetchFn })).status).toBe("accepted");
+    expect((await requestProxyStop("http://machine", { fetchFn, mode: "client" })).status).toBe("accepted");
     expect(seen).toEqual([
       { url: "http://machine/api/stop", method: "POST", body: undefined },
       { url: "http://machine/api/machine/disconnect", method: "POST", body: "{}" },
@@ -32,7 +32,7 @@ describe("App proxy stop", () => {
       formatFailure: status => `Failed to stop proxy (HTTP ${status}).`,
     });
 
-    expect(outcome).toEqual({ accepted: false, message: "native Codex restore failed" });
+    expect(outcome).toEqual({ status: "rejected", message: "native Codex restore failed" });
   });
 
   test("rejects an HTTP 200 cleanup failure and exposes its server message", async () => {
@@ -44,18 +44,77 @@ describe("App proxy stop", () => {
       formatFailure: status => `Failed to stop proxy (HTTP ${status}).`,
     });
 
-    expect(outcome).toEqual({ accepted: false, message: "native Codex cleanup failed" });
+    expect(outcome).toEqual({ status: "rejected", message: "native Codex cleanup failed" });
   });
 
-  test("treats a stop timeout like a dropped connection", async () => {
-    const outcome = await requestProxyStop("", {
-      fetchFn: (async () => {
-        throw new DOMException("The operation timed out.", "AbortError");
+  /*
+   * A lost connection is not an answer. It used to be reported as acceptance, which turned
+   * "the user pressed the button" into "the server acted": a stop that never arrived read
+   * exactly like one that succeeded. The fate of the request is settled by READING the
+   * instance again, never by sending the mutation a second time.
+   */
+  test("a dropped stop is accepted only once the proxy has actually gone", async () => {
+    const seen: string[] = [];
+    const outcome = await requestProxyStop("http://machine", {
+      fetchFn: (async (input: RequestInfo | URL) => {
+        const url = String(input);
+        seen.push(url);
+        // The proxy dies mid-response, then nothing answers the follow-up read.
+        throw new TypeError("network error");
+      }) as typeof fetch,
+    });
+
+    expect(outcome).toEqual({ status: "accepted" });
+    expect(seen).toEqual(["http://machine/api/stop", "http://machine/healthz"]);
+  });
+
+  test("a proxy that still answers after a dropped stop is unknown, not accepted", async () => {
+    const outcome = await requestProxyStop("http://machine", {
+      fetchFn: (async (input: RequestInfo | URL) => {
+        if (String(input).endsWith("/healthz")) return response({ status: "ok" });
+        throw new DOMException("The operation timed out.", "TimeoutError");
+      }) as typeof fetch,
+      formatStillRunning: () => "still answering",
+    });
+
+    expect(outcome).toEqual({ status: "unknown", message: "still answering" });
+  });
+
+  test("an unsettled follow-up read stays unknown", async () => {
+    const outcome = await requestProxyStop("http://machine", {
+      fetchFn: (async (input: RequestInfo | URL) => {
+        if (String(input).endsWith("/healthz")) return response({}, 503);
+        throw new DOMException("aborted", "AbortError");
       }) as typeof fetch,
-      timeoutMs: 1,
+      formatUnknown: () => "not confirmed",
+    });
+
+    expect(outcome).toEqual({ status: "unknown", message: "not confirmed" });
+  });
+
+  test("a dropped disconnect is unknown, because disconnecting ends no process", async () => {
+    const seen: string[] = [];
+    const outcome = await requestProxyStop("http://machine", {
+      fetchFn: (async (input: RequestInfo | URL) => {
+        seen.push(String(input));
+        throw new TypeError("network error");
+      }) as typeof fetch,
+      mode: "client",
+      formatUnknown: () => "not confirmed",
+    });
+
+    // No liveness read: the proxy answering proves nothing about a client disconnect.
+    expect(outcome).toEqual({ status: "unknown", message: "not confirmed" });
+    expect(seen).toEqual(["http://machine/api/machine/disconnect"]);
+  });
+
+  test("a 2xx whose body cannot be read is unknown, because success: false rides in it", async () => {
+    const outcome = await requestProxyStop("", {
+      fetchFn: (async () => new Response("not json", { status: 200 })) as typeof fetch,
+      formatUnknown: () => "not confirmed",
     });
 
-    expect(outcome).toEqual({ accepted: true });
+    expect(outcome).toEqual({ status: "unknown", message: "not confirmed" });
   });
 
   test("uses the localized fallback when the server omits a message", async () => {
@@ -64,10 +123,10 @@ describe("App proxy stop", () => {
       formatFailure: status => `HTTP ${status} stop failed`,
     });
 
-    expect(outcome).toEqual({ accepted: false, message: "HTTP 503 stop failed" });
+    expect(outcome).toEqual({ status: "rejected", message: "HTTP 503 stop failed" });
   });
 
-  test("App clears stopping state and alerts for every rejected stop outcome", async () => {
+  test("App gates the stop on an in-page dialog and reports every rejected outcome", async () => {
     const app = await Bun.file(new URL("../src/App.tsx", import.meta.url)).text();
     const handleStopIdx = app.indexOf("const handleStop");
     const brandIdx = app.indexOf("const brand");
@@ -75,10 +134,18 @@ describe("App proxy stop", () => {
     expect(brandIdx).toBeGreaterThan(handleStopIdx);
     const handler = app.slice(handleStopIdx, brandIdx);
 
+    // The consent gate is awaited, and a refusal returns before the request. It used to
+    // be `confirm()`, which the app's webview answers false without drawing, so this
+    // control did nothing there at all.
+    expect(handler).toContain("await confirmAction(");
+    expect(handler).toContain("if (!consented) return;");
     expect(handler).toContain("await requestProxyStop(machineBase");
     expect(handler).toContain('mode: targets.connected ? "client" : "standalone"');
-    expect(handler).toContain("if (!outcome.accepted)");
+    expect(handler).toContain('if (outcome.status !== "accepted")');
     expect(handler).toContain("setStopping(false)");
-    expect(handler).toContain("alert(outcome.message)");
+    // Reported in the page, not through a platform dialog that draws nothing — and a
+    // refusal and an unknown are not reported in the same tone.
+    expect(handler).toContain('outcome.status === "rejected" ? "err" : "warn"');
+    expect(handler).not.toContain("alert(");
   });
 });
diff --git a/gui/tests/claude-desktop-mode-picker.test.tsx b/gui/tests/claude-desktop-mode-picker.test.tsx
new file mode 100644
index 00000000000..68215092244
--- /dev/null
+++ b/gui/tests/claude-desktop-mode-picker.test.tsx
@@ -0,0 +1,261 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import ClaudeDesktop from "../src/pages/ClaudeDesktop";
+import { LanguageProvider } from "../src/i18n/provider";
+import { clearClientResourceStoresForTests } from "../src/client-resource";
+
+/**
+ * The connection-mode picker decides which of two mutually exclusive Desktop
+ * configurations the apply request asks for. Mounted tests because the
+ * failures that matter are wiring: the radio must follow /status, a changed
+ * selection must reach the POST body, and the gateway-only "not active
+ * profile" check must not leak into first-party status.
+ */
+
+const globals = ["document", "window", "navigator", "localStorage", "fetch", "IS_REACT_ACT_ENVIRONMENT"] as const;
+let previousGlobals: Record<(typeof globals)[number], unknown>;
+let testWindow: Window;
+let container: HTMLElement;
+let root: Root | null = null;
+let requests: { url: string; init?: RequestInit }[] = [];
+
+const MODEL = {
+  route: "prov/opus-0",
+  label: "Opus Model",
+  available: true,
+  contextWindow: 200_000,
+  effortSupported: true,
+  assignment: { family: "opus", alias: "alias-opus" },
+};
+
+function profilePayload() {
+  return {
+    profile: {
+      version: 1,
+      assignments: { [MODEL.route]: MODEL.assignment },
+      defaults: { opus: MODEL.route, fable: null, sonnet: null, haiku: null },
+    },
+    models: [MODEL],
+    rendered: [],
+    port: 10100,
+  };
+}
+
+function statusPayload(overrides: Record<string, unknown> = {}) {
+  return {
+    desiredEnabled: true,
+    applied: true,
+    appliedAt: null,
+    stale: false,
+    health: { lastRequestAt: null, requestCount: 0, errorCount: 0 },
+    mode: "first-party",
+    firstParty: {
+      applied: true,
+      stale: false,
+      interceptEnabled: true,
+      interceptRunning: true,
+      proxyPort: 10200,
+      caCertPath: "/tmp/ocx/claude-intercept/ca.pem",
+    },
+    ...overrides,
+  };
+}
+
+function installFetch(status: Record<string, unknown>) {
+  Object.defineProperty(globalThis, "fetch", {
+    configurable: true,
+    value: async (url: string, init?: RequestInit) => {
+      requests.push({ url: String(url), init });
+      const path = String(url);
+      const body = path.includes("/status")
+        ? status
+        : path.endsWith("/apply")
+          ? { ok: true, mode: JSON.parse(String(init?.body ?? "{}")).mode }
+          : init?.method === "PUT"
+            ? { ok: true }
+            : profilePayload();
+      return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) } as unknown as Response;
+    },
+  });
+}
+
+beforeEach(() => {
+  clearClientResourceStoresForTests();
+  requests = [];
+  previousGlobals = Object.fromEntries(globals.map(k => [k, Reflect.get(globalThis, k)])) as typeof previousGlobals;
+  testWindow = new Window({ url: "http://localhost/" });
+  Object.defineProperty(testWindow.navigator, "language", { configurable: true, value: "en-US" });
+  Object.defineProperties(globalThis, {
+    document: { configurable: true, value: testWindow.document },
+    window: { configurable: true, value: testWindow },
+    navigator: { configurable: true, value: testWindow.navigator },
+    localStorage: { configurable: true, value: testWindow.localStorage },
+  });
+  (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+  installFetch(statusPayload());
+  container = testWindow.document.createElement("div") as unknown as HTMLElement;
+  testWindow.document.body.appendChild(container as never);
+});
+
+afterEach(async () => {
+  if (root) {
+    const current = root;
+    await act(async () => { current.unmount(); });
+    root = null;
+  }
+  clearClientResourceStoresForTests();
+  for (const key of globals) {
+    Object.defineProperty(globalThis, key, { configurable: true, value: previousGlobals[key] });
+  }
+});
+
+async function mount() {
+  await act(async () => {
+    root = createRoot(container);
+    root.render(<LanguageProvider><ClaudeDesktop apiBase="" /></LanguageProvider>);
+  });
+  await act(async () => { await new Promise(r => setTimeout(r, 50)); });
+}
+
+function radio(mode: "first-party" | "gateway"): HTMLInputElement {
+  const found = container.querySelector(`input[name="claude-desktop-mode"][value="${mode}"]`);
+  if (!found) throw new Error(`mode radio not found: ${mode}`);
+  return found as unknown as HTMLInputElement;
+}
+
+function applyButton(): HTMLButtonElement {
+  const found = Array.from(container.querySelectorAll("button.btn-primary"))
+    .find(button => /apply/i.test(button.textContent ?? ""));
+  if (!found) throw new Error("apply button not found");
+  return found as unknown as HTMLButtonElement;
+}
+
+async function click(element: HTMLElement) {
+  await act(async () => { element.click(); });
+}
+
+test("a failed /status unlocks the picker on the default without claiming a current mode", async () => {
+  Object.defineProperty(globalThis, "fetch", {
+    configurable: true,
+    value: async (url: string) => {
+      const path = String(url);
+      if (path.includes("/status")) {
+        return { ok: false, status: 503, json: async () => ({ error: "down" }), text: async () => "down" } as unknown as Response;
+      }
+      const body = profilePayload();
+      return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) } as unknown as Response;
+    },
+  });
+
+  await mount();
+  await act(async () => { await new Promise(r => setTimeout(r, 200)); });
+
+  expect((container.querySelector(".claude-mode-picker") as HTMLFieldSetElement).disabled).toBe(false);
+  expect(radio("first-party").checked).toBe(true);
+  expect(radio("gateway").checked).toBe(false);
+  expect(container.querySelector(".claude-mode-current")).toBeNull();
+  expect(container.querySelector(".claude-status-bar")?.textContent ?? "").toContain("Failed to load");
+});
+
+test("the picker follows the effective mode reported by /status and shows the proxy port", async () => {
+  await mount();
+  expect(radio("first-party").checked).toBe(true);
+  expect(radio("gateway").checked).toBe(false);
+  const firstPartyOption = radio("first-party").closest("label")!;
+  expect(firstPartyOption.querySelector(".claude-mode-default")).not.toBeNull();
+  expect(firstPartyOption.querySelector(".claude-mode-current")).not.toBeNull();
+  expect(container.querySelector(".claude-mode-switch-note")).toBeNull();
+
+  const bar = container.querySelector(".claude-status-bar")!;
+  expect(bar.className).toContain("applied");
+  expect(bar.textContent ?? "").toContain("First-party: Code tab routed through the local proxy");
+  expect(bar.textContent ?? "").toContain("127.0.0.1:10200");
+  expect(applyButton().textContent).toBe("Save & apply");
+});
+
+test("a stopped intercept proxy is surfaced in first-party mode", async () => {
+  installFetch(statusPayload({
+    firstParty: { applied: true, stale: false, interceptEnabled: true, interceptRunning: false, proxyPort: 10200, caCertPath: "/tmp/ca.pem" },
+  }));
+  await mount();
+  expect(container.querySelector(".claude-status-bar")?.textContent ?? "").toContain("is not running");
+});
+
+test("selecting the other mode flips the apply label and sends that mode in the POST body", async () => {
+  await mount();
+  await act(async () => {
+    radio("gateway").click();
+  });
+  expect(radio("gateway").checked).toBe(true);
+  expect(container.querySelector(".claude-mode-switch-note")).not.toBeNull();
+  expect(applyButton().textContent).toBe("Switch mode & apply");
+
+  await click(applyButton());
+  await act(async () => { await new Promise(r => setTimeout(r, 20)); });
+
+  const apply = requests.find(r => r.url.endsWith("/api/claude-desktop/apply"));
+  expect(apply).toBeDefined();
+  expect(apply!.init?.method).toBe("POST");
+  expect(JSON.parse(String(apply!.init?.body))).toEqual({ mode: "gateway" });
+});
+
+test("the default apply keeps the effective mode when nothing was chosen", async () => {
+  installFetch(statusPayload({ mode: "gateway", activeProfile: true, firstParty: undefined }));
+  await mount();
+  expect(radio("gateway").checked).toBe(true);
+  await click(applyButton());
+  await act(async () => { await new Promise(r => setTimeout(r, 20)); });
+  const apply = requests.find(r => r.url.endsWith("/api/claude-desktop/apply"));
+  expect(JSON.parse(String(apply!.init?.body))).toEqual({ mode: "gateway" });
+});
+
+test("activeProfile=false only demotes the status bar in gateway mode", async () => {
+  // First-party never writes a Desktop profile, so Desktop serving some other
+  // profile is irrelevant and must not paint the bar as not-applied.
+  installFetch(statusPayload({ activeProfile: false }));
+  await mount();
+  expect(container.querySelector(".claude-status-bar")!.className).toContain("applied");
+  expect(container.querySelector(".claude-status-bar")!.className).not.toContain("not-applied");
+
+  await act(async () => { root!.unmount(); root = null; });
+  clearClientResourceStoresForTests();
+  installFetch(statusPayload({ mode: "gateway", activeProfile: false, firstParty: undefined }));
+  await mount();
+  expect(container.querySelector(".claude-status-bar")!.className).toContain("not-applied");
+});
+
+test("no radio is checked and the picker is disabled until /status answers", async () => {
+  // A gateway install must never see the first-party default flash while /status is in flight.
+  let releaseStatus: () => void = () => {};
+  const gate = new Promise<void>(resolve => { releaseStatus = resolve; });
+  const gatewayStatus = statusPayload({ mode: "gateway", activeProfile: true, firstParty: undefined });
+  Object.defineProperty(globalThis, "fetch", {
+    configurable: true,
+    value: async (url: string, init?: RequestInit) => {
+      const path = String(url);
+      if (path.includes("/status")) await gate;
+      const body = path.includes("/status") ? gatewayStatus : profilePayload();
+      return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) } as unknown as Response;
+    },
+  });
+  await mount();
+  expect(radio("first-party").checked).toBe(false);
+  expect(radio("gateway").checked).toBe(false);
+  expect((container.querySelector(".claude-mode-picker") as HTMLFieldSetElement).disabled).toBe(true);
+  expect(container.querySelector(".claude-mode-current")).toBeNull();
+  expect(container.querySelector(".claude-mode-switch-note")).toBeNull();
+
+  releaseStatus();
+  await act(async () => { await new Promise(r => setTimeout(r, 50)); });
+  expect(radio("gateway").checked).toBe(true);
+  expect(radio("first-party").checked).toBe(false);
+  expect((container.querySelector(".claude-mode-picker") as HTMLFieldSetElement).disabled).toBe(false);
+});
+
+test("an unknown mode in /status is rejected as malformed", async () => {
+  installFetch(statusPayload({ mode: "proxy" }));
+  await mount();
+  expect(container.textContent ?? "").toContain("Failed to load Claude Desktop profile.");
+});
diff --git a/gui/tests/codex-account-pool-controller.test.ts b/gui/tests/codex-account-pool-controller.test.ts
index 044b8156a01..3f1d5c848d4 100644
--- a/gui/tests/codex-account-pool-controller.test.ts
+++ b/gui/tests/codex-account-pool-controller.test.ts
@@ -21,6 +21,10 @@ test("the controller is the single data owner and exposes the agreed contract",
     // WP2 (260730_gui_hydration_loading_unify/010): progress is part of the contract, because a
     // forced quota refresh keeps `loadState` at "ready" and would otherwise be invisible.
     "refreshing", "initialLoading",
+    // #5261: for the same reason in the other direction. A warm refresh failure keeps the rows
+    // and keeps `loadState` at "ready", so without this the surface has no way to say that what
+    // it is showing predates a failed read.
+    "refreshFailed",
   ]) {
     expect(hook).toContain(member);
   }
diff --git a/gui/tests/codex-account-pool-stale-refresh.test.tsx b/gui/tests/codex-account-pool-stale-refresh.test.tsx
new file mode 100644
index 00000000000..0f164c71a72
--- /dev/null
+++ b/gui/tests/codex-account-pool-stale-refresh.test.tsx
@@ -0,0 +1,270 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import { act } from "react";
+import type { Root } from "react-dom/client";
+import CodexAccountPool from "../src/components/CodexAccountPool";
+import { clearClientResourceStoresForTests } from "../src/client-resource";
+import { useCodexAccountPool, type CodexAccountEntry, type CodexAccountPoolController } from "../src/hooks/useCodexAccountPool";
+import { en } from "../src/i18n/en";
+import { LanguageProvider } from "../src/i18n/provider";
+
+/**
+ * #5261: a failed account refresh used to leave the roster looking current.
+ *
+ * Keeping the rows is deliberate — blanking a populated pool on a soft poll miss is its own
+ * defect — but the controller also went on reporting `ready`, so nothing distinguished a list
+ * the server had just confirmed from one that predated a failure. The case that surfaced it:
+ * add an account, the read that would bring it over fails, and the dashboard shows the older
+ * accounts with the new one simply absent.
+ *
+ * Both halves are held here because either alone is satisfiable without the other: a flag the
+ * surface never reads changes nothing a user sees, and a banner with no flag behind it never
+ * appears.
+ */
+
+const globals = ["document", "window", "navigator", "localStorage", "IS_REACT_ACT_ENVIRONMENT"] as const;
+let previous: Record<(typeof globals)[number], unknown>;
+let win: Window;
+let host: HTMLElement;
+let root: Root | null = null;
+let originalFetch: typeof globalThis.fetch;
+let accountsOk = true;
+let serverAccounts: unknown[] = [];
+let baseCounter = 0;
+let activeResponseGate: Promise<void> | null = null;
+
+function row(id: string, email: string, isMain = false) {
+  return { id, email, isMain, paused: false, priority: 0, hasCredential: true, quota: null };
+}
+
+const mainAccount: CodexAccountEntry = {
+  id: "main",
+  email: "main@example.test",
+  isMain: true,
+  paused: false,
+  priority: 0,
+  hasCredential: true,
+  quota: null,
+  quotaAutoRefresh: {
+    fiveHourAvailable: false,
+    weeklyAvailable: false,
+    fiveHourEnabled: false,
+    weeklyEnabled: false,
+  },
+};
+
+function makeController(overrides: Partial<CodexAccountPoolController> = {}): CodexAccountPoolController {
+  return {
+    accounts: [mainAccount],
+    activeId: null,
+    loadState: "ready",
+    refreshing: false,
+    refreshFailed: false,
+    initialLoading: false,
+    switchingId: null,
+    pauseUpdatingId: null,
+    priorityUpdatingId: null,
+    pausingExhausted: false,
+    activeNeedsReauth: false,
+    activePinnedId: null,
+    load: async () => true,
+    switchAccount: async () => ({ ok: true, activeId: null }),
+    setAccountPaused: async () => ({ ok: true }),
+    setAccountPriority: async () => ({ ok: true }),
+    pauseExhaustedAccounts: async () => ({ ok: true, pausedCount: 0 }),
+    saveAlias: async () => ({ ok: true }),
+    removeAccount: async () => ({ ok: true }),
+    syncAfterAccountAdded: async () => ({ ok: true }),
+    pauseRefresh: () => ({ __brand: "codex-pool-pause" }) as never,
+    resumeRefresh: () => {},
+    subscribeLoadObserver: () => () => {},
+    readLastThreshold: () => undefined,
+    readLastActive: () => undefined,
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  previous = Object.fromEntries(globals.map((k) => [k, Reflect.get(globalThis, k)])) as typeof previous;
+  win = new Window({ url: "http://localhost/" });
+  Object.defineProperty(win.navigator, "language", { configurable: true, value: "en-US" });
+  Object.defineProperties(globalThis, {
+    document: { configurable: true, value: win.document },
+    window: { configurable: true, value: win },
+    navigator: { configurable: true, value: win.navigator },
+    localStorage: { configurable: true, value: win.localStorage },
+  });
+  (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+  originalFetch = globalThis.fetch;
+  accountsOk = true;
+  activeResponseGate = null;
+  serverAccounts = [row("a1", "account-one", true)];
+  Object.defineProperty(globalThis, "fetch", {
+    configurable: true,
+    value: async (url: string) => {
+      const path = String(url).split("/api/")[1] ?? String(url);
+      if (path.startsWith("usage?")) {
+        return { ok: true, json: async () => ({ accounts: [] }) } as unknown as Response;
+      }
+      if (path.startsWith("codex-auth/accounts")) {
+        if (!accountsOk) return { ok: false, status: 503 } as unknown as Response;
+        return { ok: true, json: async () => ({ accounts: serverAccounts }) } as unknown as Response;
+      }
+      if (path.startsWith("codex-auth/active")) {
+        const gate = activeResponseGate;
+        activeResponseGate = null;
+        if (gate) await gate;
+        return {
+          ok: true,
+          json: async () => ({ activeCodexAccountId: null, autoSwitchThreshold: 80 }),
+        } as unknown as Response;
+      }
+      return { ok: true, json: async () => ({}) } as unknown as Response;
+    },
+  });
+
+  host = win.document.createElement("div") as unknown as HTMLElement;
+  win.document.body.appendChild(host as never);
+});
+
+afterEach(async () => {
+  if (root) {
+    const current = root;
+    await act(async () => { current.unmount(); });
+    root = null;
+  }
+  await act(async () => { await new Promise((r) => setTimeout(r, 0)); });
+  clearClientResourceStoresForTests();
+  for (const key of globals) {
+    Object.defineProperty(globalThis, key, { configurable: true, value: previous[key] });
+  }
+  Object.defineProperty(globalThis, "fetch", { configurable: true, value: originalFetch });
+  await win.happyDOM?.close?.();
+});
+
+/** A fresh apiBase each time: the controller's last-good snapshot is keyed by it. */
+async function mountController() {
+  baseCounter += 1;
+  const apiBase = `stale-${Date.now()}-${baseCounter}`;
+  const seen: { current: CodexAccountPoolController | null } = { current: null };
+  function Probe() {
+    seen.current = useCodexAccountPool(apiBase, true);
+    return null;
+  }
+  const { createRoot } = await import("react-dom/client");
+  await act(async () => {
+    root = createRoot(host);
+    root.render(<Probe />);
+  });
+  await act(async () => { await new Promise((r) => setTimeout(r, 30)); });
+  return seen;
+}
+
+async function mountPool(controller: CodexAccountPoolController) {
+  const { createRoot } = await import("react-dom/client");
+  await act(async () => {
+    root = createRoot(host);
+    root.render(
+      <LanguageProvider>
+        <CodexAccountPool apiBase="" controller={controller} />
+      </LanguageProvider>,
+    );
+  });
+  await act(async () => { await new Promise((r) => setTimeout(r, 40)); });
+}
+
+function staleBanner(): Element | null {
+  return host.querySelector(".pwi-auth-state--stale");
+}
+
+test("a failed refresh keeps the rows and stops reporting them as current", async () => {
+  const seen = await mountController();
+  expect(seen.current!.loadState).toBe("ready");
+  expect(seen.current!.refreshFailed).toBe(false);
+  expect(seen.current!.accounts.map(a => a.id)).toEqual(["a1"]);
+
+  // The server now has an account this client has never seen, and the read that would have
+  // brought it over fails. This is the reported shape of the defect, not a synthetic one.
+  serverAccounts = [row("a1", "account-one", true), row("a2", "account-two")];
+  accountsOk = false;
+  await act(async () => { await seen.current!.load(); });
+
+  expect(seen.current!.refreshFailed).toBe(true);
+  // Still ready, and still holding the rows: blanking a populated pool on a miss is its own
+  // defect, so the fix is that the surface now has something to say, not that it shows less.
+  expect(seen.current!.loadState).toBe("ready");
+  expect(seen.current!.accounts.map(a => a.id)).toEqual(["a1"]);
+
+  accountsOk = true;
+  await act(async () => { await seen.current!.load(); });
+
+  expect(seen.current!.refreshFailed).toBe(false);
+  expect(seen.current!.accounts.map(a => a.id)).toEqual(["a1", "a2"]);
+});
+
+test("the banner clears with the rows it qualifies, not with the whole load", async () => {
+  // The rows are painted the moment /accounts returns, while /active can still be running on
+  // its own much longer budget. Clearing the flag at the settle instead would leave the rows
+  // that just replaced the stale ones labelled as the stale ones for that whole window.
+  const seen = await mountController();
+
+  accountsOk = false;
+  await act(async () => { await seen.current!.load(); });
+  expect(seen.current!.refreshFailed).toBe(true);
+
+  accountsOk = true;
+  serverAccounts = [row("a1", "account-one", true), row("a2", "account-two")];
+  let releaseActive!: () => void;
+  activeResponseGate = new Promise<void>(resolve => { releaseActive = resolve; });
+
+  let pending: Promise<boolean>;
+  await act(async () => {
+    pending = seen.current!.load();
+    await new Promise((r) => setTimeout(r, 10));
+  });
+
+  // /accounts has landed; /active has not.
+  expect(seen.current!.accounts.map(a => a.id)).toEqual(["a1", "a2"]);
+  expect(seen.current!.refreshFailed).toBe(false);
+
+  await act(async () => { releaseActive(); await pending!; });
+  expect(seen.current!.refreshFailed).toBe(false);
+});
+
+test("a cold failure still replaces the surface rather than annotating an empty one", async () => {
+  // Non-regression: the cold path is unchanged, and this holds it there now that a second
+  // failure signal exists that must not take it over.
+  accountsOk = false;
+  const seen = await mountController();
+
+  expect(seen.current!.loadState).toBe("error");
+  expect(seen.current!.accounts).toEqual([]);
+});
+
+test("the roster says so on screen when the rows it shows are the pre-refresh ones", async () => {
+  await mountPool(makeController({ refreshFailed: true }));
+
+  const banner = staleBanner();
+  expect(banner).not.toBeNull();
+  expect(banner!.textContent).toContain(en["codexAuth.accountsRefreshFailed"]);
+  // Non-destructive: the accounts it is qualifying are still rendered underneath it.
+  expect(host.textContent).toContain("main@example.test");
+});
+
+test("a roster whose refresh succeeded carries no banner", async () => {
+  // Non-regression: passes before this change too, and is here so the new banner cannot start
+  // appearing over a roster the server has just confirmed.
+  await mountPool(makeController({ refreshFailed: false }));
+
+  expect(staleBanner()).toBeNull();
+});
+
+test("a cold failure shows its own error instead of the stale banner", async () => {
+  // Precedence, not regression: nothing survived to qualify, so the banner would be describing
+  // an empty list. The cold error has to win even though both conditions hold.
+  await mountPool(makeController({ accounts: [], loadState: "error", refreshFailed: true }));
+
+  expect(staleBanner()).toBeNull();
+  expect(host.textContent).toContain(en["codexAuth.loadFailed"]);
+});
diff --git a/gui/tests/codex-account-pool-toast-tone.test.tsx b/gui/tests/codex-account-pool-toast-tone.test.tsx
index 5e64bed40a3..7410d9561d7 100644
--- a/gui/tests/codex-account-pool-toast-tone.test.tsx
+++ b/gui/tests/codex-account-pool-toast-tone.test.tsx
@@ -6,18 +6,30 @@ import { formatAccountPriority } from "../src/account-priority";
 import CodexAccountPool from "../src/components/CodexAccountPool";
 import type { CodexAccountEntry, CodexAccountPoolController } from "../src/hooks/useCodexAccountPool";
 import { LanguageProvider } from "../src/i18n/provider";
+import { acceptActionDialog, actionDialogOpen } from "./helpers/action-dialog";
 
 /**
  * Stale toastError must not paint a successful redeem as notice-err (PR #475).
  */
 
-const globals = ["document", "window", "navigator", "localStorage", "IS_REACT_ACT_ENVIRONMENT"] as const;
+const globals = ["document", "window", "navigator", "localStorage", "HTMLElement",
+  "IS_REACT_ACT_ENVIRONMENT", "confirm", "alert", "prompt"] as const;
 let previous: Record<(typeof globals)[number], unknown>;
 let win: Window;
 let host: HTMLElement;
 let root: Root | null = null;
 let originalFetch: typeof globalThis.fetch;
-let originalConfirm: typeof window.confirm;
+/** Platform dialogs reached, which must stay empty: the app's webview draws none of them. */
+let touched: string[];
+
+/** Removal opens an in-page consent dialog now; answer it and let the write run. */
+async function consentToRemoval(): Promise<void> {
+  expect(actionDialogOpen(win.document as unknown as Document)).toBe(true);
+  await act(async () => {
+    acceptActionDialog(win.document as unknown as Document);
+    await new Promise(resolve => setTimeout(resolve, 20));
+  });
+}
 let legacyApiPayload: unknown = null;
 let priorityWrites: { id: string; priority: number | null }[] = [];
 
@@ -70,6 +82,7 @@ function makeController(overrides: Partial<CodexAccountPoolController> = {}): Co
     activeNeedsReauth: false,
     activePinnedId: null,
     refreshing: false,
+    refreshFailed: false,
     initialLoading: false,
     load: async () => true,
     switchAccount: async () => ({ ok: true, activeId: null }),
@@ -99,12 +112,17 @@ beforeEach(() => {
     window: { configurable: true, value: win },
     navigator: { configurable: true, value: win.navigator },
     localStorage: { configurable: true, value: win.localStorage },
+    HTMLElement: { configurable: true, value: win.HTMLElement },
   });
   (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
   originalFetch = globalThis.fetch;
-  originalConfirm = window.confirm;
-  window.confirm = () => true;
+  touched = [];
+  for (const name of ["confirm", "alert", "prompt"] as const) {
+    const trap = () => { touched.push(name); throw new Error(`${name}() must not be reached`); };
+    Object.defineProperty(globalThis, name, { configurable: true, value: trap });
+    Object.defineProperty(win, name, { configurable: true, value: trap });
+  }
 
   Object.defineProperty(globalThis, "fetch", {
     configurable: true,
@@ -145,7 +163,6 @@ afterEach(async () => {
     await act(async () => { current.unmount(); });
     root = null;
   }
-  window.confirm = originalConfirm;
   await act(async () => { await new Promise((r) => setTimeout(r, 0)); });
   for (const key of globals) {
     Object.defineProperty(globalThis, key, { configurable: true, value: previous[key] });
@@ -437,6 +454,7 @@ test("a saved removal with pending catalog refresh renders a warning tone", asyn
     removeButton!.dispatchEvent(new win.MouseEvent("click", { bubbles: true }));
     await new Promise(resolve => setTimeout(resolve, 20));
   });
+  await consentToRemoval();
 
   const warning = host.querySelector(".codex-auth-page-head__feedback.is-warn");
   expect(warning?.textContent).toContain("ocx sync");
@@ -486,7 +504,7 @@ test("successful redeem clears a stale error toast tone", async () => {
   );
   expect(removeBtn).toBeTruthy();
   await act(async () => { removeBtn!.dispatchEvent(new win.MouseEvent("click", { bubbles: true })); });
-  await act(async () => { await new Promise((r) => setTimeout(r, 20)); });
+  await consentToRemoval();
 
   const errNotice = host.querySelector(".codex-auth-page-head__feedback.is-err");
   expect(errNotice).toBeTruthy();
@@ -558,7 +576,7 @@ test("a pool card folds alias/id/remove behind a ⋯ disclosure and shows the or
   const remove = card.querySelector<HTMLButtonElement>('button[aria-label^="Remove"]')!;
   expect(remove).not.toBeNull();
   await act(async () => { remove.click(); });
-  await act(async () => { await new Promise((r) => setTimeout(r, 0)); });
+  await consentToRemoval();
   expect(removed).toEqual(["pool-1"]);
 });
 
diff --git a/gui/tests/codex-restart.test.ts b/gui/tests/codex-restart.test.ts
index b1d4e9cf28b..0b2a1d33de8 100644
--- a/gui/tests/codex-restart.test.ts
+++ b/gui/tests/codex-restart.test.ts
@@ -48,8 +48,9 @@ describe("requestCodexRestart", () => {
   });
 
   test("a network failure is reported as unreachable", async () => {
-    // requestProxyStop reads a dropped socket as "the stop started". This route
-    // does not kill the process serving it, so silence means something broke.
+    // requestProxyStop resolves a dropped socket by re-reading the instance, because the
+    // process it talks to is the one going away. This route does not kill the process
+    // serving it, so there is nothing to re-read and silence means something broke.
     const outcome = await requestCodexRestart("", {
       fetchFn: (async () => {
         throw new TypeError("Failed to fetch");
@@ -219,4 +220,3 @@ describe("requestCodexRestart", () => {
     expect(outcome).toEqual({ ok: false, message: "malformed" });
   });
 });
-
diff --git a/gui/tests/codex-stale-banner-dom.test.tsx b/gui/tests/codex-stale-banner-dom.test.tsx
index 5b59c3c489a..ef8ffffd1aa 100644
--- a/gui/tests/codex-stale-banner-dom.test.tsx
+++ b/gui/tests/codex-stale-banner-dom.test.tsx
@@ -7,6 +7,8 @@ import { LanguageProvider } from "../src/i18n/provider";
 import { CodexStaleBanner } from "../src/components/codex-stale-banner";
 import { useCodexRestart } from "../src/use-codex-restart";
 import type { CodexRestartResponse } from "../src/codex-restart";
+import type { NoticeTone } from "../src/ui";
+import { acceptActionDialog, actionDialogOpen, dismissActionDialog } from "./helpers/action-dialog";
 
 /**
  * Real DOM behavior for the staleness surface.
@@ -15,16 +17,39 @@ import type { CodexRestartResponse } from "../src/codex-restart";
  * while a restart from the page-head button left the banner on screen — the
  * refresh only ran from the banner's own click handler. Source-text assertions
  * cannot see that, so these render the components and drive them.
+ *
+ * It also stubbed `confirm()` to true and `alert()` to a no-op, which is how the
+ * desktop defect stayed invisible: inside the app neither draws, so both controls
+ * were dead there while this file was green. Every platform dialog is now a trap —
+ * reaching one fails the test — and consent is answered through the real in-page
+ * dialog instead.
  */
 
-const globals = ["document", "window", "navigator", "localStorage", "IS_REACT_ACT_ENVIRONMENT"] as const;
+const globals = ["document", "window", "navigator", "localStorage", "HTMLElement", "IS_REACT_ACT_ENVIRONMENT",
+  "confirm", "alert", "prompt"] as const;
 let previous: Record<(typeof globals)[number], unknown>;
 let win: Window;
 let host: HTMLElement;
 let root: Root | null = null;
 let originalFetch: typeof globalThis.fetch;
-let originalConfirm: typeof globalThis.confirm;
-let originalAlert: typeof globalThis.alert;
+/** Outcome messages the controller published, in order. */
+let reports: Array<{ message: string; tone: NoticeTone }>;
+/** Platform dialogs reached, which must stay empty. */
+let touched: string[];
+
+/** The document the components render into, which is where the dialog is mounted. */
+const dialogDocument = () => win.document as unknown as Document;
+
+/** Opens the consent dialog by clicking, then answers it. */
+async function clickAndAnswer(button: HTMLButtonElement, answer: "accept" | "dismiss"): Promise<void> {
+  await act(async () => { button.click(); });
+  expect(actionDialogOpen(dialogDocument())).toBe(true);
+  await act(async () => {
+    if (answer === "accept") acceptActionDialog(dialogDocument());
+    else dismissActionDialog(dialogDocument());
+    await Promise.resolve();
+  });
+}
 
 function restartBody(overrides: Partial<CodexRestartResponse> = {}): CodexRestartResponse {
   return {
@@ -43,8 +68,8 @@ function restartBody(overrides: Partial<CodexRestartResponse> = {}): CodexRestar
 beforeEach(() => {
   previous = Object.fromEntries(globals.map(k => [k, Reflect.get(globalThis, k)])) as typeof previous;
   originalFetch = globalThis.fetch;
-  originalConfirm = globalThis.confirm;
-  originalAlert = globalThis.alert;
+  reports = [];
+  touched = [];
   win = new Window({ url: "http://localhost/" });
   Object.defineProperty(win.navigator, "language", { configurable: true, value: "en-US" });
   Object.defineProperties(globalThis, {
@@ -52,10 +77,14 @@ beforeEach(() => {
     window: { configurable: true, value: win },
     navigator: { configurable: true, value: win.navigator },
     localStorage: { configurable: true, value: win.localStorage },
+    HTMLElement: { configurable: true, value: win.HTMLElement },
   });
   (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
-  Object.defineProperty(globalThis, "confirm", { configurable: true, value: () => true });
-  Object.defineProperty(globalThis, "alert", { configurable: true, value: () => {} });
+  for (const name of ["confirm", "alert", "prompt"] as const) {
+    const trap = () => { touched.push(name); throw new Error(`${name}() must not be reached`); };
+    Object.defineProperty(globalThis, name, { configurable: true, value: trap });
+    Object.defineProperty(win, name, { configurable: true, value: trap });
+  }
 
   host = win.document.createElement("div") as unknown as HTMLElement;
   win.document.body.appendChild(host as never);
@@ -65,11 +94,10 @@ afterEach(() => {
   if (root) act(() => root!.unmount());
   root = null;
   Object.defineProperty(globalThis, "fetch", { configurable: true, value: originalFetch });
-  Object.defineProperty(globalThis, "confirm", { configurable: true, value: originalConfirm });
-  Object.defineProperty(globalThis, "alert", { configurable: true, value: originalAlert });
   for (const key of globals) {
     Object.defineProperty(globalThis, key, { configurable: true, value: previous[key] });
   }
+  expect(touched).toEqual([]);
 });
 
 /** Mirrors how Models.tsx wires the controller, banner, and head action. */
@@ -77,7 +105,11 @@ function Harness(props: {
   initialState: "fresh" | "stale" | "not_running" | "unknown" | null;
   onReload: () => void;
 }) {
-  const controller = useCodexRestart("", { onSettled: () => props.onReload() });
+  const controller = useCodexRestart("", {
+    onSettled: () => props.onReload(),
+    // Models routes this to the shell, which outlives the page; the test just records it.
+    report: (message, tone) => { reports.push({ message, tone }); },
+  });
   return (
     <div>
       <button type="button" data-testid="head" onClick={() => { void controller.restart(); }}
@@ -120,7 +152,7 @@ test("a restart from the PAGE-HEAD button refreshes staleness", async () => {
 
   render(<Harness initialState="stale" onReload={() => { reloads += 1; }} />);
   const head = host.querySelector('[data-testid="head"]') as HTMLButtonElement;
-  await act(async () => { head.click(); });
+  await clickAndAnswer(head, "accept");
 
   expect(reloads).toBe(1);
 });
@@ -137,7 +169,7 @@ test("a restart from the BANNER button refreshes staleness through the same path
 
   render(<Harness initialState="stale" onReload={() => { reloads += 1; }} />);
   const button = host.querySelector(".codex-stale-banner button") as HTMLButtonElement;
-  await act(async () => { button.click(); });
+  await clickAndAnswer(button, "accept");
 
   expect(reloads).toBe(1);
 });
@@ -157,7 +189,7 @@ test("nothing_running also counts as settled", async () => {
 
   render(<Harness initialState="stale" onReload={() => { reloads += 1; }} />);
   const head = host.querySelector('[data-testid="head"]') as HTMLButtonElement;
-  await act(async () => { head.click(); });
+  await clickAndAnswer(head, "accept");
 
   expect(reloads).toBe(1);
 });
@@ -178,16 +210,15 @@ test("an unresolved outcome does not clear the banner", async () => {
 
   render(<Harness initialState="stale" onReload={() => { reloads += 1; }} />);
   const head = host.querySelector('[data-testid="head"]') as HTMLButtonElement;
-  await act(async () => { head.click(); });
+  await clickAndAnswer(head, "accept");
 
   expect(reloads).toBe(0);
   expect(host.querySelector(".codex-stale-banner")).not.toBeNull();
 });
 
-test("a declined confirm sends no request and does not refresh", async () => {
+test("a dismissed consent dialog sends no request and does not refresh", async () => {
   let fetches = 0;
   let reloads = 0;
-  Object.defineProperty(globalThis, "confirm", { configurable: true, value: () => false });
   Object.defineProperty(globalThis, "fetch", {
     configurable: true,
     value: async () => {
@@ -198,10 +229,11 @@ test("a declined confirm sends no request and does not refresh", async () => {
 
   render(<Harness initialState="stale" onReload={() => { reloads += 1; }} />);
   const head = host.querySelector('[data-testid="head"]') as HTMLButtonElement;
-  await act(async () => { head.click(); });
+  await clickAndAnswer(head, "dismiss");
 
   expect(fetches).toBe(0);
   expect(reloads).toBe(0);
+  expect(reports).toEqual([]);
 });
 
 test("both controls disable while one restart is pending", async () => {
@@ -223,6 +255,7 @@ test("both controls disable while one restart is pending", async () => {
   const bannerButton = host.querySelector(".codex-stale-banner button") as HTMLButtonElement;
 
   await act(async () => { head.click(); });
+  await act(async () => { acceptActionDialog(dialogDocument()); await Promise.resolve(); });
   // One controller drives both, so the banner's button is disabled too — the two
   // controls on this page can never disagree about whether a restart is running.
   expect(head.disabled).toBe(true);
@@ -248,6 +281,7 @@ test("unmounting during a pending restart does not throw", async () => {
   render(<Harness initialState="stale" onReload={() => {}} />);
   const head = host.querySelector('[data-testid="head"]') as HTMLButtonElement;
   await act(async () => { head.click(); });
+  await act(async () => { acceptActionDialog(dialogDocument()); await Promise.resolve(); });
 
   act(() => root!.unmount());
   root = null;
@@ -258,22 +292,45 @@ test("unmounting during a pending restart does not throw", async () => {
 test("a timeout is localized, not left as the transport's English default", async () => {
   // The hook once dropped formatTimeout when it was rewritten, which silently
   // reverted this string to the helper's hardcoded English.
-  let seen = "";
-  Object.defineProperty(globalThis, "alert", {
+  Object.defineProperty(globalThis, "fetch", {
     configurable: true,
-    value: (message: string) => { seen = message; },
+    value: async () => { throw new DOMException("timed out", "TimeoutError"); },
   });
+
+  render(<Harness initialState="stale" onReload={() => {}} />);
+  const head = host.querySelector('[data-testid="head"]') as HTMLButtonElement;
+  await clickAndAnswer(head, "accept");
+
+  // The English catalog entry, not the transport fallback sentence.
+  expect(reports).toHaveLength(1);
+  expect(reports[0].message).toContain("It may still be stopping app-servers");
+  expect(reports[0].tone).toBe("err");
+});
+
+test("unmounting while the consent is open withdraws it and sends nothing", async () => {
+  /*
+   * The consent is asynchronous now, so the surface can disappear while the question is on
+   * screen. Answering it afterwards would send a stop against the closure's captured base —
+   * a target the user is no longer looking at.
+   */
+  let fetches = 0;
   Object.defineProperty(globalThis, "fetch", {
     configurable: true,
-    value: async () => { throw new DOMException("timed out", "TimeoutError"); },
+    value: async () => { fetches += 1; return new Response("{}", { status: 200 }); },
   });
 
   render(<Harness initialState="stale" onReload={() => {}} />);
   const head = host.querySelector('[data-testid="head"]') as HTMLButtonElement;
   await act(async () => { head.click(); });
+  expect(actionDialogOpen(dialogDocument())).toBe(true);
 
-  // The English catalog entry, not the transport fallback sentence.
-  expect(seen).toContain("It may still be stopping app-servers");
+  act(() => root!.unmount());
+  root = null;
+  await act(async () => { await Promise.resolve(); });
+
+  expect(actionDialogOpen(dialogDocument())).toBe(false);
+  expect(fetches).toBe(0);
+  expect(reports).toEqual([]);
 });
 
 test("a settled restart does not call back after unmount", async () => {
@@ -296,6 +353,7 @@ test("a settled restart does not call back after unmount", async () => {
   render(<Harness initialState="stale" onReload={() => { settled += 1; }} />);
   const head = host.querySelector('[data-testid="head"]') as HTMLButtonElement;
   await act(async () => { head.click(); });
+  await act(async () => { acceptActionDialog(dialogDocument()); await Promise.resolve(); });
 
   act(() => root!.unmount());
   root = null;
diff --git a/gui/tests/compaction-routing-panel.test.tsx b/gui/tests/compaction-routing-panel.test.tsx
index 9e698c02bb6..13fb2cde8d0 100644
--- a/gui/tests/compaction-routing-panel.test.tsx
+++ b/gui/tests/compaction-routing-panel.test.tsx
@@ -14,8 +14,12 @@ let container: HTMLDivElement;
 let setting: { model: string; reasoningEffort?: string; triggers?: string[] } | null;
 let failLoad: boolean;
 let failSave: boolean;
+let combosUnavailable: boolean;
 let writes: unknown[];
 const models = [{ id: "cheap", provider: "gateway", namespaced: "gateway/cheap" }, { id: "compact", provider: "combo", namespaced: "combo/compact" }];
+// A combo reached through an alias carries no `combo/` prefix, which is the shape #5216 was
+// filed about: the panel has to learn what the selection resolves to, not read its name.
+const ALIASED_COMBO = { id: "fast", model: "quickpick", alias: "quickpick", targets: [{ provider: "xai", model: "a" }, { provider: "gateway", model: "b" }] };
 
 beforeEach(() => {
   previous = Object.fromEntries(globals.map(key => [key, Object.getOwnPropertyDescriptor(globalThis, key)]));
@@ -25,10 +29,14 @@ beforeEach(() => {
   }
   Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", { configurable: true, value: true });
   win.localStorage.setItem("ocx-lang", "en");
-  setting = null; failLoad = false; failSave = false; writes = [];
+  setting = null; failLoad = false; failSave = false; combosUnavailable = false; writes = [];
   Object.defineProperty(globalThis, "fetch", { configurable: true, writable: true, value: async (_input: unknown, init?: RequestInit) => {
     if (String(_input).endsWith("/api/combos")) {
-      return Response.json({ combos: [{ id: "compact", model: "combo/compact", targets: [{ provider: "gateway", model: "a" }, { provider: "openai-apikey", model: "b" }, { provider: "gateway", model: "c" }] }] });
+      if (combosUnavailable) return Response.json({ error: "unavailable" }, { status: 503 });
+      return Response.json({ combos: [
+        { id: "compact", model: "combo/compact", targets: [{ provider: "gateway", model: "a" }, { provider: "openai-apikey", model: "b" }, { provider: "gateway", model: "c" }] },
+        ALIASED_COMBO,
+      ] });
     }
     if (init?.method === "PUT") {
       const body = JSON.parse(String(init.body));
@@ -148,7 +156,45 @@ test("discloses that the selected provider receives the full conversation", asyn
   await choose("model", "gateway/cheap");
   expect(container.querySelector('[role="note"]')?.textContent).toContain("sends the full conversation contents to gateway for summarization");
   await choose("model", "combo/compact");
-  expect(container.querySelector('[role="note"]')?.textContent).toContain("every target of combo combo/compact (gateway, openai-apikey), including failover targets");
+  const comboNote = container.querySelector('[role="note"]')?.textContent ?? "";
+  expect(comboNote).toContain("combo combo/compact");
+  expect(comboNote).toContain("(gateway, openai-apikey)");
+  // The runtime tries one target at a time and stops at the first answer; the panel used to
+  // promise fan-out to every target, which an operator would budget latency and cost for.
+  expect(comboNote).toContain("in order and uses the first that answers");
+  expect(comboNote).not.toContain("every target");
   await choose("model", "Use conversation model");
   expect(container.querySelector('[role="note"]')).toBeNull();
 });
+
+test("names the targets of a combo reached through an alias", async () => {
+  setting = { model: ALIASED_COMBO.model };
+  await render();
+  const note = container.querySelector('[role="note"]')?.textContent ?? "";
+  // Before #5216 this selection had no `combo/` prefix, so the panel called it a provider and
+  // named none of its targets.
+  expect(note).toContain(`combo ${ALIASED_COMBO.model}`);
+  expect(note).toContain("(xai, gateway)");
+  expect(note).not.toContain("its configured target providers");
+  expect(note).toContain("in order and uses the first that answers");
+});
+
+test("still calls a prefixed combo a combo when the combo list is unavailable", async () => {
+  // The combo list is the only source of target names, and losing it must not downgrade the
+  // disclosure to "the provider named combo receives your conversation".
+  combosUnavailable = true;
+  setting = { model: "combo/compact" };
+  await render();
+  const note = container.querySelector('[role="note"]')?.textContent ?? "";
+  expect(note).toContain("combo combo/compact");
+  expect(note).toContain("its configured target providers");
+});
+
+test("an alias that shadows an Object member is not read as a target list", async () => {
+  // A combo id is free-form, so `constructor` is a legal alias. Reading it off a plain object
+  // would hand the renderer a function to join.
+  setting = { model: "constructor" };
+  await render();
+  const note = container.querySelector('[role="note"]')?.textContent ?? "";
+  expect(note).toContain("sends the full conversation contents to constructor for summarization");
+});
diff --git a/gui/tests/desktop-shell.test.ts b/gui/tests/desktop-shell.test.ts
new file mode 100644
index 00000000000..936c27dff68
--- /dev/null
+++ b/gui/tests/desktop-shell.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import {
+  desktopShellVersion,
+  hostOs,
+  isDesktopShell,
+  isExternalLink,
+} from "../src/lib/desktop-shell";
+
+const tauriMac = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) OpenCodexDesktop/2.61.0";
+const tauriWindows = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) OpenCodexDesktop/2.61.0";
+const tauriLinux = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) OpenCodexDesktop/2.61.0";
+
+describe("desktop shell user-agent helpers", () => {
+  test("detects shell versions across desktop platforms", () => {
+    expect(desktopShellVersion(tauriMac)).toBe("2.61.0");
+    expect(isDesktopShell(tauriWindows)).toBe(true);
+    expect(isDesktopShell("Mozilla/5.0 Chrome/140.0")).toBe(false);
+  });
+
+  test("detects host operating systems without treating Android as Linux", () => {
+    expect(hostOs(tauriMac)).toBe("macos");
+    expect(hostOs(tauriWindows)).toBe("windows");
+    expect(hostOs(tauriLinux)).toBe("linux");
+    expect(hostOs("Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) Chrome/140.0")).toBe("macos");
+    expect(hostOs("Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/140.0")).toBe("windows");
+    expect(hostOs("Mozilla/5.0 (X11; Linux x86_64) Chrome/140.0")).toBe("linux");
+    expect(hostOs("Mozilla/5.0 (Linux; Android 15) Chrome/140.0")).toBe("unknown");
+    expect(hostOs("unknown")).toBe("unknown");
+  });
+
+  test("recognizes only absolute cross-origin HTTP links", () => {
+    expect(isExternalLink("https://example.com/a", "http://127.0.0.1:10100")).toBe(true);
+    expect(isExternalLink("http://127.0.0.1:10100/a", "http://127.0.0.1:10100")).toBe(false);
+    expect(isExternalLink("/#/usage", "http://127.0.0.1:10100")).toBe(false);
+    expect(isExternalLink("mailto:hello@example.com", "http://127.0.0.1:10100")).toBe(false);
+  });
+});
diff --git a/gui/tests/fr-localization.test.ts b/gui/tests/fr-localization.test.ts
index 5c5d8aa73d8..64b6bcb4a4e 100644
--- a/gui/tests/fr-localization.test.ts
+++ b/gui/tests/fr-localization.test.ts
@@ -13,6 +13,17 @@ import { statusCodeInfo } from "../src/status-codes";
 const FR_CATALOG_URL = new URL("../src/i18n/fr.ts", import.meta.url);
 const PLACEHOLDER_RE = /\{([a-zA-Z0-9_]+)\}/g;
 
+/**
+ * A value carrying no letters once its placeholders are removed has nothing to translate.
+ * An em dash, a unit symbol and "{position} / {total}" are identical in every locale by
+ * construction, so matching English is evidence of nothing. Deriving that from the value
+ * keeps the allowlist below for real words instead of growing it each time the UI gains
+ * another symbol.
+ */
+function carriesTranslatableWords(value: string): boolean {
+  return /\p{L}/u.test(value.replace(/\{[a-zA-Z0-9_]+\}/g, " "));
+}
+
 const INTENTIONAL_ENGLISH = new Set<TKey>([
   // Units, symbols, protocol values, machine labels, and product names.
   "integrations.cursor.noControl",
@@ -223,7 +234,9 @@ describe("French base catalog", () => {
 
     const french = (await import("../src/i18n/fr")).fr;
     const accidental = (Object.keys(DICTS.en) as TKey[]).filter(key =>
-      french[key] === DICTS.en[key] && !INTENTIONAL_ENGLISH.has(key)
+      french[key] === DICTS.en[key]
+      && !INTENTIONAL_ENGLISH.has(key)
+      && carriesTranslatableWords(String(DICTS.en[key]))
     );
 
     expect(accidental).toEqual([]);
diff --git a/gui/tests/helpers/action-dialog.ts b/gui/tests/helpers/action-dialog.ts
new file mode 100644
index 00000000000..81397d6d45b
--- /dev/null
+++ b/gui/tests/helpers/action-dialog.ts
@@ -0,0 +1,43 @@
+/**
+ * Drives the in-page consent dialog that replaced `confirm()` and `prompt()`.
+ *
+ * Component tests used to answer consent by stubbing `confirm()` to true, which is exactly
+ * why CI never saw that the app's webview draws no platform dialog at all. Answering the
+ * real dialog instead means a component that stopped opening one fails here.
+ */
+function currentDialog(doc: Document): HTMLDialogElement {
+  const dialog = doc.querySelector("dialog.modal-overlay");
+  if (!dialog) throw new Error("no in-page dialog is open");
+  return dialog as HTMLDialogElement;
+}
+
+/** True when a consent or text-entry dialog is on screen. */
+export function actionDialogOpen(doc: Document): boolean {
+  return doc.querySelector("dialog.modal-overlay") !== null;
+}
+
+/** The dialog's message, as the user reads it. */
+export function actionDialogText(doc: Document): string {
+  return currentDialog(doc).textContent ?? "";
+}
+
+/** Answers yes. The accepting control is the form's submit button. */
+export function acceptActionDialog(doc: Document): void {
+  const accept = currentDialog(doc).querySelector("button[type=submit]");
+  if (!accept) throw new Error("the dialog has no accepting button");
+  (accept as HTMLButtonElement).click();
+}
+
+/** Answers no, which must leave the caller's early return intact. */
+export function dismissActionDialog(doc: Document): void {
+  const cancel = currentDialog(doc).querySelector(".modal-actions button[type=button]");
+  if (!cancel) throw new Error("the dialog has no cancelling button");
+  (cancel as HTMLButtonElement).click();
+}
+
+/** Types into the text-entry dialog before accepting it. */
+export function fillActionDialog(doc: Document, value: string): void {
+  const input = currentDialog(doc).querySelector("input");
+  if (!input) throw new Error("the dialog has no text field");
+  (input as HTMLInputElement).value = value;
+}
diff --git a/gui/tests/locale-parity.test.ts b/gui/tests/locale-parity.test.ts
index cc602a8a9ce..acc20c98140 100644
--- a/gui/tests/locale-parity.test.ts
+++ b/gui/tests/locale-parity.test.ts
@@ -14,6 +14,16 @@ async function readDict(locale: string): Promise<Map<string, string>> {
   return out;
 }
 
+/**
+ * A value with no letters once its placeholders are removed has nothing to translate: an em
+ * dash, a currency template, a bare glyph. Matching English there is evidence of nothing, so
+ * it is derived from the value instead of growing the allowlist by one entry every time the
+ * UI gains another symbol.
+ */
+function carriesTranslatableWords(value: string): boolean {
+  return /\p{L}/u.test(value.replace(/\{[a-zA-Z0-9_]+\}/g, " "));
+}
+
 // When the English locale grows, `scripts/sync-locale-keys.mjs` seeds the new key into every
 // locale as an English placeholder so the build does not break. That is fine for de/ko/ja/zh/ru
 // (they each have a human owner who will translate later), but zh-TW is this PR's contribution
@@ -192,6 +202,7 @@ test("zh-TW ships no untranslated English placeholders beyond the intentional al
     const enValue = en.get(key);
     if (enValue === undefined) continue; // key-set parity is the other test's job
     if (!value.trim()) continue; // blank-value is the other test's job
+    if (!carriesTranslatableWords(value)) continue; // a symbol is identical in every locale
     if (value === enValue && !ZH_TW_KEEP_ENGLISH.has(key)) {
       stale.push(key);
     }
diff --git a/gui/tests/memory-observability-card.test.tsx b/gui/tests/memory-observability-card.test.tsx
index 1fca1bcd332..6c134c161ef 100644
--- a/gui/tests/memory-observability-card.test.tsx
+++ b/gui/tests/memory-observability-card.test.tsx
@@ -4,10 +4,10 @@ import { act } from "react";
 import type { Root } from "react-dom/client";
 import { LanguageProvider } from "../src/i18n/provider";
 import MemoryObservabilityCard from "../src/components/MemoryObservabilityCard";
+import { acceptActionDialog, actionDialogOpen, dismissActionDialog } from "./helpers/action-dialog";
 
 const originalFetch = globalThis.fetch;
 let restoreGlobals: (() => void) | undefined;
-let originalConfirm: typeof window.confirm | undefined;
 
 beforeEach(() => {
   Object.defineProperty(globalThis.navigator, "language", { configurable: true, value: "en-US" });
@@ -32,8 +32,6 @@ beforeEach(() => {
 
 afterEach(() => {
   globalThis.fetch = originalFetch;
-  if (originalConfirm && typeof window !== "undefined") window.confirm = originalConfirm;
-  originalConfirm = undefined;
   restoreGlobals?.();
 });
 
@@ -152,7 +150,7 @@ test("a non-OK response degrades to the unavailable note instead of crashing", a
   await act(async () => { root.unmount(); });
 });
 
-test("Drain & restart posts /api/system/restart after confirm", async () => {
+test("Drain & restart posts /api/system/restart only after the in-page dialog is accepted", async () => {
   let restartPosts = 0;
   const { root, container, testWindow } = await mountCard((url) => {
     if (url.includes("/api/system/restart")) {
@@ -167,9 +165,6 @@ test("Drain & restart posts /api/system/restart after confirm", async () => {
     return defaultRespond(url);
   });
 
-  originalConfirm = window.confirm;
-  window.confirm = () => true;
-
   const button = Array.from(container.querySelectorAll("button")).find(
     (el) => (el.textContent ?? "").includes("Drain & restart"),
   );
@@ -180,12 +175,47 @@ test("Drain & restart posts /api/system/restart after confirm", async () => {
     await new Promise(resolve => testWindow.setTimeout(resolve, 0));
   });
 
+  // The click alone must not restart anything: the consent is a real dialog now, and
+  // inside the app the platform one drew nothing, so nothing could answer it.
+  expect(actionDialogOpen(testWindow.document as unknown as Document)).toBe(true);
+  expect(restartPosts).toBe(0);
+
+  await act(async () => {
+    acceptActionDialog(testWindow.document as unknown as Document);
+    await new Promise(resolve => testWindow.setTimeout(resolve, 0));
+  });
+
   expect(restartPosts).toBe(1);
   expect(container.textContent ?? "").toContain("Draining");
 
   await act(async () => { root.unmount(); });
 });
 
+test("dismissing the restart dialog sends no request", async () => {
+  let restartPosts = 0;
+  const { root, container, testWindow } = await mountCard((url) => {
+    if (url.includes("/api/system/restart")) { restartPosts += 1; return Response.json({ success: true }, { status: 202 }); }
+    return defaultRespond(url);
+  });
+
+  const button = Array.from(container.querySelectorAll("button")).find(
+    (el) => (el.textContent ?? "").includes("Drain & restart"),
+  );
+  await act(async () => {
+    button!.dispatchEvent(new testWindow.MouseEvent("click", { bubbles: true }));
+    await new Promise(resolve => testWindow.setTimeout(resolve, 0));
+  });
+  await act(async () => {
+    dismissActionDialog(testWindow.document as unknown as Document);
+    await new Promise(resolve => testWindow.setTimeout(resolve, 0));
+  });
+
+  expect(restartPosts).toBe(0);
+  expect(container.textContent ?? "").not.toContain("Draining");
+
+  await act(async () => { root.unmount(); });
+});
+
 test("restart reconnect polls authenticated management health instead of denied /healthz", async () => {
   let memoryReads = 0;
   const { root, container, testWindow, calls } = await mountCard((url) => {
@@ -205,8 +235,6 @@ test("restart reconnect polls authenticated management health instead of denied
     return new Response(null, { status: 404 });
   });
 
-  originalConfirm = window.confirm;
-  window.confirm = () => true;
   const button = Array.from(container.querySelectorAll("button")).find(
     (el) => (el.textContent ?? "").includes("Drain & restart"),
   );
@@ -214,6 +242,10 @@ test("restart reconnect polls authenticated management health instead of denied
 
   await act(async () => {
     button!.dispatchEvent(new testWindow.MouseEvent("click", { bubbles: true }));
+    await new Promise(resolve => testWindow.setTimeout(resolve, 0));
+  });
+  await act(async () => {
+    acceptActionDialog(testWindow.document as unknown as Document);
     for (let attempt = 0; attempt < 20; attempt += 1) {
       await new Promise(resolve => testWindow.setTimeout(resolve, 0));
       if (calls().some(call => call.includes("/api/system/health"))) break;
diff --git a/gui/tests/provider-model-management.test.tsx b/gui/tests/provider-model-management.test.tsx
index 01dc6068593..34f6ae5b330 100644
--- a/gui/tests/provider-model-management.test.tsx
+++ b/gui/tests/provider-model-management.test.tsx
@@ -7,10 +7,14 @@ import ProviderModels from "../src/components/provider-workspace/ProviderModels"
 import { LanguageProvider } from "../src/i18n/provider";
 import type { ModelRow } from "../src/pages/models-shared";
 import type { WorkspaceProvider } from "../src/provider-workspace/catalog";
+import { acceptActionDialog, actionDialogOpen, dismissActionDialog } from "./helpers/action-dialog";
 
-const globals = ["document", "window", "navigator", "localStorage", "sessionStorage", "IS_REACT_ACT_ENVIRONMENT"] as const;
+const globals = ["document", "window", "navigator", "localStorage", "sessionStorage", "HTMLElement",
+  "IS_REACT_ACT_ENVIRONMENT", "confirm", "alert", "prompt"] as const;
 const originalFetch = globalThis.fetch;
 let previous: Record<(typeof globals)[number], unknown>;
+/** Platform dialogs reached, which must stay empty. */
+let touched: string[];
 let win: Window;
 let root: Root | undefined;
 let host: HTMLElement;
@@ -102,10 +106,18 @@ beforeEach(() => {
   win = new Window({ url: "http://localhost/#providers" });
   Object.defineProperty(win.navigator, "language", { configurable: true, value: "en-US" });
   for (const [key, value] of Object.entries({ document: win.document, window: win, navigator: win.navigator,
-    localStorage: win.localStorage, sessionStorage: win.sessionStorage, IS_REACT_ACT_ENVIRONMENT: true })) {
+    localStorage: win.localStorage, sessionStorage: win.sessionStorage, HTMLElement: win.HTMLElement,
+    IS_REACT_ACT_ENVIRONMENT: true })) {
     Object.defineProperty(globalThis, key, { configurable: true, value });
   }
-  win.confirm = () => true;
+  // The removal gate is an in-page dialog now. Every platform dialog is a trap: the app's
+  // webview draws none of them, so reaching one is the defect this lane removed.
+  touched = [];
+  for (const name of ["confirm", "alert", "prompt"] as const) {
+    const trap = () => { touched.push(name); throw new Error(`${name}() must not be reached`); };
+    Object.defineProperty(globalThis, name, { configurable: true, value: trap });
+    Object.defineProperty(win, name, { configurable: true, value: trap });
+  }
   rows = []; custom = []; selected = {}; available = {}; requests = []; reads = {}; recovery = 0;
   deleteMode = "ok"; underlying = undefined; writeGate = undefined; queues.clear();
   globalThis.fetch = api as typeof fetch;
@@ -117,6 +129,7 @@ afterEach(async () => {
   root = undefined; globalThis.fetch = originalFetch;
   win.close();
   for (const key of globals) Object.defineProperty(globalThis, key, { configurable: true, value: previous[key] });
+  expect(touched).toEqual([]);
 });
 
 // Observe DOM state, not elapsed time. Timeout is only a failing-test bound.
@@ -172,7 +185,21 @@ async function mount(name = "vendor") {
   const { createRoot } = await import("react-dom/client");
   await act(async () => { root = createRoot(host); root.render(<LanguageProvider><Harness /></LanguageProvider>); });
 }
-async function click(button: HTMLButtonElement) { expect(button).toBeDefined(); await act(async () => { button.click(); }); }
+/**
+ * Clicks, then accepts the in-page consent dialog when the control opens one. Removal used
+ * to be gated by `confirm()`, which this file stubbed to true — and which the desktop
+ * webview answers false without drawing, so Delete and Hide did nothing there. The
+ * dismissal cases drive the dialog themselves, so they can assert it appeared at all.
+ */
+async function click(button: HTMLButtonElement) {
+  expect(button).toBeDefined();
+  await act(async () => { button.click(); });
+  if (!actionDialogOpen(win.document as unknown as Document)) return;
+  await act(async () => {
+    acceptActionDialog(win.document as unknown as Document);
+    await Promise.resolve();
+  });
+}
 async function current() { await waitFor(() => host.querySelector('[data-testid="parent-ready"]')?.getAttribute("data-ready") === "true"); }
 async function refreshCurrent() { await act(async () => { refresh(); }); await current(); }
 
@@ -223,10 +250,19 @@ test("same-label custom and account-native rows keep disjoint Delete/Hide identi
 });
 
 for (const customRow of [true, false]) {
-  test(`cancel ${customRow ? "Delete" : "Hide"} sends no write and preserves the row`, async () => {
+  test(`dismissing ${customRow ? "Delete" : "Hide"} sends no write and preserves the row`, async () => {
     if (customRow) addCustom(); else rows = [row("custom-model")];
-    win.confirm = () => false; await mount(); await waitFor(() => actionable().length === 1);
-    await click(action("vendor/custom-model", customRow ? "Delete" : "Hide")); expect(requests).toEqual([]); expect(ids()).toEqual(["custom-model"]);
+    await mount(); await waitFor(() => actionable().length === 1);
+    const button = action("vendor/custom-model", customRow ? "Delete" : "Hide");
+    await act(async () => { button.click(); });
+    /*
+     * The gate must actually appear. Answering through the shared `click` helper would let
+     * this case pass if the control became a no-op — which is precisely the defect this
+     * lane exists for, since inside the app every one of these buttons did nothing.
+     */
+    expect(actionDialogOpen(win.document as unknown as Document)).toBe(true);
+    await act(async () => { dismissActionDialog(win.document as unknown as Document); await Promise.resolve(); });
+    expect(requests).toEqual([]); expect(ids()).toEqual(["custom-model"]);
   });
 }
 
@@ -250,7 +286,12 @@ test("single flight blocks a second row until the first write and all reconcilia
   writeGate = new Promise<void>(resolve => { releaseWrite = resolve; });
   await mount(); await waitFor(() => actionable().length === 2);
   const first = action("vendor/custom-model", "Delete"); const second = action("vendor/second", "Hide");
-  await act(async () => { first.click(); second.click(); }); expect(requests).toHaveLength(1);
+  await act(async () => { first.click(); second.click(); });
+  // One dialog, not two: the flight is claimed before consent is awaited, so the second
+  // row cannot open its own gate while this one is unanswered.
+  expect(win.document.querySelectorAll("dialog.modal-overlay")).toHaveLength(1);
+  await act(async () => { acceptActionDialog(win.document as unknown as Document); await Promise.resolve(); });
+  expect(requests).toHaveLength(1);
   const inventory = hold("/api/models"); const ownership = hold("/api/custom-models");
   await act(async () => { releaseWrite(); }); await inventory.started; await ownership.started;
   expect(actionable()).toEqual([]);
diff --git a/gui/tests/provider-settings-account-mode.test.tsx b/gui/tests/provider-settings-account-mode.test.tsx
index 446a483e0bf..7db3f2c6d8d 100644
--- a/gui/tests/provider-settings-account-mode.test.tsx
+++ b/gui/tests/provider-settings-account-mode.test.tsx
@@ -6,13 +6,18 @@ import ProviderSettings from "../src/components/provider-workspace/ProviderSetti
 import type { ProviderUpdatePatch } from "../src/components/provider-workspace/types";
 import { LanguageProvider } from "../src/i18n/provider";
 import type { WorkspaceItem } from "../src/provider-workspace/catalog";
+import { acceptActionDialog, actionDialogOpen, dismissActionDialog } from "./helpers/action-dialog";
 
-const globals = ["document", "window", "navigator", "localStorage", "IS_REACT_ACT_ENVIRONMENT"] as const;
+const globals = ["document", "window", "navigator", "localStorage", "HTMLElement", "IS_REACT_ACT_ENVIRONMENT",
+  "confirm", "alert", "prompt"] as const;
 let previousGlobals: Record<(typeof globals)[number], unknown>;
 let testWindow: Window;
+/** Platform dialogs reached, which must stay empty: the app's webview draws none of them. */
+let touched: string[];
 
 beforeEach(() => {
   previousGlobals = Object.fromEntries(globals.map(key => [key, Reflect.get(globalThis, key)])) as typeof previousGlobals;
+  touched = [];
   testWindow = new Window({ url: "http://localhost/#providers/workspace" });
   Object.defineProperty(testWindow.navigator, "language", { configurable: true, value: "en-US" });
   Object.defineProperties(globalThis, {
@@ -20,8 +25,13 @@ beforeEach(() => {
     window: { configurable: true, value: testWindow },
     navigator: { configurable: true, value: testWindow.navigator },
     localStorage: { configurable: true, value: testWindow.localStorage },
+    HTMLElement: { configurable: true, value: testWindow.HTMLElement },
   });
-  setConfirm(true);
+  for (const name of ["confirm", "alert", "prompt"] as const) {
+    const trap = () => { touched.push(name); throw new Error(`${name}() must not be reached`); };
+    Object.defineProperty(globalThis, name, { configurable: true, value: trap });
+    Object.defineProperty(testWindow, name, { configurable: true, value: trap });
+  }
   (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 });
 
@@ -30,11 +40,10 @@ afterEach(() => {
   for (const key of globals) {
     Object.defineProperty(globalThis, key, { configurable: true, value: previousGlobals[key] });
   }
+  expect(touched).toEqual([]);
 });
 
-function setConfirm(result: boolean): void {
-  Object.defineProperty(testWindow, "confirm", { configurable: true, value: () => result });
-}
+const dialogDocument = () => testWindow.document as unknown as Document;
 
 function openAiItem(mode: "pool" | "direct" = "pool"): WorkspaceItem {
   return {
@@ -90,12 +99,23 @@ function modeSelect(container: HTMLElement): HTMLSelectElement {
   return select!;
 }
 
-async function chooseMode(select: HTMLSelectElement, value: string): Promise<void> {
+/**
+ * Picks a mode and answers the in-page consent dialog. The gate used to be `confirm()`,
+ * which this file stubbed — and which the desktop webview answers false without drawing,
+ * so the control could not be used there at all.
+ */
+async function chooseMode(select: HTMLSelectElement, value: string, answer: "accept" | "dismiss" = "accept"): Promise<void> {
   await act(async () => {
     Object.getOwnPropertyDescriptor(testWindow.HTMLSelectElement.prototype, "value")!
       .set!.call(select, value);
     select.dispatchEvent(new testWindow.Event("change", { bubbles: true }));
   });
+  expect(actionDialogOpen(dialogDocument())).toBe(true);
+  await act(async () => {
+    if (answer === "accept") acceptActionDialog(dialogDocument());
+    else dismissActionDialog(dialogDocument());
+    await Promise.resolve();
+  });
 }
 
 test("a confirmed mode change sends the exact standalone codexAccountMode patch", async () => {
@@ -110,12 +130,11 @@ test("a confirmed mode change sends the exact standalone codexAccountMode patch"
   await act(async () => { root.unmount(); });
 });
 
-test("a cancelled confirmation sends no patch and snaps the select back", async () => {
+test("a dismissed consent dialog sends no patch and snaps the select back", async () => {
   const { root, container, patches } = await mountSettings(openAiItem("pool"));
   const select = modeSelect(container);
-  setConfirm(false);
 
-  await chooseMode(select, "direct");
+  await chooseMode(select, "direct", "dismiss");
 
   expect(patches).toHaveLength(0);
   expect(select.value).toBe("pool");
diff --git a/gui/tests/ui-font-fallback.test.ts b/gui/tests/ui-font-fallback.test.ts
new file mode 100644
index 00000000000..a5ec926f219
--- /dev/null
+++ b/gui/tests/ui-font-fallback.test.ts
@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+
+const css = await Bun.file(new URL("../src/styles.css", import.meta.url)).text();
+const fontStack = css.replace(/\/\*[\s\S]*?\*\//g, "")
+  .match(/--font-ui\s*:\s*([^;]+);/)?.[1];
+if (!fontStack) throw new Error("The UI font stack is missing.");
+const families = fontStack.split(",").map(family =>
+  family.trim().replace(/^(["'])(.*)\1$/, "$2"),
+);
+
+test("product fonts retain priority in the UI font stack", () => {
+  expect(families.slice(0, 3)).toEqual(["OpenAI Sans", "Pretendard Variable", "Pretendard"]);
+});
+
+// Keep system fonts ahead of Apple SD Gothic Neo, which also covers Latin.
+// This guards fallback order; actual glyph selection requires a browser check.
+test.each(["-apple-system", "BlinkMacSystemFont", "Segoe UI", "Roboto", "system-ui"])(
+  "%s precedes Apple SD Gothic Neo in the UI font stack",
+  systemFont => {
+    const systemIndex = families.indexOf(systemFont);
+    const koreanIndex = families.indexOf("Apple SD Gothic Neo");
+    expect(systemIndex).toBeGreaterThanOrEqual(0);
+    expect(koreanIndex).toBeGreaterThanOrEqual(0);
+    expect(systemIndex).toBeLessThan(koreanIndex);
+  },
+);
diff --git a/gui/tests/usage-companion-utils.test.ts b/gui/tests/usage-companion-utils.test.ts
new file mode 100644
index 00000000000..2fd02c7fd9e
--- /dev/null
+++ b/gui/tests/usage-companion-utils.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import {
+  bucketMinutesForWindow,
+  buildCompanionSettingsPatch,
+  chartPolylinePoints,
+  chartStackedBarRects,
+  formatCompanionTokens,
+  groupCompanionModels,
+  toggleCompanionModels,
+} from "../src/pages/usage-companion-utils";
+
+describe("usage companion utilities", () => {
+  test("maps chart windows to bounded buckets", () => {
+    expect([6, 24, 72, 168].map(bucketMinutesForWindow)).toEqual([15, 60, 180, 360]);
+  });
+
+  test("normalizes empty templates and all-selected models", () => {
+    expect(buildCompanionSettingsPatch({
+      menuBarTemplate: " ",
+      models: ["openai/gpt-5", "anthropic/claude"],
+    }, ["openai/gpt-5", "anthropic/claude"])).toEqual({
+      menuBarTemplate: null,
+      models: null,
+    });
+    expect(buildCompanionSettingsPatch({ models: ["openai/gpt-5"] }, ["openai/gpt-5", "anthropic/claude"])).toEqual({
+      models: ["openai/gpt-5"],
+    });
+  });
+
+  test("creates line and stacked bar geometry", () => {
+    expect(chartPolylinePoints([0, 5, 10], 100, 50, 10)).toBe("8,42 50,25 92,8");
+    expect(chartStackedBarRects([
+      { points: [5] },
+      { points: [5] },
+    ], 100, 50, 10)).toEqual([
+      { x: 9.5, y: 25, width: 81, height: 17, seriesIndex: 0, bucketIndex: 0 },
+      { x: 9.5, y: 8, width: 81, height: 17, seriesIndex: 1, bucketIndex: 0 },
+    ]);
+  });
+
+  test("formats companion token values as integer SI units", () => {
+    expect([999, 1_000, 999_600, 1_634_303, 333_400_000, 12_300_000_000].map(formatCompanionTokens)).toEqual([
+      "999", "1K", "1M", "2M", "333M", "12B",
+    ]);
+  });
+
+  test("groups companion models by descending totals with alphabetical ties", () => {
+    expect(groupCompanionModels(
+      ["openai/gpt-4", "anthropic/claude", "openai/gpt-5", "local"],
+      new Map([
+        ["openai/gpt-4", 5],
+        ["anthropic/claude", 10],
+        ["openai/gpt-5", 5],
+      ]),
+    )).toEqual([
+      { provider: "anthropic", models: [{ id: "anthropic/claude", total: 10 }], total: 10 },
+      { provider: "openai", models: [{ id: "openai/gpt-4", total: 5 }, { id: "openai/gpt-5", total: 5 }], total: 10 },
+      { provider: "local", models: [{ id: "local", total: 0 }], total: 0 },
+    ]);
+  });
+
+  test("keeps known totals for models absent from the current timeline", () => {
+    expect(groupCompanionModels(
+      ["openai/gpt-4", "anthropic/claude"],
+      new Map([["openai/gpt-4", 10]]),
+    )).toEqual([
+      { provider: "openai", models: [{ id: "openai/gpt-4", total: 10 }], total: 10 },
+      { provider: "anthropic", models: [{ id: "anthropic/claude", total: 0 }], total: 0 },
+    ]);
+  });
+
+  test("toggles mixed groups and collapses all-selected state to null", () => {
+    const available = ["openai/gpt-4", "openai/gpt-5", "anthropic/claude"];
+    expect(toggleCompanionModels(["openai/gpt-4"], available, ["openai/gpt-5"], true)).toEqual(["openai/gpt-4", "openai/gpt-5"]);
+    expect(toggleCompanionModels(["openai/gpt-4", "openai/gpt-5"], available, ["anthropic/claude"], true)).toBeNull();
+  });
+});
diff --git a/gui/tests/usage-custom-range.test.tsx b/gui/tests/usage-custom-range.test.tsx
index 3ef6373ccfe..80bdbf23714 100644
--- a/gui/tests/usage-custom-range.test.tsx
+++ b/gui/tests/usage-custom-range.test.tsx
@@ -4,6 +4,7 @@ import { resolve } from "node:path";
 import { act } from "react";
 import type { Root } from "react-dom/client";
 import { LanguageProvider } from "../src/i18n/provider";
+import { en } from "../src/i18n/en";
 import { clearClientResourceStoresForTests } from "../src/client-resource";
 import Usage from "../src/pages/Usage";
 
@@ -81,6 +82,83 @@ function report(gate: RequestGate, marker: string, date = "2020-09-15") {
   };
 }
 
+test("Usage model table renders cache breakdown and marks unavailable telemetry", async () => {
+  await mount();
+  const data = report(requests[0], "cache-model");
+  data.models = [
+    {
+      ...data.models[0]!,
+      model: "cache-model",
+      totalTokens: 1_120,
+      inputTokens: 1_000,
+      outputTokens: 120,
+      cachedInputTokens: 600,
+      cacheReadInputTokens: 600,
+      cacheCreationInputTokens: 100,
+      cacheHitRate: 0.6,
+      cacheObservedInputTokens: 1_000,
+    },
+    {
+      ...data.models[0]!,
+      model: "partial-cache-model",
+      totalTokens: 1_000,
+      inputTokens: 1_000,
+      outputTokens: 0,
+      cachedInputTokens: 450,
+      cacheReadInputTokens: 450,
+      cacheCreationInputTokens: 0,
+      cacheHitRate: 0.9,
+      cacheObservedInputTokens: 500,
+    },
+    {
+      ...data.models[0]!,
+      model: "unknown-cache-model",
+      totalTokens: 110,
+      inputTokens: 100,
+      outputTokens: 10,
+    },
+  ];
+  await act(async () => { requests[0]!.resolve(Response.json(data)); });
+
+  const table = container.querySelector<HTMLElement>("#usage-section-models table");
+  expect(table).not.toBeNull();
+  // Header labels come from the catalog the page renders, so a copy change stays a
+  // one-place edit and this case keeps asserting the column ORDER it cares about --
+  // identity, then the three comparison figures, then the per-request detail with the
+  // five cache columns last.
+  expect([...table!.querySelectorAll("thead th")].map(cell => cell.textContent?.trim())).toEqual([
+    "logs.col.model", "logs.col.provider", "usage.col.share", "usage.col.tokens",
+    "usage.col.apiListPrice", "usage.col.requests", "usage.col.measured",
+    "usage.col.inputTokens", "usage.col.outputTokens", "usage.col.cacheHits",
+    "usage.col.cacheWrites", "usage.col.cacheHitRate",
+  ].map(key => en[key as keyof typeof en]));
+  const rows = table!.querySelectorAll("tbody tr");
+  expect(rows).toHaveLength(3);
+  const cells = (row: Element) => [...row.querySelectorAll("td")].map(cell => cell.textContent?.trim());
+  // The hit-rate cell carries the rate and, when coverage is partial or absent, the same
+  // sentence twice over: a `title` for a pointer and an `sr-only` span for everyone else.
+  const hitRateCell = (row: Element) => row.querySelectorAll("td")[11]!;
+  const hitRate = (row: Element) => hitRateCell(row).querySelector(".usage-hit-rate")?.textContent?.trim();
+  const coverageNote = (row: Element) => hitRateCell(row).querySelector(".sr-only")?.textContent ?? null;
+  expect(cells(rows[0]!).slice(7, 11)).toEqual(["1000", "120", "600", "100"]);
+  expect(hitRate(rows[0]!)).toBe("60%");
+  // A row whose cache detail covers its whole input needs no coverage caveat.
+  expect(hitRateCell(rows[0]!).getAttribute("title")).toBeNull();
+  expect(coverageNote(rows[0]!)).toBeNull();
+  // Half this row's input never reported cache detail. The rate is still an average over the
+  // half that did, so it is reported with its coverage rather than withheld.
+  const partialNote = en["usage.cacheHitRate.partial"].replace("{measured}", "500").replace("{total}", "1000");
+  expect(cells(rows[1]!).slice(9, 11)).toEqual(["450", "0"]);
+  expect(hitRate(rows[1]!)).toBe("90%");
+  expect(hitRateCell(rows[1]!).getAttribute("title")).toBe(partialNote);
+  expect(coverageNote(rows[1]!)).toBe(partialNote);
+  // Nothing in this row reported cache detail at all, which is the one case with no basis.
+  expect(cells(rows[2]!).slice(9, 11)).toEqual(["—", "—"]);
+  expect(hitRate(rows[2]!)).toBe("—");
+  expect(hitRateCell(rows[2]!).getAttribute("title")).toBe(en["usage.cacheHitRate.unmeasured"]);
+  expect(coverageNote(rows[2]!)).toBe(en["usage.cacheHitRate.unmeasured"]);
+});
+
 async function respond(index: number, marker: string, date?: string) {
   await act(async () => { requests[index].resolve(Response.json(report(requests[index], marker, date))); });
 }
diff --git a/gui/tests/usage-layout.test.ts b/gui/tests/usage-layout.test.ts
index c7d4cecd604..fb9a57356ad 100644
--- a/gui/tests/usage-layout.test.ts
+++ b/gui/tests/usage-layout.test.ts
@@ -34,6 +34,30 @@ test("Usage renders every section in one scrollable column with a sticky strip",
   expect(css).toContain("position: sticky");
 });
 
+test("the usage models table scrolls sideways with model and provider pinned", async () => {
+  const page = await Bun.file(new URL("../src/pages/Usage.tsx", import.meta.url)).text();
+  const css = await Bun.file(new URL("../src/styles-usage-workspace.css", import.meta.url)).text();
+
+  // The table opts into the rules below by class. Without it `.tbl`'s `width: 100%` divides the
+  // shell across every column until an eight-digit token total folds onto a second line.
+  expect(page).toContain('className="tbl usage-models-tbl"');
+  // Doubled selector on purpose: this file is `@import`ed from the top of `styles.css`, so a
+  // single class ties `.tbl { width: 100% }` and loses to it on source order.
+  expect(css).toMatch(/\.tbl\.usage-models-tbl \{[^}]*width: max-content/);
+  // Model and provider stay readable while the numbers scroll under them. The offsets are one
+  // scrollport padding step negative so a stuck cell repaints the strip it slides over.
+  expect(css).toMatch(/\.tbl\.usage-models-tbl td:nth-child\(2\) \{\s*position: sticky/);
+  expect(css).not.toMatch(/^\.usage-models-tbl/m);
+  expect(css).toContain("left: calc(-1 * var(--space-3));");
+  expect(css).toContain("left: calc(var(--usage-models-model-col) - var(--space-3));");
+  // `--hover` is a 3% overlay, so a pinned cell that takes it as its whole background turns
+  // nearly transparent and the scrolled columns read through it.
+  expect(css).toContain("background: linear-gradient(var(--hover), var(--hover)), var(--surface);");
+  // The excluded-request caption is a line under the amount, not a wrap of the same line.
+  expect(page).toContain("usage-cost-note");
+  expect(css).toMatch(/\.usage-cost-note \{[^}]*display: block/);
+});
+
 test("connected Usage defaults to the exact machine key and can toggle hub-wide without local fallback", async () => {
   const src = await Bun.file(new URL("../src/pages/Usage.tsx", import.meta.url)).text();
   expect(src).toContain('useState<UsageScope>("machine")');
diff --git a/package.json b/package.json
index ed4bb03a82a..cfabb4378af 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.60.0",
+  "version": "2.61.0",
   "description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",
@@ -49,6 +49,8 @@
     "typecheck": "bun x tsc --noEmit",
     "audit:high": "bun audit --audit-level=high && cd gui && bun audit --audit-level=high",
     "privacy:scan": "bun scripts/privacy-scan.ts",
+    "favicons": "bun scripts/brand-favicons.ts",
+    "favicons:check": "bun scripts/brand-favicons.ts --check",
     "skill:surface": "bun scripts/generate-ocx-skill-surface.ts",
     "skill:surface:check": "bun scripts/generate-ocx-skill-surface.ts --check",
     "structure:index": "bun scripts/structure-ssot.ts --fix",
@@ -58,6 +60,8 @@
     "build:gui": "cd gui && bun install --frozen-lockfile && bun run build && cd .. && bun run prepare:package",
     "build:remote-workspace-helper": "cargo build --release --locked --manifest-path native/remote-workspace-helper/Cargo.toml",
     "test:remote-workspace-helper": "cargo test --locked --manifest-path native/remote-workspace-helper/Cargo.toml",
+    "build:standalone": "bun scripts/build-standalone.ts",
+    "test:macos": "swift run --package-path app MenuBarCoreTests",
     "prepare:package": "bun scripts/prepare-package.ts",
     "prepack": "bun run prepare:package",
     "prepublishOnly": "bun run audit:high && bun run typecheck && bun run build:gui",
diff --git a/readme/README.fr.md b/readme/README.fr.md
index 160acfb908d..be965be6d9a 100644
--- a/readme/README.fr.md
+++ b/readme/README.fr.md
@@ -92,7 +92,37 @@ Ouvrez **http://localhost:10100** et configurez tout dans le tableau de bord web
 fournisseurs (plus de 40 intégrés, ou n'importe quel point de terminaison compatible OpenAI),
 choisissez les modèles, gérez les comptes. `ocx gui`
 rouvre le tableau de bord à tout moment.
-Il peut également gérer un **groupe de comptes ChatGPT** pour l'authentification Codex. Ajoutez plusieurs
+
+<details>
+<summary><b>Application de bureau et widget macOS — bêta</b></summary>
+
+Une application native qui reprend le même tableau de bord, accompagnée d’une extension WidgetKit qui
+affiche l’état du proxy, l’utilisation du jour et les quotas des fournisseurs sans ouvrir de
+navigateur. Le proxy ne change pas : l’application détecte une instance en cours d’exécution ou
+démarre le sidecar `ocx` inclus, tandis que le tableau de bord reste accessible à l’adresse
+**http://localhost:10100**.
+
+Cette version est en bêta. Les versions distribuées sont signées pour en garantir l’intégrité, mais ne sont pas
+notariées : macOS demande donc un clic droit → **Ouvrir** au premier lancement, et Windows
+SmartScreen affiche un avertissement pour le programme d’installation. Le widget nécessite macOS 14
+ou une version ultérieure ; le modèle de données des instantanés qu’il affiche se trouve dans [`app/`](../app)
+(`MenuBarCore`).
+
+Téléchargez l’application depuis la [dernière version publiée](https://github.com/lidge-jun/opencodex/releases),
+ou compilez-la localement avec
+`bun run prepare-sidecar && bun run prepare-widget && bunx tauri build`.
+
+Les emplacements d’installation, les fichiers de service et tous les autres éléments écrits sur le
+disque sont répertoriés dans [`AGENTS_INSTALL.md`](../AGENTS_INSTALL.md#where-things-are-installed).
+Le [guide de l’application de bureau](https://lidge-jun.github.io/opencodex/guides/desktop-app/) et le
+[guide de l’application macOS dans la barre des menus](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)
+détaillent l’installation sur chaque plateforme et le message de Gatekeeper.
+
+</details>
+
+### Groupe de comptes ChatGPT
+
+opencodex peut également gérer un **groupe de comptes ChatGPT** pour l'authentification Codex. Ajoutez plusieurs
 comptes ChatGPT / Codex et actualisez leurs quotas 5 h / hebdomadaires / 30 j dans le tableau de bord.
 Avec le routage par quota, les nouvelles sessions peuvent utiliser le compte opérationnel le moins sollicité ;
 les modes round-robin et fill-first appliquent leurs propres politiques. Les fils Codex existants restent
diff --git a/readme/README.ja.md b/readme/README.ja.md
index 415d5c9674d..9d32a7bfc7f 100644
--- a/readme/README.ja.md
+++ b/readme/README.ja.md
@@ -90,14 +90,41 @@ ocx start                         # プロキシとダッシュボードが loca
 **http://localhost:10100** を開き、Web ダッシュボードですべて設定します。プロバイダーの追加（40 以上の
 組み込み、または任意の OpenAI 互換エンドポイント）、モデルの選択、アカウントの管理はここで行います。
 `ocx gui` でいつでもダッシュボードを開き直せます。
-Codex 認証用の **ChatGPT アカウントプール**も管理できます。ChatGPT / Codex のアカウントを複数追加し、
-5 時間 / 週間 / 30 日のクォータをダッシュボードで更新します。クォータルーティングでは、新しいセッション
-が使用量の最も少ない健全なアカウントを使えます。ラウンドロビンと fill-first はそれぞれの方針に従います。
-既存の Codex スレッドは通常、開始したアカウントとの affinity を保つので、長い SSH・tmux・モバイル接続
-のセッションが会話の途中でアカウントを乗り換えることはありません。ただしクォータの再評価、failover、
-アカウントの除外、affinity の失効、401/403 や 429 からの復帰では再バインドされることがあります。ふだん
-は使わず他が尽きたときだけ回したいアカウント（多くは Codex Desktop のログイン）があるなら、アカウント
-に選択順を指定してください。
+
+<details>
+<summary><b>デスクトップアプリと macOS ウィジェット — ベータ版</b></summary>
+
+同じダッシュボードを包むネイティブアプリに、ブラウザーを開かなくてもプロキシの状態、今日の使用量、
+プロバイダーのクォータを確認できる WidgetKit 拡張を加えたものです。プロキシ自体は変わりません。アプリは
+起動中のプロキシを見つけるか、同梱の `ocx` サイドカーを起動し、ダッシュボードは引き続き
+**http://localhost:10100** で開きます。
+
+現在はベータ版です。ビルドは改ざん検知のため署名されていますが公証はされていないため、macOS では
+初回起動時に右クリックして「開く」を選ぶ必要があり、Windows ではインストーラーに SmartScreen の警告が
+表示されます。ウィジェットには macOS 14 以降が必要です。表示に使うスナップショットモデルは
+[`app/`](../app)（`MenuBarCore`）にあります。
+
+[最新リリース](https://github.com/lidge-jun/opencodex/releases)からダウンロードするか、
+`bun run prepare-sidecar && bun run prepare-widget && bunx tauri build` でローカルビルドできます。
+
+インストール先、サービスファイルなどディスクに書き込まれるものは
+[`AGENTS_INSTALL.md`](../AGENTS_INSTALL.md#where-things-are-installed) にまとめています。
+[デスクトップアプリガイド](https://lidge-jun.github.io/opencodex/guides/desktop-app/)と
+[macOS メニューバーアプリガイド](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)では、
+プラットフォーム別のインストール手順と Gatekeeper の確認画面を説明しています。
+
+</details>
+
+### ChatGPT アカウントプール
+
+opencodex では、Codex 認証用の **ChatGPT アカウントプール**も管理できます。ChatGPT / Codex のアカウントを
+複数追加し、5 時間 / 週間 / 30 日のクォータをダッシュボードで更新します。クォータルーティングでは、新しい
+セッションが使用量の最も少ない健全なアカウントを使えます。ラウンドロビンと fill-first はそれぞれの方針に
+従います。既存の Codex スレッドは通常、開始したアカウントとの affinity を保つので、長い SSH・tmux・
+モバイル接続のセッションが会話の途中でアカウントを乗り換えることはありません。ただしクォータの再評価、
+failover、アカウントの除外、affinity の失効、401/403 や 429 からの復帰では再バインドされることがあります。
+ふだんは使わず他が尽きたときだけ回したいアカウント（多くは Codex Desktop のログイン）があるなら、
+アカウントに選択順を指定してください。
 
 ### スポンサー
 
diff --git a/readme/README.ko.md b/readme/README.ko.md
index f4c44f121c6..1dc97b5b1fc 100644
--- a/readme/README.ko.md
+++ b/readme/README.ko.md
@@ -89,12 +89,38 @@ ocx start                         # 프록시 + 대시보드: localhost:10100
 
 **http://localhost:10100**을 열고 웹 대시보드에서 전부 설정하세요. 프로바이더 추가(내장 40개 이상,
 또는 OpenAI 호환 엔드포인트), 모델 선택, 계정 관리까지 모두 여기서 합니다. `ocx gui`로 대시보드를 언제든 다시 엽니다.
-Codex 인증용 **ChatGPT 계정 풀**도 관리합니다. ChatGPT / Codex 계정을 여러 개 넣고, 대시보드에서
-5시간 / 주간 / 30일 쿼터를 갱신합니다. 쿼터 라우팅을 켜면 새 세션은 사용량이 가장 적은 정상 계정을 쓰고,
-round-robin과 fill-first는 각자 정책을 따릅니다. 기존 Codex 스레드는 기본적으로 시작한 계정에 붙어
-있어서, 긴 SSH·tmux·모바일 세션이 대화 도중에 계정을 바꾸지 않습니다. 다만 쿼터 재평가, failover,
-계정 제외, affinity 만료, 401/403·429 복구가 일어나면 다시 묶일 수 있습니다. Codex Desktop 로그인처럼
-다른 계정이 소진된 뒤에만 쓰고 싶은 계정이 있으면, 계정에 선택 순서를 지정하세요.
+
+<details>
+<summary><b>데스크톱 앱과 macOS 위젯 — 베타</b></summary>
+
+같은 대시보드를 감싼 네이티브 앱과, 브라우저를 열지 않고 프록시 상태·오늘의 사용량·프로바이더
+쿼터를 보여 주는 WidgetKit 확장입니다. 프록시 자체는 그대로입니다. 앱은 실행 중인 프록시를 찾거나
+번들된 `ocx` 사이드카를 시작하며, 대시보드는 계속 **http://localhost:10100**에서 열립니다.
+
+현재 베타 버전입니다. 빌드는 무결성을 확인할 수 있도록 서명되어 있지만 공증되지는 않았습니다.
+따라서 macOS에서는 처음 실행할 때 마우스 오른쪽 버튼을 클릭한 뒤 **열기**를 선택해야 하고,
+Windows 설치 파일에는 SmartScreen 경고가 표시됩니다. 위젯은 macOS 14 이상에서 쓸 수 있으며,
+위젯이 그리는 스냅샷 모델은 [`app/`](../app)의 `MenuBarCore`에 있습니다.
+
+[최신 릴리스](https://github.com/lidge-jun/opencodex/releases)에서 다운로드하거나
+`bun run prepare-sidecar && bun run prepare-widget && bunx tauri build`로 직접 빌드하세요.
+
+설치 위치, 서비스 파일을 비롯해 디스크에 쓰는 항목은
+[`AGENTS_INSTALL.md`](../AGENTS_INSTALL.md#where-things-are-installed)에 정리되어 있습니다.
+[데스크톱 앱 가이드](https://lidge-jun.github.io/opencodex/guides/desktop-app/)와
+[macOS 메뉴 막대 앱 가이드](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)에서
+플랫폼별 설치 방법과 Gatekeeper 안내를 확인할 수 있습니다.
+
+</details>
+
+### ChatGPT 계정 풀
+
+opencodex는 Codex 인증용 **ChatGPT 계정 풀**도 관리합니다. ChatGPT / Codex 계정을 여러 개 넣고,
+대시보드에서 5시간 / 주간 / 30일 쿼터를 갱신합니다. 쿼터 라우팅을 켜면 새 세션은 사용량이 가장 적은
+정상 계정을 쓰고, round-robin과 fill-first는 각자 정책을 따릅니다. 기존 Codex 스레드는 기본적으로
+시작한 계정에 붙어 있어서 긴 SSH·tmux·모바일 세션이 대화 도중에 계정을 바꾸지 않습니다. 다만 쿼터
+재평가, failover, 계정 제외, affinity 만료, 401/403·429 복구가 일어나면 다시 묶일 수 있습니다.
+Codex Desktop 로그인처럼 다른 계정이 소진된 뒤에만 쓰고 싶은 계정이 있으면 계정에 선택 순서를 지정하세요.
 
 ### 스폰서
 
diff --git a/readme/README.ru.md b/readme/README.ru.md
index e654f571a93..e12ab125df8 100644
--- a/readme/README.ru.md
+++ b/readme/README.ru.md
@@ -92,7 +92,34 @@ ocx start                         # прокси + панель управлен
 Откройте **http://localhost:10100** и настройте всё в веб-панели: добавьте провайдеров
 (40+ встроенных или любой OpenAI-совместимый endpoint), выберите модели, управляйте
 аккаунтами. `ocx gui` в любой момент снова откроет панель.
-Кроме того, он умеет управлять **пулом аккаунтов ChatGPT** для аутентификации Codex. Добавьте
+
+<details>
+<summary><b>Настольное приложение и виджет macOS — бета-версия</b></summary>
+
+Это нативная оболочка вокруг той же панели управления с расширением WidgetKit, которое
+показывает состояние прокси, расход за сегодня и квоты провайдеров без открытия браузера.
+Сам прокси не меняется: приложение находит уже запущенный экземпляр либо запускает встроенный
+сайдкар `ocx`, а панель по-прежнему доступна по адресу **http://localhost:10100**.
+
+Это бета-версия. Сборки подписаны для проверки целостности, но не нотариализованы, поэтому
+при первом запуске macOS просит нажать правой кнопкой мыши и выбрать **«Открыть»**, а Windows
+SmartScreen предупреждает об установщике. Для виджета нужна macOS 14 или новее; его модель
+снимков находится в [`app/`](../app) (`MenuBarCore`).
+
+Скачайте приложение из [последнего релиза](https://github.com/lidge-jun/opencodex/releases) или
+соберите локально командой `bun run prepare-sidecar && bun run prepare-widget && bunx tauri build`.
+
+Пути установки, файлы служб и всё остальное, что записывается на диск, перечислены в
+[`AGENTS_INSTALL.md`](../AGENTS_INSTALL.md#where-things-are-installed). В
+[руководстве по настольному приложению](https://lidge-jun.github.io/opencodex/guides/desktop-app/) и
+[руководстве по приложению macOS в строке меню](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)
+описаны установка на каждой платформе и запрос Gatekeeper.
+
+</details>
+
+### Пул аккаунтов ChatGPT
+
+opencodex также умеет управлять **пулом аккаунтов ChatGPT** для аутентификации Codex. Добавьте
 несколько аккаунтов ChatGPT / Codex и обновляйте их квоты за 5 ч / неделю / 30 дней в панели.
 При маршрутизации по квоте новые сессии могут использовать работоспособный аккаунт с наименьшим
 использованием; round-robin и fill-first применяют свои политики. Существующие треды Codex
diff --git a/readme/README.tr.md b/readme/README.tr.md
index 998338d8760..083e8e46370 100644
--- a/readme/README.tr.md
+++ b/readme/README.tr.md
@@ -90,14 +90,42 @@ Arka planda çalıştırmak için `ocx service` kullanın.
 **http://localhost:10100** adresini açın ve her şeyi web kontrol panelinden yapılandırın: sağlayıcı
 ekleyin (40'tan fazla hazır sağlayıcı ya da herhangi bir OpenAI uyumlu uç nokta), model seçin, hesap
 yönetin. `ocx gui` paneli istediğiniz zaman yeniden açar.
-Codex kimlik doğrulaması için bir **ChatGPT hesap havuzu** da yönetebilir. Birden fazla ChatGPT / Codex
-hesabı ekleyin, 5 saatlik / haftalık / 30 günlük kotalarını panelden tazeleyin. Kota yönlendirmesinde
-yeni oturumlar en az kullanılan sağlıklı hesabı kullanabilir; round-robin ve fill-first kendi
-politikalarını izler. Mevcut Codex dizileri normalde onları başlatan hesaba bağlı kalır, böylece uzun
-SSH, tmux ya da mobil oturumlar konuşmanın ortasında hesap değiştirmez — ancak kota yeniden
-değerlendirmesi, failover, hesabın devre dışı bırakılması, bağlılığın süresinin dolması ya da 401/403 ve
-429 toparlanması bu bağı yeniden kurabilir. Yalnızca diğerleri tükendiğinde kullanılmasını istediğiniz
-bir hesap varsa — genellikle Codex Desktop girişiniz — hesaplara bir seçim sırası verin.
+
+<details>
+<summary><b>Masaüstü uygulaması ve macOS widget'ı — beta</b></summary>
+
+Aynı kontrol panelini sarmalayan yerel uygulamaya ek olarak, tarayıcı açmadan proxy durumunu,
+bugünkü kullanımı ve sağlayıcı kotalarını gösteren bir WidgetKit uzantısı sunulur. Proxy'nin çalışma
+şekli değişmez: uygulama çalışan bir proxy bulur ya da paketlenmiş `ocx` sidecar'ını başlatır;
+kontrol paneli yine **http://localhost:10100** adresinde kalır.
+
+Bu bir beta sürümüdür. Derlemeler bütünlük için imzalanır ancak noter tasdikli değildir; bu nedenle
+macOS ilk açılışta sağ tıklayıp **Aç**'ı seçmenizi ister, Windows SmartScreen ise yükleyici için uyarı
+gösterir. Widget için macOS 14 veya üzeri gerekir; görüntülediği anlık görüntü modeli
+[`app/`](../app) dizinindedir (`MenuBarCore`).
+
+Uygulamayı [en güncel sürümden](https://github.com/lidge-jun/opencodex/releases) indirin veya
+`bun run prepare-sidecar && bun run prepare-widget && bunx tauri build` komutuyla yerel olarak derleyin.
+
+Kurulum konumları, servis dosyaları ve diske yazılan diğer her şey
+[`AGENTS_INSTALL.md`](../AGENTS_INSTALL.md#where-things-are-installed) dosyasında listelenir.
+[Masaüstü uygulaması kılavuzu](https://lidge-jun.github.io/opencodex/guides/desktop-app/) ve
+[macOS menü çubuğu uygulaması kılavuzu](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/),
+platforma göre kurulumu ve Gatekeeper istemini açıklar.
+
+</details>
+
+### ChatGPT hesap havuzu
+
+opencodex, Codex kimlik doğrulaması için bir **ChatGPT hesap havuzu** da yönetebilir. Birden fazla
+ChatGPT / Codex hesabı ekleyin, 5 saatlik / haftalık / 30 günlük kotalarını panelden tazeleyin. Kota
+yönlendirmesinde yeni oturumlar en az kullanılan sağlıklı hesabı kullanabilir; round-robin ve
+fill-first kendi politikalarını izler. Mevcut Codex dizileri normalde onları başlatan hesaba bağlı
+kalır, böylece uzun SSH, tmux ya da mobil oturumlar konuşmanın ortasında hesap değiştirmez — ancak
+kota yeniden değerlendirmesi, failover, hesabın devre dışı bırakılması, bağlılığın süresinin dolması
+ya da 401/403 ve 429 toparlanması bu bağı yeniden kurabilir. Yalnızca diğerleri tükendiğinde
+kullanılmasını istediğiniz bir hesap varsa — genellikle Codex Desktop girişiniz — hesaplara bir seçim
+sırası verin.
 
 ### Sponsorlar
 
diff --git a/readme/README.zh-CN.md b/readme/README.zh-CN.md
index 79392708a13..e4cd96d518e 100644
--- a/readme/README.zh-CN.md
+++ b/readme/README.zh-CN.md
@@ -89,7 +89,33 @@ ocx start                         # 代理 + 仪表板：localhost:10100
 打开 **http://localhost:10100**，在 Web 仪表板中完成所有配置 —— 添加提供商
 （40 多个内置，或任意 OpenAI 兼容端点）、选择模型、管理账户。随时运行 `ocx gui`
 可重新打开仪表板。
-它还能为 Codex 认证管理一个 **ChatGPT 账户池**。添加多个 ChatGPT / Codex 账户，
+
+<details>
+<summary><b>桌面应用与 macOS 小组件 —— 测试版</b></summary>
+
+它是同一套仪表板的原生外壳，另带 WidgetKit 扩展，无需打开浏览器即可查看代理状态、
+今日用量和提供商配额。代理本身没有变化：应用会连接已在运行的代理；若未发现，
+则启动内置的 `ocx` sidecar。仪表板仍位于 **http://localhost:10100**。
+
+桌面应用目前仍处于测试阶段。构建已签名以保障完整性，但尚未公证，因此 macOS
+首次启动时需要右键点击并选择“打开”，Windows SmartScreen 也会对安装程序发出警告。
+小组件需要 macOS 14 或更高版本；它所呈现的快照模型位于 [`app/`](../app)
+（`MenuBarCore`）。
+
+请从[最新发布版本](https://github.com/lidge-jun/opencodex/releases)下载，或使用
+`bun run prepare-sidecar && bun run prepare-widget && bunx tauri build` 在本地构建。
+
+安装位置、服务文件以及写入磁盘的其他内容均列在
+[`AGENTS_INSTALL.md`](../AGENTS_INSTALL.md#where-things-are-installed) 中。
+[桌面应用指南](https://lidge-jun.github.io/opencodex/guides/desktop-app/)和
+[macOS 菜单栏应用指南](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)
+介绍了各平台的安装方式和 Gatekeeper 提示。
+
+</details>
+
+### ChatGPT 账户池
+
+opencodex 还能为 Codex 认证管理一个 **ChatGPT 账户池**。添加多个 ChatGPT / Codex 账户，
 在仪表板中刷新它们的 5 小时 / 每周 / 30 天配额。在配额路由下，新会话可以使用
 使用量最低的健康账户；round-robin 和 fill-first 则各自使用自己的策略。现有 Codex
 线程通常会保持对启动它的账户的亲和性，因此长时间的 SSH、tmux 或移动端连接的会话
diff --git a/readme/README.zh-TW.md b/readme/README.zh-TW.md
index 6a25aae4d15..70b0cae1276 100644
--- a/readme/README.zh-TW.md
+++ b/readme/README.zh-TW.md
@@ -88,7 +88,32 @@ ocx start                         # 代理 + 儀表板位於 localhost:10100
 開啟 **http://localhost:10100**，在網頁儀表板完成所有設定——新增供應商
 （40+ 內建，或任何 OpenAI 相容端點）、挑選模型、管理帳號。隨時可用 `ocx gui`
 重新開啟儀表板。
-它也能為 Codex 認證管理 **ChatGPT 帳號池**。新增多個 ChatGPT / Codex 帳號，
+
+<details>
+<summary><b>桌面應用程式與 macOS 小工具——Beta 版</b></summary>
+
+它是同一套儀表板的原生外殼，另附 WidgetKit 擴充套件，無需開啟瀏覽器就能查看代理狀態、
+今日用量與供應商配額。代理本身沒有改變：應用程式會尋找正在執行的代理，找不到便啟動隨附的
+`ocx` sidecar；儀表板仍位於 **http://localhost:10100**。
+
+目前仍是 Beta 版。建置會簽章以確保完整性，但尚未經公證，因此 macOS 在首次啟動時需要按右鍵 → **開啟**，
+Windows SmartScreen 則會對安裝程式顯示警告。小工具需要 macOS 14 或更新版本；它所呈現的快照模型位於
+[`app/`](../app)（`MenuBarCore`）。
+
+請從[最新發行版](https://github.com/lidge-jun/opencodex/releases)下載，或使用
+`bun run prepare-sidecar && bun run prepare-widget && bunx tauri build` 在本機建置。
+
+安裝位置、服務檔案，以及其他寫入磁碟的內容，都列在
+[`AGENTS_INSTALL.md`](../AGENTS_INSTALL.md#where-things-are-installed)。
+[桌面應用程式指南](https://lidge-jun.github.io/opencodex/guides/desktop-app/) 與
+[macOS 選單列應用程式指南](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)
+說明各平台的安裝方式與 Gatekeeper 提示。
+
+</details>
+
+### ChatGPT 帳號池
+
+opencodex 也能為 Codex 認證管理 **ChatGPT 帳號池**。新增多個 ChatGPT / Codex 帳號，
 在儀表板重新整理 5 小時／每週／30 天配額。在配額路由下，新會話可使用
 使用量最低的健康帳號；round-robin 與 fill-first 則各自套用自己的策略。既有 Codex
 執行緒通常會維持對啟動帳號的親和性，因此長時間的 SSH、tmux 或
diff --git a/readme/i18n-manifest.json b/readme/i18n-manifest.json
index d64870cad2c..1bdee0719bc 100644
--- a/readme/i18n-manifest.json
+++ b/readme/i18n-manifest.json
@@ -6,43 +6,43 @@
       "file": "readme/README.fr.md",
       "label": "Français",
       "docsPath": "fr",
-      "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+      "sourceSha256": "10c088099257df8813301d057990780394aae922c2703337c8326c9e64a835c3"
     },
     "ko": {
       "file": "readme/README.ko.md",
       "label": "한국어",
       "docsPath": "ko",
-      "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+      "sourceSha256": "10c088099257df8813301d057990780394aae922c2703337c8326c9e64a835c3"
     },
     "zh-CN": {
       "file": "readme/README.zh-CN.md",
       "label": "简体中文",
       "docsPath": "zh-cn",
-      "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+      "sourceSha256": "10c088099257df8813301d057990780394aae922c2703337c8326c9e64a835c3"
     },
     "zh-TW": {
       "file": "readme/README.zh-TW.md",
       "label": "繁體中文",
       "docsPath": "zh-tw",
-      "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+      "sourceSha256": "10c088099257df8813301d057990780394aae922c2703337c8326c9e64a835c3"
     },
     "ru": {
       "file": "readme/README.ru.md",
       "label": "Русский",
       "docsPath": "ru",
-      "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+      "sourceSha256": "10c088099257df8813301d057990780394aae922c2703337c8326c9e64a835c3"
     },
     "ja": {
       "file": "readme/README.ja.md",
       "label": "日本語",
       "docsPath": "ja",
-      "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+      "sourceSha256": "10c088099257df8813301d057990780394aae922c2703337c8326c9e64a835c3"
     },
     "tr": {
       "file": "readme/README.tr.md",
       "label": "Türkçe",
       "docsPath": "tr",
-      "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+      "sourceSha256": "10c088099257df8813301d057990780394aae922c2703337c8326c9e64a835c3"
     }
   }
 }
diff --git a/scripts/brand-favicons.ts b/scripts/brand-favicons.ts
new file mode 100644
index 00000000000..043cbb3222e
--- /dev/null
+++ b/scripts/brand-favicons.ts
@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+/**
+ * Render the favicons the dashboard and the documentation site serve from the app icon vector.
+ *
+ * They used to be hand-made bitmaps with no source, and one of them was wrong in a way the file
+ * itself does not show: docs-site/public/favicon.png was the dark variant of the mark, white on
+ * transparency, 98.3% covered. A browser tab strip is light by default, so the documentation
+ * site's favicon was white on white. The .ico beside it carried the same artwork at 16, 32 and 48.
+ *
+ * Sizes and names here are the ones gui/index.html and docs-site/astro.config.mjs already
+ * reference, so nothing on either site has to change to pick these up.
+ *
+ * --check regenerates into a temporary directory and compares byte for byte, the same contract
+ * desktop/scripts/generate-icons.ts has for the app icon set.
+ */
+import { mkdtempSync, readFileSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildIco, render } from "./lib/icon-render";
+
+const repoRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const source = join(repoRoot, "desktop", "src-tauri", "icons", "icon.svg");
+
+/** Favicon PNGs the two sites reference, by path relative to the repository root. */
+const FAVICON_SIZES: Record<string, number> = {
+  "gui/public/favicon.png": 128,
+  "docs-site/public/favicon.png": 192,
+};
+
+/** The documentation site's .ico, which Starlight names directly, and the sizes it carries. */
+const ICO_OUTPUT = "docs-site/public/favicon.ico";
+const ICO_SIZES = [16, 32, 48];
+
+/** Scratch files are flat, so a nested output name becomes one path segment. */
+function scratchName(output: string): string {
+  return output.replaceAll("/", "__");
+}
+
+function generateInto(target: string): string[] {
+  const produced: string[] = [];
+  for (const [output, size] of Object.entries(FAVICON_SIZES)) {
+    render(size, join(target, scratchName(output)), source);
+    produced.push(output);
+  }
+
+  const parts: Array<{ size: number; bytes: Buffer }> = [];
+  for (const size of ICO_SIZES) {
+    const scratch = join(target, `.ico-${size}.png`);
+    render(size, scratch, source);
+    parts.push({ size, bytes: readFileSync(scratch) });
+    rmSync(scratch, { force: true });
+  }
+  writeFileSync(join(target, scratchName(ICO_OUTPUT)), buildIco(parts));
+  produced.push(ICO_OUTPUT);
+
+  return produced;
+}
+
+function main(): number {
+  if (!existsSync(source)) {
+    console.error(`[favicons] missing source: ${source}`);
+    return 1;
+  }
+  const check = process.argv.includes("--check");
+  const scratch = mkdtempSync(join(tmpdir(), "ocx-favicons-"));
+  try {
+    const produced = generateInto(scratch);
+    if (!check) {
+      // Written in one pass at the end, so a renderer failure part way through cannot leave one
+      // site on the new mark and the other on the old one.
+      for (const output of produced) {
+        writeFileSync(join(repoRoot, output), readFileSync(join(scratch, scratchName(output))));
+      }
+      console.log(`[favicons] regenerated ${produced.length} favicons from ${basename(source)}`);
+      return 0;
+    }
+
+    const drifted = produced.filter(output => {
+      const committed = join(repoRoot, output);
+      if (!existsSync(committed)) return true;
+      return !readFileSync(join(scratch, scratchName(output))).equals(readFileSync(committed));
+    });
+    if (drifted.length > 0) {
+      console.error(`[favicons] these do not match the app icon vector: ${drifted.join(", ")}`);
+      console.error("[favicons] regenerate with: bun run favicons");
+      return 1;
+    }
+    console.log(`[favicons] ${produced.length} favicons match the source`);
+    return 0;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+process.exit(main());
+
diff --git a/scripts/build-standalone.ts b/scripts/build-standalone.ts
new file mode 100644
index 00000000000..f75fcc32251
--- /dev/null
+++ b/scripts/build-standalone.ts
@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { isStandaloneTarget, standaloneExecutableName } from "./standalone-targets";
+
+function hostTarget(): string {
+  const platform = process.platform === "darwin" ? "darwin" : process.platform === "win32" ? "windows" : "linux";
+  const arch = process.arch === "arm64" ? "arm64" : "x64";
+  return `bun-${platform}-${arch}`;
+}
+
+function argumentValue(name: string): string | undefined {
+  const index = Bun.argv.indexOf(name);
+  return index >= 0 ? Bun.argv[index + 1] : undefined;
+}
+
+const target = argumentValue("--target") ?? hostTarget();
+if (!isStandaloneTarget(target)) {
+  throw new Error(`Unsupported standalone target: ${target}`);
+}
+
+const repoRoot = resolve(import.meta.dir, "..");
+const guiDist = join(repoRoot, "gui", "dist");
+if (!existsSync(join(guiDist, "index.html"))) {
+  throw new Error("gui/dist is missing; run `bun run build:gui` first");
+}
+
+const output = resolve(argumentValue("--out") ?? join(repoRoot, "dist", "standalone", target));
+mkdirSync(output, { recursive: true });
+const executable = join(output, standaloneExecutableName(target));
+const result = Bun.spawnSync([
+  process.execPath,
+  "build",
+  "--compile",
+  "--target",
+  target,
+  join(repoRoot, "src", "cli", "index.ts"),
+  "--outfile",
+  executable,
+], { stdout: "inherit", stderr: "inherit" });
+if (result.exitCode !== 0) process.exit(result.exitCode);
+
+cpSync(guiDist, join(output, "gui", "dist"), { recursive: true });
+const digest = createHash("sha256").update(readFileSync(executable)).digest("hex");
+writeFileSync(join(output, "SHA256SUMS"), `${digest}  ${executable.split(/[\\/]/).pop()}\n`);
+console.log(`Built ${executable}`);
diff --git a/scripts/lib/icon-render.ts b/scripts/lib/icon-render.ts
new file mode 100644
index 00000000000..89ab2783add
--- /dev/null
+++ b/scripts/lib/icon-render.ts
@@ -0,0 +1,162 @@
+/**
+ * Rendering and packing shared by the icon generators.
+ *
+ * Two generators read the same vector: desktop/scripts/generate-icons.ts builds the app icon set
+ * and the menu bar image, and scripts/brand-favicons.ts builds the favicons the dashboard and the
+ * documentation site serve. They shared nothing at first, and the PNG re-encode below is exactly
+ * the kind of detail that would have been copied and then fixed in one place only.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { deflateSync, inflateSync } from "node:zlib";
+
+export function render(size: number, out: string, from: string): void {
+  const result = spawnSync("rsvg-convert", ["-w", String(size), "-h", String(size), from, "-o", out]);
+  if (result.status !== 0) {
+    const detail = result.error?.message ?? result.stderr?.toString().trim() ?? "unknown error";
+    throw new Error(`rsvg-convert failed for ${size}px: ${detail}`);
+  }
+  writeFileSync(out, toRgba(readFileSync(out)));
+}
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+const CRC_TABLE = (() => {
+  const table = new Int32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c;
+  }
+  return table;
+})();
+
+function crc32(bytes: Buffer): number {
+  let c = -1;
+  for (const byte of bytes) c = CRC_TABLE[(c ^ byte) & 0xff]! ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+function chunk(type: string, data: Buffer): Buffer {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(data.length, 0);
+  head.write(type, 4, "latin1");
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])), 0);
+  return Buffer.concat([head, data, crc]);
+}
+
+/** Undo one PNG scanline filter in place, given the already reconstructed row above. */
+function unfilter(kind: number, row: Buffer, prior: Buffer, stride: number): void {
+  for (let i = 0; i < row.length; i += 1) {
+    const a = i >= stride ? row[i - stride]! : 0;
+    const b = prior[i]!;
+    const c = i >= stride ? prior[i - stride]! : 0;
+    let add = 0;
+    if (kind === 1) add = a;
+    else if (kind === 2) add = b;
+    else if (kind === 3) add = (a + b) >> 1;
+    else if (kind === 4) {
+      const p = a + b - c;
+      const pa = Math.abs(p - a);
+      const pb = Math.abs(p - b);
+      const pc = Math.abs(p - c);
+      add = pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+    } else if (kind !== 0) throw new Error(`unknown PNG filter ${kind}`);
+    row[i] = (row[i]! + add) & 0xff;
+  }
+}
+
+/**
+ * Re-encode an 8-bit truecolour PNG as truecolour-with-alpha, and leave one that already has
+ * alpha untouched.
+ *
+ * This exists because the icon has an opaque backdrop. librsvg notices that nothing in the render
+ * is transparent and drops the alpha channel, which is a valid PNG and a broken icon: Tauri's
+ * `generate_context!` rejects a window icon that is not RGBA, so `bun run build` fails at
+ * compile time with "icon ... is not RGBA". Leaving that to the renderer would also make the
+ * committed bytes depend on which librsvg drew them.
+ */
+export function toRgba(bytes: Buffer): Buffer {
+  if (!bytes.subarray(0, 8).equals(PNG_SIGNATURE)) throw new Error("rsvg-convert did not emit a PNG");
+
+  let header: { width: number; height: number } | null = null;
+  let colourType = -1;
+  const idat: Buffer[] = [];
+  for (let at = 8; at + 8 <= bytes.length; ) {
+    const length = bytes.readUInt32BE(at);
+    const type = bytes.subarray(at + 4, at + 8).toString("latin1");
+    const data = bytes.subarray(at + 8, at + 8 + length);
+    if (type === "IHDR") {
+      colourType = data[9]!;
+      if (data[8] !== 8 || data[12] !== 0) throw new Error("PNG is not 8-bit non-interlaced");
+      header = { width: data.readUInt32BE(0), height: data.readUInt32BE(4) };
+    } else if (type === "IDAT") idat.push(Buffer.from(data));
+    else if (type === "IEND") break;
+    at += 12 + length;
+  }
+  if (colourType === 6) return bytes;
+  if (colourType !== 2 || header === null) throw new Error(`unexpected PNG colour type ${colourType}`);
+
+  const { width, height } = header;
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * 3;
+  const out = Buffer.alloc(height * (1 + width * 4));
+  let prior = Buffer.alloc(stride);
+  for (let y = 0; y < height; y += 1) {
+    const start = y * (1 + stride);
+    const row = Buffer.from(raw.subarray(start + 1, start + 1 + stride));
+    unfilter(raw[start]!, row, prior, 3);
+    const target = y * (1 + width * 4);
+    out[target] = 0;
+    for (let x = 0; x < width; x += 1) {
+      row.copy(out, target + 1 + x * 4, x * 3, x * 3 + 3);
+      out[target + 1 + x * 4 + 3] = 0xff;
+    }
+    prior = row;
+  }
+
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  return Buffer.concat([
+    PNG_SIGNATURE,
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(out, { level: 9 })),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+/**
+ * Pack PNGs into an ICO.
+ *
+ * Written here rather than shelled out because the alternative is ImageMagick, and adding a
+ * system dependency to regenerate an icon is a worse trade than 30 lines of a container format
+ * that has not changed in decades. A 256px entry records its dimension as 0, which is how ICO
+ * spells "256".
+ */
+export function buildIco(entries: Array<{ size: number; bytes: Buffer }>): Buffer {
+  const header = Buffer.alloc(6);
+  header.writeUInt16LE(0, 0); // reserved
+  header.writeUInt16LE(1, 2); // type: icon
+  header.writeUInt16LE(entries.length, 4);
+
+  const directory = Buffer.alloc(16 * entries.length);
+  let offset = header.length + directory.length;
+  entries.forEach((entry, index) => {
+    const at = index * 16;
+    directory.writeUInt8(entry.size >= 256 ? 0 : entry.size, at);
+    directory.writeUInt8(entry.size >= 256 ? 0 : entry.size, at + 1);
+    directory.writeUInt8(0, at + 2); // palette colours
+    directory.writeUInt8(0, at + 3); // reserved
+    directory.writeUInt16LE(1, at + 4); // colour planes
+    directory.writeUInt16LE(32, at + 6); // bits per pixel
+    directory.writeUInt32LE(entry.bytes.length, at + 8);
+    directory.writeUInt32LE(offset, at + 12);
+    offset += entry.bytes.length;
+  });
+
+  return Buffer.concat([header, directory, ...entries.map(entry => entry.bytes)]);
+}
diff --git a/scripts/privacy-scan.ts b/scripts/privacy-scan.ts
index 5d6e288b1e4..cedb2360424 100644
--- a/scripts/privacy-scan.ts
+++ b/scripts/privacy-scan.ts
@@ -110,6 +110,13 @@ function isAllowedEmail(file: string, email: string): boolean {
   }
   // URL-userinfo fixtures (https://user:pw@host/...) read as "pw@host" — not emails.
   if (file.startsWith("tests/") && email === ["pw", "chatgpt.com"].join("@")) return true;
+  // Retina asset names read as addresses: "128x128@2x.png" is local part "128x128", domain "2x",
+  // and the loose TLD rule accepts "png". The exemption is written against the asset-name grammar
+  // rather than against that shape, because a person's name in front of the same scale suffix is
+  // the same shape and is a mailbox. The part before the suffix has to be a pixel dimension,
+  // optionally prefixed the way an iconset member is, so a name someone could receive mail at
+  // does not match.
+  if (/^(?:[a-z]+_)?\d+x\d+@[23]x\.(?:png|jpe?g|gif|webp|tiff?)$/i.test(email)) return true;
   return file.startsWith("tests/") && email === "a@b.com";
 }
 
diff --git a/scripts/standalone-targets.ts b/scripts/standalone-targets.ts
new file mode 100644
index 00000000000..27b9a635b1e
--- /dev/null
+++ b/scripts/standalone-targets.ts
@@ -0,0 +1,29 @@
+/**
+ * Standalone binary target metadata — the single source for the standalone build
+ * matrix. scripts/build-standalone.ts builds from this list, the release workflow's
+ * package-standalone matrix must stay equal to it, and the pre-publication
+ * verifier derives its expected standalone assets from it.
+ */
+export const standaloneTargets = [
+  "bun-darwin-arm64",
+  "bun-darwin-x64",
+  "bun-windows-x64",
+  "bun-linux-x64",
+  "bun-linux-arm64",
+] as const;
+
+export function isStandaloneTarget(value: string): boolean {
+  return (standaloneTargets as readonly string[]).includes(value);
+}
+
+export function standaloneExecutableName(target: string): string {
+  return target.startsWith("bun-windows-") ? "ocx.exe" : "ocx";
+}
+
+export function standaloneArchiveExtension(target: string): string {
+  return target.startsWith("bun-windows-") ? "zip" : "tar.gz";
+}
+
+export function standaloneArchiveName(version: string, target: string): string {
+  return `ocx-${version}-${target}.${standaloneArchiveExtension(target)}`;
+}
diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json
index ef1c68922bb..3905c739ac9 100644
--- a/scripts/test-layout/layout.json
+++ b/scripts/test-layout/layout.json
@@ -167,12 +167,23 @@
     }
   },
   "explicit": {
+    "release-desktop-scripts.test.ts": "ci-workflows",
+    "installed-gate-drivers.test.ts": "ci-workflows",
+    "gui-desktop-sidecar-script.test.ts": "gui",
+    "standalone-build-script.test.ts": "gui",
+    "standalone-service.test.ts": "service",
+    "standalone.test.ts": "lib",
     "server-combo-held-response.test.ts": "server",
     "key-attribution.test.ts": "usage",
     "provider-send-path-import.test.ts": "server",
     "socks5-fetch.test.ts": "lib",
     "socks5-upload-lifecycle.test.ts": "lib",
+    "provider-egress.test.ts": "lib",
+    "provider-egress-outbound.test.ts": "providers",
+    "provider-egress-fetch.test.ts": "responses",
+    "provider-egress-management-validation.test.ts": "server",
     "start-args.test.ts": "cli",
+    "start-ownership-publication.test.ts": "cli",
     "responses-core-modules.test.ts": "responses",
     "responses-passthrough-transient-policy.test.ts": "responses",
     "responses-spend-ledger-wiring.test.ts": "responses",
@@ -181,10 +192,12 @@
     "chat-responses-control-integration.test.ts": "responses",
     "coding-agent-tool-result-images.test.ts": "adapters",
     "cold-spawn-warmup.test.ts": "ci-workflows",
+    "stepfun-provider.test.ts": "providers",
     "warmup-registration.test.ts": "ci-workflows",
     "hub-usage.test.ts": "server",
     "client-hub-usage.test.ts": "clients",
     "cli-usage-hub.test.ts": "cli",
+    "cli-companion.test.ts": "cli",
     "abort-idle-deadline.test.ts": "lib",
     "abort-race.test.ts": "adapters",
     "account-import.test.ts": "server",
@@ -292,10 +305,13 @@
     "bridge-terminal-singleness.test.ts": "adapters",
     "bridge.test.ts": "adapters",
     "buffered-response-shape-guards.test.ts": "adapters",
+    "brand-favicons.test.ts": "ci-workflows",
+    "build-desktop-icon-set.test.ts": "ci-workflows",
     "build-release-changelog.test.ts": "ci-workflows",
     "bump-dev-version.test.ts": "ci-workflows",
     "bun-runtime.test.ts": "ci-workflows",
     "bun-stream-caps.test.ts": "lib",
+    "cache-diagnostic.test.ts": "usage",
     "cancel-body-on-abort.test.ts": "server",
     "catalog-auto-refresh-scheduler.test.ts": "codex-integration",
     "catalog-cursor-search.test.ts": "codex-integration",
@@ -323,6 +339,7 @@
     "chat-inbound-reasoning-none.test.ts": "responses",
     "chat-inbound-reasoning-replay.test.ts": "responses",
     "chat-json-sse-fallback.test.ts": "responses",
+    "chat-native-developer-role.test.ts": "responses",
     "chat-native-image-normalization.test.ts": "responses",
     "chat-refusal.test.ts": "responses",
     "chat-refusal-scope.test.ts": "responses",
@@ -408,6 +425,8 @@
     "cli-ready-subprocess.test.ts": "cli",
     "cli-ready.test.ts": "cli",
     "cli-registry.test.ts": "cli",
+    "cli-resolve-subprocess.test.ts": "cli",
+    "cli-resolve.test.ts": "cli",
     "cli-restart-health.test.ts": "cli",
     "cli-restore-back.test.ts": "cli",
     "cli-start-auxiliary-bind.test.ts": "cli",
@@ -415,6 +434,7 @@
     "cli-status-hub-state.test.ts": "cli",
     "cli-status-json.test.ts": "cli",
     "cli-status-oauth-health.test.ts": "cli",
+    "cli-stop-json.test.ts": "cli",
     "cli-storage-inspect.test.ts": "cli",
     "cli-transport-honesty.test.ts": "cli",
     "cli-usage-report.test.ts": "cli",
@@ -522,6 +542,8 @@
     "codex-management-convergence.test.ts": "codex-integration",
     "codex-metadata-integrity.test.ts": "codex-integration",
     "codex-model-entitlements.test.ts": "codex-integration",
+    "codex-model-entitlement-admission.test.ts": "codex-integration",
+    "codex-routing-cache-affinity-detour.test.ts": "codex-integration",
     "codex-model-denial-evidence.test.ts": "codex-integration",
     "codex-model-availability-error.test.ts": "codex-integration",
     "codex-models-cache-invalidate.test.ts": "codex-integration",
@@ -560,8 +582,11 @@
     "codex-service-manager-probe-hardening.test.ts": "codex-integration",
     "codex-service-manager-probe.test.ts": "codex-integration",
     "codex-shim-autorestore.test.ts": "codex-integration",
+    "codex-shim-ensure-failure.test.ts": "codex-integration",
     "codex-shim-readiness.test.ts": "codex-integration",
     "codex-shim.test.ts": "codex-integration",
+    "codex-signin-lockout.test.ts": "codex-integration",
+    "server-gui-bundle-freshness.test.ts": "server",
     "codex-spark-visibility.test.ts": "codex-integration",
     "codex-sqlite-home.test.ts": "codex-integration",
     "codex-sync-api.test.ts": "codex-integration",
@@ -616,6 +641,7 @@
     "credential-redirect-guard.test.ts": "lib",
     "crusoe-provider.test.ts": "providers",
     "cursor-adapter.test.ts": "providers/cursor",
+    "cursor-roster-account-scope.test.ts": "providers/cursor",
     "cursor-continuity-retention.test.ts": "providers/cursor",
     "cursor-arg-normalize.test.ts": "providers/cursor",
     "cursor-blob-integrity.test.ts": "providers/cursor",
@@ -695,8 +721,16 @@
     "desktop-3p-removal.test.ts": "clients",
     "desktop-3p.test.ts": "clients",
     "desktop-app-restart.test.ts": "clients",
+    "desktop-cli-contracts.test.ts": "clients",
+    "desktop-exit-ownership.test.ts": "clients",
+    "desktop-install-identity.test.ts": "clients",
     "desktop-profile.test.ts": "clients",
+    "desktop-startup-surface.test.ts": "clients",
+    "desktop-tray-availability.test.ts": "clients",
+    "desktop-widget-entry.test.ts": "clients",
     "desktop-remote-store.test.ts": "clients",
+    "desktop-runtime-identity.test.ts": "clients",
+    "desktop-start-at-login-default.test.ts": "clients",
     "destination-policy-resolved.test.ts": "routing",
     "devin-adapter.test.ts": "providers",
     "devin-cli-authmode-migration.test.ts": "providers",
@@ -806,6 +840,8 @@
     "health-scoring.test.ts": "server",
     "history-migration-guardian.test.ts": "codex-integration",
     "history-ocx-compaction-recovery.test.ts": "codex-integration",
+    "history-paginated-openai-compat.test.ts": "codex-integration",
+    "history-paginated-transition-destinations.test.ts": "codex-integration",
     "hub-gated-local-clients.test.ts": "cli",
     "hub-invite.test.ts": "cli",
     "hyperbolic-provider.test.ts": "providers",
@@ -817,11 +853,13 @@
     "injection-model-api.test.ts": "codex-integration",
     "input-admission.test.ts": "server",
     "install-scripts.test.ts": "ci-workflows",
+    "integrations-current-store.test.ts": "clients",
     "integrations-invariants.test.ts": "gui",
     "integrations-journal.test.ts": "clients",
     "integrations-merge.test.ts": "clients",
     "integrations-serialize.test.ts": "clients",
     "integrations-state.test.ts": "clients",
+    "integrations-superseded-store.test.ts": "clients",
     "integrations-writer-frozen-config.test.ts": "clients",
     "integrations-writer.test.ts": "clients",
     "interactive-confirm.test.ts": "cli",
@@ -1012,11 +1050,13 @@
     "oauth-first-add-hint.test.ts": "gui",
     "oauth-health.test.ts": "oauth",
     "oauth-log.test.ts": "oauth",
+    "oauth-login-cli-browser-launch.test.ts": "oauth",
     "oauth-login-cli-live-update.test.ts": "oauth",
     "oauth-login-open-browser.test.ts": "oauth",
     "oauth-login-summary.test.ts": "oauth",
     "oauth-manual-code.test.ts": "oauth",
     "oauth-open-browser-choice.test.ts": "oauth",
+    "oauth-open-url-result.test.ts": "oauth",
     "oauth-provider-reconcile.test.ts": "oauth",
     "oauth-public-surface.test.ts": "oauth",
     "oauth-reauth-bind.test.ts": "oauth",
@@ -1052,6 +1092,7 @@
     "openai-chat-native-policy.test.ts": "adapters/openai",
     "openai-chat-parallel-stream.test.ts": "adapters/openai",
     "openai-chat-path-override.test.ts": "adapters/openai",
+    "openai-chat-reasoning-wire-policy.test.ts": "adapters/openai",
     "openai-chat-system-order.test.ts": "adapters/openai",
     "openai-chat-tool-result-images.test.ts": "adapters/openai",
     "openai-chat-url.test.ts": "adapters/openai",
@@ -1062,6 +1103,7 @@
     "openai-provider-option-tooling.test.ts": "adapters/openai",
     "openai-provider-option.test.ts": "adapters/openai",
     "openai-responses-passthrough.test.ts": "responses",
+    "opaque-blob-wrapped-rejection.test.ts": "responses",
     "opencode-cli.test.ts": "providers",
     "opencode-management-transport.test.ts": "providers",
     "opencode-free-provider.test.ts": "providers",
@@ -1104,6 +1146,7 @@
     "ports.test.ts": "server",
     "prime-client.test.ts": "clients",
     "privacy-mask-account.test.ts": "lib",
+    "privacy-scan-asset-names.test.ts": "ci-workflows",
     "privacy-scan-meta-key.test.ts": "ci-workflows",
     "privacy-scan-ssh-endpoint.test.ts": "ci-workflows",
     "probe-lease.test.ts": "routing",
@@ -1167,6 +1210,8 @@
     "reasoning-replay-robustness.test.ts": "adapters",
     "reasoning-replay-scope-source.test.ts": "lib",
     "redact.test.ts": "lib",
+    "failure-stage-model.test.ts": "lib",
+    "failure-attribution.test.ts": "lib",
     "relay-eager.test.ts": "server",
     "release-helper.test.ts": "ci-workflows",
     "release-notes.test.ts": "ci-workflows",
@@ -1197,6 +1242,7 @@
     "remote-workspace-protocol.test.ts": "clients",
     "remote-workspace-rpc-framing.test.ts": "clients",
     "remove-tree-helper.test.ts": "lib",
+    "replay-refusal-parity.test.ts": "server",
     "repo-hygiene.test.ts": "ci-workflows",
     "request-decompress.test.ts": "usage",
     "request-evidence.test.ts": "usage",
@@ -1204,6 +1250,11 @@
     "request-log-conversation.test.ts": "usage",
     "request-log-estimate-cap.test.ts": "usage",
     "request-log.test.ts": "usage",
+    "request-outcome-agreement.test.ts": "usage",
+    "usage-failure-fingerprint.test.ts": "usage",
+    "usage-failure-projection.test.ts": "usage",
+    "usage-attempt-delivery.test.ts": "usage",
+    "usage-ledger-retention.test.ts": "usage",
     "request-pacing.test.ts": "usage",
     "reserve-auth-context.test.ts": "codex-integration",
     "reserve-availability.test.ts": "codex-integration",
@@ -1261,6 +1312,7 @@
     "responses-show-thinking-summary.test.ts": "responses",
     "responses-snapshot-repair-server.test.ts": "responses",
     "responses-snapshot-repair.test.ts": "responses",
+    "responses-sparse-terminal-tool-scope.test.ts": "responses",
     "responses-spill-shutdown-clock.test.ts": "responses",
     "responses-state-write-amplification.test.ts": "responses",
     "responses-state.test.ts": "responses",
@@ -1328,6 +1380,9 @@
     "server-xai-header-parity.test.ts": "server",
     "server-xai-oauth-401-replay.test.ts": "server",
     "server-xai-responses-streaming.test.ts": "server",
+    "service-ownership-compatibility.test.ts": "service",
+    "service-ownership-handover.test.ts": "service",
+    "service-ownership-state.test.ts": "service",
     "service-probe-docker.test.ts": "service",
     "service-secrets.test.ts": "service",
     "service-sqlite-home.test.ts": "service",
@@ -1431,6 +1486,7 @@
     "umans-provider.test.ts": "providers",
     "uninstall.test.ts": "cli",
     "update-badge.test.ts": "update",
+    "update-desktop-owner.test.ts": "update",
     "update-job.test.ts": "update",
     "update-notify.test.ts": "update",
     "update-npm-cache-preflight.test.ts": "update",
@@ -1521,6 +1577,7 @@
     "ws-upstream.test.ts": "responses",
     "ws-upstream-socks5.test.ts": "responses",
     "xai-client.test.ts": "images",
+    "xai-empty-catalog-tool-choice.test.ts": "providers/xai",
     "xai-oauth-retry.test.ts": "providers/xai",
     "xai-refresh-lock.test.ts": "providers/xai",
     "xai-responses-adjacency.test.ts": "providers/xai",
@@ -1566,7 +1623,36 @@
     "web-search-sidecar-429.test.ts": "web-search",
     "management-google-tool-schema-policy.test.ts": "server",
     "codex-shim-destroyed-probe.test.ts": "codex-integration",
-    "client-runtime.test.ts": "clients"
+    "client-runtime.test.ts": "clients",
+    "usage-timeline.test.ts": "usage",
+    "companion-settings.test.ts": "server",
+    "chat-tool-choice-allowed-tools.test.ts": "responses",
+    "anthropic-tool-declaration-constraints.test.ts": "adapters/anthropic",
+    "google-strict-tool-validated-mode.test.ts": "adapters/google",
+    "openai-chat-developer-position.test.ts": "adapters/openai",
+    "chat-inline-document-bytes.test.ts": "responses",
+    "devin-output-budget.test.ts": "providers",
+    "api-key-model-scope.test.ts": "server",
+    "docs-provider-discovery-limits.test.ts": "ci-workflows",
+    "api-key-scope-images.test.ts": "server",
+    "api-key-scope-audio.test.ts": "server",
+    "api-key-scope-live.test.ts": "server",
+    "api-key-scope-alpha-search.test.ts": "server",
+    "claude-intercept-local-ca.test.ts": "claude-integration",
+    "claude-intercept-proxy.test.ts": "claude-integration",
+    "claude-intercept-settings.test.ts": "claude-integration",
+    "claude-desktop-first-party.test.ts": "claude-integration",
+    "claude-desktop-mode-explanation.test.ts": "claude-integration",
+    "claude-intercept-integration.test.ts": "server",
+    "management-provider-reset-replay.test.ts": "server",
+    "responses-reset-replay.test.ts": "responses",
+    "ambiguous-resend-gate.test.ts": "lib",
+    "docs-developer-role-policy.test.ts": "ci-workflows",
+    "ambiguous-resend-composition.test.ts": "lib",
+    "chat-inbound-developer-position.test.ts": "responses",
+    "release-pipeline-contract.test.ts": "ci-workflows",
+    "desktop-proxy-direct-transport.test.ts": "clients",
+    "platform-dialog-guard.test.ts": "gui"
   },
   "migrated": [
     "adapters",
diff --git a/scripts/test.ts b/scripts/test.ts
index 4406b080867..dc95434b782 100644
--- a/scripts/test.ts
+++ b/scripts/test.ts
@@ -352,6 +352,15 @@ export const SERIAL_FULL_SUITE_FILES = [
   "adapters/openai/openai-provider-option-e2e.test.ts",
   "ci-workflows/release-helper.test.ts",
   "update/update-stop-first.test.ts",
+  // Relays a 50 MiB WebSocket frame end to end against a 15s deadline, so its result is a
+  // measurement of the whole process, not of the relay. On a healthy 3-CPU macOS runner the
+  // echo leg alone spends 7.4s of that budget; whichever half of `--shard=N/2` it lands in
+  // decides whether it finishes. It has been passing by accident: it sat in the lighter half
+  // until three unrelated test files were added elsewhere in the tree, Bun repartitioned, and
+  // it went from 7.4s to over 15s twice in a row without anything on the sideband path
+  // changing. Quarantining it here is what keeps it a test of the relay instead of a test of
+  // its neighbours.
+  "server/server-live.test.ts",
 ] as const;
 
 type SerialLaneBasename = (typeof SERIAL_FULL_SUITE_FILES)[number] extends infer P
diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md
index 78d2047d1aa..5682c76ac71 100644
--- a/skills/ocx/references/01_management_surface.md
+++ b/skills/ocx/references/01_management_surface.md
@@ -72,6 +72,21 @@ JSON mode: `envelope`.
 
 - Reads /healthz plus local config; drives no management API route.
 
+### `ocx resolve`
+
+One JSON document naming the config home, the effective port, and the identity-checked proxy liveness verdict.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the resolve document as JSON (the shell contract). |
+
+JSON mode: `envelope`.
+
+- Exit 0 carries a trustworthy verdict (live or proven absent); exit 1 means the CLI could not resolve and a caller must refuse to guess — unknown liveness never reads as absent.
+- Built for embedding shells (desktop app): the liveness budgets stay owned by src/server/proxy-liveness.ts.
+
 ### `ocx capabilities`
 
 List the declared CLI capabilities and the management routes they drive.
@@ -537,6 +552,25 @@ JSON mode: `payload`.
 - `store` verifies every keychain write by read-back before config.json is rewritten with keychain: references; an unavailable keychain refuses with 503 and leaves the file untouched.
 - Headless services usually have no unlocked keychain session; prefer ${ENV_VAR} references there.
 
+### `ocx companion`
+
+Inspect and configure menu-bar and widget companion usage settings.
+
+| Method | Route |
+|---|---|
+| GET | `/api/companion/settings` |
+| GET | `/api/usage/timeline` |
+| PUT | `/api/companion/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit companion settings as JSON. |
+
+JSON mode: `payload`.
+
+- `show` (the default) reads settings; `set key=value ...` updates selected settings; `reset` restores defaults.
+- Values accepted by `set` are parsed as JSON when valid, so booleans, numbers, arrays, objects, and null can be passed directly.
+
 ### `ocx account main reauth`
 
 Reauthenticate the native main Codex login with a device code (#3898); headless hubs need no Codex App or keyring.
@@ -896,6 +930,6 @@ JSON mode: `payload`.
 
 ## Counts
 
-- declared capabilities: 48
-- of those, state-changing: 24
+- declared capabilities: 50
+- of those, state-changing: 25
 - head-resolved invocations: 2
diff --git a/src/adapters/anthropic.ts b/src/adapters/anthropic.ts
index c90f8009a66..9e2e1ffb425 100644
--- a/src/adapters/anthropic.ts
+++ b/src/adapters/anthropic.ts
@@ -39,6 +39,16 @@ function toAnthropicContentPart(p: OcxContentPart): unknown {
       : { type: "image", source: { type: "url", url: p.imageUrl } };
   }
   if (p.type === "video") return { type: "text", text: "[video]" };
+  // The block the caller sent, rebuilt. A Messages-to-Messages route used to reduce it to its
+  // title before any adapter ran, so the model was told a document existed rather than given
+  // one, and the answer came back looking the same (#5212).
+  if (p.type === "document") {
+    return {
+      type: "document",
+      source: { type: "base64", media_type: p.mediaType, data: p.data },
+      ...(p.filename !== undefined ? { title: p.filename } : {}),
+    };
+  }
   return { type: "text", text: p.text };
 }
 
@@ -857,6 +867,12 @@ function toolsToAnthropicFormat(parsed: OcxParsedRequest, toolNames: { toWire: (
     name: toolNames.toWire(namespacedToolName(t.namespace, t.name)),
     description: t.description,
     input_schema: normalizeAnthropicInputSchema(t.parameters),
+    // Anthropic is the target that DEFINES both of these, and both were dropped while the
+    // OpenAI Chat adapter already forwarded strict (#5210). Only an explicit `true` is
+    // emitted: the Messages inbound records an absent strict as `false`, so a false here
+    // cannot be distinguished from silence and must not become an opt-out on the wire.
+    ...(t.strict === true ? { strict: true } : {}),
+    ...(t.allowedCallers !== undefined ? { allowed_callers: [...t.allowedCallers] } : {}),
   }));
   return converted;
 }
diff --git a/src/adapters/coding-agent/protocol.ts b/src/adapters/coding-agent/protocol.ts
index 779e88d14f7..4d38ac071e1 100644
--- a/src/adapters/coding-agent/protocol.ts
+++ b/src/adapters/coding-agent/protocol.ts
@@ -21,6 +21,30 @@ export const MAX_STREAM_LINE_BYTES = 8 * 1024 * 1024;
 export const MAX_STREAM_TOTAL_BYTES = 64 * 1024 * 1024;
 /** Hard ceiling on projected conversation history text (characters) to prevent runaway memory. */
 export const MAX_PROJECTED_HISTORY_CHARS = 200_000;
+/**
+ * Chars-per-token ratio for deriving the projected-history ceiling from the model context
+ * window. Sits between the English/code (~4 chars per token) and CJK (~1.5) extremes: the
+ * ceiling is a runaway-memory bound and a coarse guard against cutting history the window can
+ * hold, not a token accounting - the caller-side compaction line stays the token authority.
+ */
+const PROJECTED_HISTORY_CHARS_PER_TOKEN = 3;
+/** Absolute ceiling on a window-derived history cap, so runaway metadata cannot unbound stdin. */
+const MAX_PROJECTED_HISTORY_DERIVED_CHARS = 4_000_000;
+
+/**
+ * Projected-history character ceiling for a turn, derived from the declared model context
+ * window. A missing or non-finite window keeps the legacy flat cap, and the derivation never
+ * lowers the cap below it: small windows change nothing, while large windows scale (a 1M-token
+ * model keeps 3M characters) until the hard ceiling. The flat 200k cap predates window
+ * metadata and cut long replays to roughly 50k-130k tokens of content regardless of the model.
+ */
+export function projectedHistoryCharLimit(contextWindowTokens: number | undefined): number {
+  if (typeof contextWindowTokens !== "number" || !Number.isFinite(contextWindowTokens) || contextWindowTokens <= 0) {
+    return MAX_PROJECTED_HISTORY_CHARS;
+  }
+  const derived = contextWindowTokens * PROJECTED_HISTORY_CHARS_PER_TOKEN;
+  return Math.min(Math.max(derived, MAX_PROJECTED_HISTORY_CHARS), MAX_PROJECTED_HISTORY_DERIVED_CHARS);
+}
 
 export class CodingAgentStreamLimitError extends Error {
   constructor(message: string) {
@@ -308,7 +332,7 @@ function formatMessageForHistory(message: OcxMessage): string {
   if (message.role === "user") {
     const text = typeof message.content === "string"
       ? message.content
-      : message.content.map(p => (p.type === "text" ? p.text : `[${p.type}]`)).join("\n");
+      : message.content.map(p => (p.type === "text" || p.type === "document" ? p.text : `[${p.type}]`)).join("\n");
     return `USER:\n${text}`;
   }
   if (message.role === "assistant") {
@@ -328,7 +352,7 @@ function formatMessageForHistory(message: OcxMessage): string {
   if (message.role === "toolResult") {
     const text = typeof message.content === "string"
       ? message.content
-      : message.content.map(p => (p.type === "text" ? p.text : "[image]")).join("");
+      : message.content.map(p => (p.type === "text" || p.type === "document" ? p.text : "[image]")).join("");
     const status = message.isError ? " (error)" : "";
     return `TOOL RESULT (call_id: ${message.toolCallId})${status}:\n${text}`;
   }
@@ -355,6 +379,8 @@ export function buildInputLines(message: OcxMessage): string[] {
         else if (part.type === "image") {
           const image = imagePart(part.imageUrl);
           if (image) content.push(image);
+        } else if (part.type === "document") {
+          content.push(textPart(part.text));
         } else {
           content.push(textPart("[video]"));
         }
@@ -378,7 +404,7 @@ export function buildSystemPrompt(parsed: OcxParsedRequest): string | undefined
     if (message.role !== "developer") continue;
     const text = typeof message.content === "string"
       ? message.content
-      : message.content.map(part => (part.type === "text" ? part.text : "")).join("");
+      : message.content.map(part => (part.type === "text" || part.type === "document" ? part.text : "")).join("");
     if (text.trim()) parts.push(text);
   }
   return parts.length > 0 ? parts.join("\n\n") : undefined;
@@ -395,7 +421,7 @@ export function buildSystemPrompt(parsed: OcxParsedRequest): string | undefined
  * prior conversation turns are structured as bounded context text with tool results as text,
  * clearly demarcated from the current user request. Codex retains tool control; vendor tools are never invoked.
  */
-export function buildConversationInput(parsed: OcxParsedRequest): string[] {
+export function buildConversationInput(parsed: OcxParsedRequest, options: { maxHistoryChars?: number } = {}): string[] {
   const nonDev = parsed.context.messages.filter(m => m.role !== "developer");
   if (nonDev.length === 0) {
     return [JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text: "" }] } })];
@@ -440,6 +466,8 @@ export function buildConversationInput(parsed: OcxParsedRequest): string[] {
           const image = imagePart(part.imageUrl);
           if (image) currentImageBlocks.push(image);
           else textParts.push("[image omitted: unsupported reference]");
+        } else if (part.type === "document") {
+          textParts.push(part.text);
         } else {
           textParts.push("[video]");
         }
@@ -463,6 +491,7 @@ export function buildConversationInput(parsed: OcxParsedRequest): string[] {
           else segments.push("[image omitted: unsupported reference]");
           continue;
         }
+        if (part.type === "document") { segments.push(part.text); continue; }
         segments.push("[video]");
       }
       text = segments.join("");
@@ -475,10 +504,11 @@ export function buildConversationInput(parsed: OcxParsedRequest): string[] {
 
   const imageBlocks: WireContentPart[] = [...historyImageBlocks, ...currentImageBlocks];
 
+  const maxHistoryChars = options.maxHistoryChars ?? MAX_PROJECTED_HISTORY_CHARS;
   let historyText = historyMessages.map(formatMessageForHistory).filter(Boolean).join("\n\n");
-  if (historyText.length > MAX_PROJECTED_HISTORY_CHARS) {
+  if (historyText.length > maxHistoryChars) {
     historyText = `[Earlier conversation history truncated for length...]\n\n` +
-      historyText.slice(historyText.length - MAX_PROJECTED_HISTORY_CHARS);
+      historyText.slice(historyText.length - maxHistoryChars);
   }
 
   const combinedText = `Prior conversation context:\n\n${historyText}\n\nCurrent user request:\n\n${currentRequestText}`;
diff --git a/src/adapters/coding-agent/turn.ts b/src/adapters/coding-agent/turn.ts
index a264ce188fa..f13b1ff0ea3 100644
--- a/src/adapters/coding-agent/turn.ts
+++ b/src/adapters/coding-agent/turn.ts
@@ -1,8 +1,9 @@
 import { execFileSync, spawn as nodeSpawn, type ChildProcess, type SpawnOptions } from "node:child_process";
 import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig } from "../../types";
 import { commandInvocation } from "../../lib/win-exec";
+import { modelRecordValue } from "../../reasoning-effort";
 import type { IncomingMeta } from "../base";
-import { buildConversationInput, CodingAgentProtocolError, mapStreamMessageToEvents, readJsonLines, type StreamParseState } from "./protocol";
+import { buildConversationInput, CodingAgentProtocolError, mapStreamMessageToEvents, projectedHistoryCharLimit, readJsonLines, type StreamParseState } from "./protocol";
 import { resolveCodingAgentBinary, resolveProfileByBaseUrl, type CodingAgentProviderProfile, type WhichFn } from "./profile";
 
 /** Injectable spawn for tests; production uses node:child_process. */
@@ -264,7 +265,14 @@ export async function runCodingAgentTurn(input: CodingAgentTurnInput): Promise<v
     const stdin = child.stdin;
     if (stdin) {
       stdin.on("error", () => { /* EPIPE if the CLI exits early; surfaced via close/stderr */ });
-      for (const line of buildConversationInput(parsed)) stdin.write(`${line}\n`);
+      // The projected history scales with the model context window on the routed provider row
+      // (catalog and config metadata merged): a 1M-token model keeps 3M characters of replay
+      // where the flat cap cut it near 50k-130k tokens of content. Absent metadata keeps the
+      // flat cap.
+      const historyCharLimit = projectedHistoryCharLimit(
+        modelRecordValue(provider.modelContextWindows, parsed.modelId) ?? provider.contextWindow,
+      );
+      for (const line of buildConversationInput(parsed, { maxHistoryChars: historyCharLimit })) stdin.write(`${line}\n`);
       stdin.end();
     }
     const stdout = child.stdout;
diff --git a/src/adapters/command-code.ts b/src/adapters/command-code.ts
index 35d54ebd463..c05263110f9 100644
--- a/src/adapters/command-code.ts
+++ b/src/adapters/command-code.ts
@@ -32,7 +32,7 @@ function canonicalCommandCodeModelId(modelId: string): string {
 /** Flatten tool-result content for the text-only wire output, keeping an `[image]` marker per image part in content order. */
 function toolResultText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
-  return content.map(part => (part.type === "text" ? part.text : "[image]")).join("");
+  return content.map(part => (part.type === "text" || part.type === "document" ? part.text : "[image]")).join("");
 }
 
 /** Best-effort media type from a remote https URL extension, e.g. image/png. */
@@ -149,6 +149,7 @@ function wireMessages(messages: OcxMessage[]): Array<Record<string, unknown>> {
     else for (const part of message.content) {
       if (part.type === "text") content.push({ type: "text", text: part.text });
       else if (part.type === "image") content.push(wireImagePart(part.imageUrl));
+      else if (part.type === "document") content.push({ type: "text", text: part.text });
       else content.push({ type: "text", text: "[video]" });
     }
     out.push({ role: "user", content });
diff --git a/src/adapters/cursor.ts b/src/adapters/cursor.ts
index 17f9fd45fd7..e495f2a6713 100644
--- a/src/adapters/cursor.ts
+++ b/src/adapters/cursor.ts
@@ -61,6 +61,7 @@ import {
   CursorTransportDisabledError,
   type CursorTransportFactory,
 } from "./cursor/transport";
+import { cursorLiveRosterScope } from "./cursor/catalog";
 
 export const CURSOR_API_URL = "https://api2.cursor.sh";
 
@@ -172,9 +173,11 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         // Namespace thread→conversation derivation by the authenticated Cursor credential so
         // shared-proxy tenants with different Cursor accounts cannot collide on a parent thread id.
         // Prefer an already-set auth scope (e.g. Codex pool account) when present.
+        let liveRosterScope: string | undefined;
         if (!_parsed._cursorIdentityScope) {
           try {
             const token = resolveCursorToken(provider, incoming.headers);
+            liveRosterScope = cursorLiveRosterScope(provider.baseUrl, token);
             _parsed._cursorIdentityScope = createHash("sha256")
               .update("ocx:cursor:acct:")
               .update(token)
@@ -183,11 +186,17 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
           } catch {
             /* Missing credential is handled by the live transport path below. */
           }
+        } else {
+          try {
+            liveRosterScope = cursorLiveRosterScope(provider.baseUrl, resolveCursorToken(provider, incoming.headers));
+          } catch {
+            /* Missing credential is handled by the live transport path below. */
+          }
         }
         const inheritedCheckpointRef = _parsed._providerContinuation?.cursor?.checkpointRef;
         const previousConversationId = _parsed._cursorConversationId;
         let request = {
-          ...createCursorRequest(_parsed),
+          ...createCursorRequest(_parsed, { liveRosterScope }),
           _cursorIdentityScope: _parsed._cursorIdentityScope?.trim() || "local",
         };
         requestSizeContext = cursorRequestSizeContext(request);
@@ -441,7 +450,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
           lastTransport = undefined;
           _parsed._cursorConversationId = undefined;
           const next = {
-            ...createCursorRequest(_parsed, { forceFreshConversation: true }),
+            ...createCursorRequest(_parsed, { forceFreshConversation: true, liveRosterScope }),
             _cursorIdentityScope: _parsed._cursorIdentityScope?.trim() || "local",
           };
           rekeyContextUsage(failedConversationId, next.conversationId);
diff --git a/src/adapters/cursor/catalog.ts b/src/adapters/cursor/catalog.ts
index 69791f087b8..d6a73defe26 100644
--- a/src/adapters/cursor/catalog.ts
+++ b/src/adapters/cursor/catalog.ts
@@ -3,6 +3,7 @@ import {
   normalizeCursorClaudeId,
   type NormalizedCursorClaudeId,
 } from "./claude-id";
+import { createHash } from "node:crypto";
 
 /**
  * Cursor umbrella catalog — the single source of truth for cursor model
@@ -599,7 +600,7 @@ export function resolveCursorSelection(
   pickedId: string,
   reasoning: string | undefined,
   liveMaxModeIds?: ReadonlySet<string>,
-  options: { fast?: boolean } = {},
+  options: { fast?: boolean; liveRosterScope?: string } = {},
 ): CursorResolvedSelection {
   const parsed = parseCursorVariantId(pickedId);
   if (!parsed.known) {
@@ -617,7 +618,10 @@ export function resolveCursorSelection(
   const requested = parsed.level ?? reasoning;
   const effort = cursorVariantEffort(spec, requested);
   const requestedClaude = normalizeCursorClaudeId(pickedId);
-  const claudeIdentity = liveCursorClaudeWireIdentities.get(parsed.baseId)
+  const scopedClaudeIdentities = options.liveRosterScope
+    ? liveCursorClaudeWireIdentitiesByScope.get(options.liveRosterScope)
+    : liveCursorClaudeWireIdentities;
+  const claudeIdentity = scopedClaudeIdentities?.get(parsed.baseId)
     ?? (requestedClaude
       ? { sourceBaseId: requestedClaude.sourceBaseId, spelling: requestedClaude.spelling }
       : undefined);
@@ -626,7 +630,9 @@ export function resolveCursorSelection(
     ? `${capability.wirePrefix}${canonicalId}`
     : canonicalId;
   const ultraRequested = parsed.ultra || reasoning?.toLowerCase() === "ultra";
-  const evidence = liveMaxModeIds ?? liveCursorMaxModeBases;
+  const evidence = liveMaxModeIds
+    ?? (options.liveRosterScope ? liveCursorMaxModeBasesByScope.get(options.liveRosterScope) : undefined)
+    ?? liveCursorMaxModeBases;
   const maxModeArmed = capability.maxModeVerified === true || evidence.has(parsed.baseId);
   return { wireId, canonicalId, maxMode: ultraRequested && maxModeArmed, known: true };
 }
@@ -639,15 +645,36 @@ export function resolveCursorSelection(
  */
 let liveCursorMaxModeBases: ReadonlySet<string> = new Set();
 let liveCursorClaudeWireIdentities: ReadonlyMap<string, CursorLiveClaudeWireIdentity> = new Map();
+const liveCursorMaxModeBasesByScope = new Map<string, ReadonlySet<string>>();
+const liveCursorClaudeWireIdentitiesByScope = new Map<string, ReadonlyMap<string, CursorLiveClaudeWireIdentity>>();
+const liveCursorRosterScopesByProvider = new Map<string, Set<string>>();
+
+/** Non-secret key binding live roster evidence to one upstream destination and credential. */
+export function cursorLiveRosterScope(baseUrl: string | undefined, credential: string): string {
+  const destination = (baseUrl?.trim().replace(/\/+$/, "") || "https://api2.cursor.sh");
+  return createHash("sha256")
+    .update("ocx:cursor:live-roster\0")
+    .update(destination)
+    .update("\0")
+    .update(credential)
+    .digest("hex");
+}
 
-export function recordLiveCursorClaudeModels(liveIds: readonly string[]): void {
+export function recordLiveCursorClaudeModels(liveIds: readonly string[], scope?: { provider: string; key: string }): void {
   const next = new Map<string, CursorLiveClaudeWireIdentity>();
   for (const rawId of liveIds) {
     const n = normalizeCursorClaudeId(rawId.startsWith("cursor-") ? rawId.slice(7) : rawId);
     if (!n || !CURSOR_CAPABILITIES[n.canonicalBaseId]) continue;
     if (!next.has(n.canonicalBaseId)) next.set(n.canonicalBaseId, { sourceBaseId: n.sourceBaseId, spelling: n.spelling });
   }
-  liveCursorClaudeWireIdentities = next;
+  if (scope) {
+    liveCursorClaudeWireIdentitiesByScope.set(scope.key, next);
+    const scopes = liveCursorRosterScopesByProvider.get(scope.provider) ?? new Set<string>();
+    scopes.add(scope.key);
+    liveCursorRosterScopesByProvider.set(scope.provider, scopes);
+  } else {
+    liveCursorClaudeWireIdentities = next;
+  }
 }
 
 export function liveCursorClaudeWireIdentitiesForTests(): ReadonlyMap<string, CursorLiveClaudeWireIdentity> {
@@ -656,15 +683,32 @@ export function liveCursorClaudeWireIdentitiesForTests(): ReadonlyMap<string, Cu
 
 export function resetLiveCursorClaudeWireIdentitiesForTests(): void {
   liveCursorClaudeWireIdentities = new Map();
+  liveCursorClaudeWireIdentitiesByScope.clear();
+  liveCursorRosterScopesByProvider.clear();
 }
 
-export function recordLiveCursorMaxModeModels(liveIds: readonly string[]): void {
+export function recordLiveCursorMaxModeModels(liveIds: readonly string[], scope?: { provider: string; key: string }): void {
   const bases = new Set<string>();
   for (const id of liveIds) {
     const parsed = parseCursorVariantId(id);
     if (parsed.known) bases.add(parsed.baseId);
   }
-  liveCursorMaxModeBases = bases;
+  if (scope) liveCursorMaxModeBasesByScope.set(scope.key, bases);
+  else liveCursorMaxModeBases = bases;
+}
+
+export function clearLiveCursorRosterState(provider?: string): void {
+  if (!provider) {
+    liveCursorClaudeWireIdentitiesByScope.clear();
+    liveCursorMaxModeBasesByScope.clear();
+    liveCursorRosterScopesByProvider.clear();
+    return;
+  }
+  for (const scope of liveCursorRosterScopesByProvider.get(provider) ?? []) {
+    liveCursorClaudeWireIdentitiesByScope.delete(scope);
+    liveCursorMaxModeBasesByScope.delete(scope);
+  }
+  liveCursorRosterScopesByProvider.delete(provider);
 }
 
 export function liveCursorMaxModeBasesForTests(): ReadonlySet<string> {
diff --git a/src/adapters/cursor/protobuf-request.ts b/src/adapters/cursor/protobuf-request.ts
index 894cf3eae45..83e076dcced 100644
--- a/src/adapters/cursor/protobuf-request.ts
+++ b/src/adapters/cursor/protobuf-request.ts
@@ -741,7 +741,7 @@ function contentText(message: OcxMessage): string {
   if (typeof message.content === "string") return message.content;
   return message.content
     .map(part => {
-      if (part.type === "text") return part.text;
+      if (part.type === "text" || part.type === "document") return part.text;
       if (part.type === "thinking") return part.thinking;
       if (part.type === "image") return undefined;
       return undefined;
@@ -754,7 +754,7 @@ function contentToText(content: OcxToolResultMessage["content"]): string {
   if (typeof content === "string") return content;
   return content
     .map(part => {
-      if (part.type === "text") return part.text;
+      if (part.type === "text" || part.type === "document") return part.text;
       if (part.type === "image") return CURSOR_VISION_IMAGE_HISTORY_MARKER;
       return undefined;
     })
@@ -767,7 +767,7 @@ function historyContentText(message: OcxMessage): string {
   if (message.role === "toolResult" || typeof message.content === "string") return contentText(message);
   return message.content
     .map(part => {
-      if (part.type === "text") return part.text;
+      if (part.type === "text" || part.type === "document") return part.text;
       if (part.type === "thinking") return part.thinking;
       if (part.type === "image") return CURSOR_VISION_IMAGE_HISTORY_MARKER;
       return undefined;
@@ -836,6 +836,9 @@ function decodeResultParts(message: OcxToolResultMessage): DecodedResultPart[] |
   return content.map((part): DecodedResultPart => {
     if (part.type === "text") return { kind: "text", text: part.text };
     if (part.type === "video") return { kind: "text", text: "[video]" };
+    // Without this the document falls through to decodeInlineImage(part.imageUrl) below and is
+    // treated as an image it is not.
+    if (part.type === "document") return { kind: "text", text: part.text };
     const decoded = decodeInlineImage(part.imageUrl);
     return decoded ? { kind: "image", ...decoded } : { kind: "undecodable" };
   });
diff --git a/src/adapters/cursor/request-builder.ts b/src/adapters/cursor/request-builder.ts
index 065f971afa3..ec4fa07208c 100644
--- a/src/adapters/cursor/request-builder.ts
+++ b/src/adapters/cursor/request-builder.ts
@@ -213,7 +213,7 @@ export function cursorRequestEmitsFastVariant(parsed: OcxParsedRequest): boolean
  * instead: current Cursor clients send the matching Grok base id plus `effort` and `fast` parameters.
  * A fully-qualified id (one that is not a known effort base) passes through unchanged.
  */
-function normalizeCursorModelId(modelId: string, reasoning?: string, fast?: boolean): {
+function normalizeCursorModelId(modelId: string, reasoning?: string, fast?: boolean, liveRosterScope?: string): {
   modelId: string;
   requestedModelParameters?: readonly CursorRequestedModelParameter[];
   routingLevel?: CursorRoutingLevel;
@@ -239,7 +239,7 @@ function normalizeCursorModelId(modelId: string, reasoning?: string, fast?: bool
       ],
     };
   }
-  const resolved = resolveCursorSelection(id, reasoning, undefined, { fast });
+  const resolved = resolveCursorSelection(id, reasoning, undefined, { fast, liveRosterScope });
   return {
     ...selection,
     ...(resolved.maxMode ? { maxMode: true } : {}),
@@ -251,6 +251,9 @@ function contentPartToText(part: OcxContentPart | OcxAssistantContentPart): stri
   switch (part.type) {
     case "text":
       return part.text;
+    case "document":
+      // Cursor has no document carrier; the marker keeps the turn from serializing to nothing.
+      return part.text;
     case "thinking":
       return part.thinking;
     case "image":
@@ -407,6 +410,8 @@ export function cursorCoveredPrefixDigest(parsed: OcxParsedRequest, coveredMessa
 export interface CreateCursorRequestOptions {
   /** Force a brand-new Cursor conversation id even when remembered state exists. */
   forceFreshConversation?: boolean;
+  /** Credential-bound scope for live Cursor model spelling and Max-Mode evidence. */
+  liveRosterScope?: string;
 }
 
 function lookupPrefixSnapshot(
@@ -499,7 +504,12 @@ export function createCursorRequest(
   const visibleTools = cursorToolsForActivePrompt(parsed.context.tools, activeText, parsed.options.toolChoice);
   const budget = applyCursorToolBudget(visibleTools, parsed.options.toolChoice);
   const limitNote = catalogLimitNote(budget.tools, budget.omitted);
-  const model = normalizeCursorModelId(parsed.modelId, parsed.options.reasoning, cursorFastRequested(parsed));
+  const model = normalizeCursorModelId(
+    parsed.modelId,
+    parsed.options.reasoning,
+    cursorFastRequested(parsed),
+    options.liveRosterScope,
+  );
   const request: CursorRunRequest = {
     modelId: model.modelId,
     ...(model.requestedModelParameters ? { requestedModelParameters: model.requestedModelParameters } : {}),
diff --git a/src/adapters/declaration-carrier.ts b/src/adapters/declaration-carrier.ts
new file mode 100644
index 00000000000..a1f99739c97
--- /dev/null
+++ b/src/adapters/declaration-carrier.ts
@@ -0,0 +1,45 @@
+// Type-only: erased at compile time, so this does not create an import cycle with the registry.
+import type { AdapterWire } from "./registry";
+import type { OcxMessage, OcxParsedRequest } from "../types";
+import { toolRestrictsCallers } from "../types";
+
+/**
+ * Wires that can actually carry a constraint, as a default-deny allowlist.
+ *
+ * A per-adapter opt-in is the wrong shape for this: an adapter that never learned about a
+ * carrier rebuilds the declaration or the message without it and returns a normal completion,
+ * which is exactly the silent widening this batch exists to remove. Listing the wires that CAN
+ * carry it means a new wire refuses until someone teaches it, and adding a member to
+ * `AdapterWire` makes the omission visible here rather than at a customer's upstream.
+ */
+const CALLER_RESTRICTION_WIRES: ReadonlySet<AdapterWire> = new Set<AdapterWire>(["anthropic"]);
+const INLINE_DOCUMENT_WIRES: ReadonlySet<AdapterWire> = new Set<AdapterWire>([
+  "anthropic",
+  "openai-chat",
+  "google",
+]);
+
+/** A fixed-vocabulary refusal, or `undefined` when this wire can hold everything the request carries. */
+export function unrepresentableDeclaration(parsed: OcxParsedRequest, wire: AdapterWire): string | undefined {
+  if (!CALLER_RESTRICTION_WIRES.has(wire) && parsed.context.tools?.some(toolRestrictsCallers)) {
+    // The name is deliberately absent: it is caller-controlled and would put client metadata
+    // into an error body.
+    return "OpenCodex cannot express tools[].allowed_callers on this route. "
+      + "Route the request to an Anthropic-protocol provider, or remove the caller restriction.";
+  }
+  if (!INLINE_DOCUMENT_WIRES.has(wire) && parsed.context.messages.some(carriesDocument)) {
+    return "OpenCodex cannot translate document input on this route. "
+      + "Use a native input wire that supports the attachment, or convert it to text first.";
+  }
+  return undefined;
+}
+
+/**
+ * Typed structurally rather than as `OcxContentPart[]`: an assistant turn's content is
+ * `OcxAssistantContentPart[]`, which carries thinking and tool-call members and is not
+ * assignable to the user-content union. Only the discriminant is read here.
+ */
+function carriesDocument(message: OcxMessage): boolean {
+  const content: unknown = message.content;
+  return Array.isArray(content) && (content as ReadonlyArray<{ type: string }>).some(part => part.type === "document");
+}
diff --git a/src/adapters/devin.ts b/src/adapters/devin.ts
index 5832b2be8b7..fe81f356ba4 100644
--- a/src/adapters/devin.ts
+++ b/src/adapters/devin.ts
@@ -192,6 +192,35 @@ async function resolveWireModelUid(
  */
 export const resolveWireModelUidForTests = resolveWireModelUid;
 
+const positiveTokenCount = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+
+/**
+ * Read a per-model token count for the exact UID selected for this turn.
+ *
+ * Tries the selected UID and then its collapsed base id, preferring the
+ * canonical spelling and accepting dotted or case-folded saved hints — the same
+ * normalization the inference request applies to the model id. Where several
+ * spellings match one id, the smallest wins: a ceiling stated twice is
+ * satisfied by the lower statement.
+ */
+function devinModelTokenHint(
+  record: Record<string, number> | undefined,
+  modelUid: string,
+): number | undefined {
+  if (!record) return undefined;
+  for (const id of [modelUid, collapseDevinModelUid(modelUid)]) {
+    const exact = Object.hasOwn(record, id) ? positiveTokenCount(record[id]) : undefined;
+    if (exact !== undefined) return exact;
+    const matches = Object.entries(record)
+      .filter(([key]) => normalizeDevinModelId(key).toLowerCase() === id.toLowerCase())
+      .map(([, value]) => positiveTokenCount(value))
+      .filter((value): value is number => value !== undefined);
+    if (matches.length > 0) return Math.min(...matches);
+  }
+  return undefined;
+}
+
 /**
  * Resolve the INPUT ceiling for the exact UID selected for this turn. Catalog
  * ClientModelConfig #18 and CompletionConfiguration #3 both carry input tokens;
@@ -204,33 +233,50 @@ function resolveDevinMaxInputTokens(
   modelUid: string,
   liveWindow?: number,
 ): number | undefined {
-  const positive = (value: unknown): number | undefined =>
-    typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
-  const baseId = collapseDevinModelUid(modelUid);
-  const configured = (record: Record<string, number> | undefined): number | undefined => {
-    if (!record) return undefined;
-    for (const id of [modelUid, baseId]) {
-      // Prefer the canonical spelling; retain dotted/case-folded saved hints,
-      // matching the model-id normalization used for the inference request.
-      const exact = Object.hasOwn(record, id) ? positive(record[id]) : undefined;
-      if (exact !== undefined) return exact;
-      const matches = Object.entries(record)
-        .filter(([key]) => normalizeDevinModelId(key).toLowerCase() === id.toLowerCase())
-        .map(([, value]) => positive(value))
-        .filter((value): value is number => value !== undefined);
-      if (matches.length > 0) return Math.min(...matches);
-    }
-    return undefined;
-  };
-  const contextHint = configured(provider.modelContextWindows) ?? positive(provider.contextWindow);
-  const inputHint = configured(provider.modelMaxInputTokens);
-  const ceilings = [positive(liveWindow), contextHint, inputHint]
+  const contextHint = devinModelTokenHint(provider.modelContextWindows, modelUid)
+    ?? positiveTokenCount(provider.contextWindow);
+  const inputHint = devinModelTokenHint(provider.modelMaxInputTokens, modelUid);
+  const ceilings = [positiveTokenCount(liveWindow), contextHint, inputHint]
     .filter((value): value is number => value !== undefined);
   return ceilings.length > 0 ? Math.min(...ceilings) : undefined;
 }
 
-/** Pure test seam; runtime uses the same resolver immediately before dispatch. */
+/**
+ * Resolve the OUTPUT ceiling for this turn, highest authority first:
+ *
+ * 1. the caller's explicit `max_output_tokens`, forwarded unchanged — an
+ *    explicit cap is a request, so a small one is never widened into a
+ *    configured larger one;
+ * 2. the configured per-model cap (`modelMaxOutputTokens`), read through the
+ *    same UID-aware hint lookup the input ceiling uses;
+ * 3. the provider-wide `defaultMaxOutputTokens`;
+ * 4. undefined, which leaves the cloud-direct encoder's own 8192 fallback in
+ *    place for a provider that configured nothing.
+ *
+ * This is NOT the history ceiling, and the two must not collapse into one
+ * number. CompletionConfiguration #2 is the output cap and #3 is the context
+ * window, so feeding a context window into this resolver would ask Cognition to
+ * generate a whole window's worth of output. Nothing here reads
+ * `contextWindow` or `modelContextWindows` for that reason.
+ *
+ * Step 1 keeps the caller's raw value rather than `positiveTokenCount`: the
+ * inbound parser owns what a caller may send, and re-filtering here would
+ * silently promote a rejected value to a configured cap the caller never asked
+ * for.
+ */
+function resolveDevinMaxOutputTokens(
+  provider: OcxProviderConfig,
+  modelUid: string,
+  requested: number | undefined,
+): number | undefined {
+  if (typeof requested === "number") return requested;
+  return devinModelTokenHint(provider.modelMaxOutputTokens, modelUid)
+    ?? positiveTokenCount(provider.defaultMaxOutputTokens);
+}
+
+/** Pure test seams; runtime uses the same resolvers immediately before dispatch. */
 export const resolveDevinMaxInputTokensForTests = resolveDevinMaxInputTokens;
+export const resolveDevinMaxOutputTokensForTests = resolveDevinMaxOutputTokens;
 
 export class DevinMissingCredentialError extends Error {
   constructor() {
@@ -285,6 +331,9 @@ function mapOcxContentToWire(content: string | OcxContentPart[] | undefined): st
   for (const part of content) {
     if (part.type === "text" && part.text) {
       out.push({ type: "text", text: part.text });
+    } else if (part.type === "document") {
+      // No Devin document field; the marker keeps the turn from disappearing entirely.
+      out.push({ type: "text", text: part.text });
     } else if (part.type === "image") {
       const m = part.imageUrl.match(/^data:([^;]+);base64,(.+)$/);
       if (m) out.push({ type: "image", mimeType: m[1]!, base64Data: m[2]! });
@@ -590,6 +639,9 @@ export function createDevinAdapter(
         const maxInputTokens = resolveDevinMaxInputTokens(
           provider, modelUid, catalog?.byUid.get(modelUid)?.contextWindow,
         );
+        const maxOutputTokens = resolveDevinMaxOutputTokens(
+          provider, modelUid, parsed.options.maxOutputTokens,
+        );
         // The reset-retry wrapper waits out a 429 that states its own recovery
         // delay ("limit will reset in 35 seconds") and replays the identical
         // request — but only while zero events have been yielded, so a
@@ -606,7 +658,7 @@ export function createDevinAdapter(
           // input hint used to force every model through the 128k default.
           completionOpts: {
             ...(maxInputTokens !== undefined ? { maxInputTokens } : {}),
-            ...(typeof parsed.options.maxOutputTokens === "number" ? { maxOutputTokens: parsed.options.maxOutputTokens } : {}),
+            ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
             ...(typeof parsed.options.temperature === "number" ? { temperature: parsed.options.temperature } : {}),
             ...(typeof parsed.options.topP === "number" ? { topP: parsed.options.topP } : {}),
           },
diff --git a/src/adapters/google-antigravity-wire.ts b/src/adapters/google-antigravity-wire.ts
index a40703f8377..223d95293e4 100644
--- a/src/adapters/google-antigravity-wire.ts
+++ b/src/adapters/google-antigravity-wire.ts
@@ -45,8 +45,11 @@ function firstUserText(parsed: OcxParsedRequest): string | undefined {
   for (const msg of parsed.context.messages) {
     if (msg.role !== "user") continue;
     if (typeof msg.content === "string") return msg.content;
-    const first = (msg.content as OcxContentPart[]).find(p => p.type === "text" && typeof p.text === "string");
-    if (first && first.type === "text") return first.text;
+    // A document part carries text too: ignoring it left a document-only opening turn with no
+    // anchor, which silently downgrades the deterministic session id to a random one.
+    const first = (msg.content as OcxContentPart[])
+      .find(p => (p.type === "text" || p.type === "document") && typeof p.text === "string");
+    if (first && (first.type === "text" || first.type === "document")) return first.text;
   }
   return undefined;
 }
diff --git a/src/adapters/google.ts b/src/adapters/google.ts
index 1e8631ae645..a82c240a1d9 100644
--- a/src/adapters/google.ts
+++ b/src/adapters/google.ts
@@ -15,6 +15,7 @@ import type {
   OcxUsage,
 } from "../types";
 import { isAllowedToolChoice, namespacedToolName, resolveToolChoiceWireName, toolChoiceToolPredicate } from "../types";
+import type { OcxTool } from "../types";
 import { contentPartsToText, parseDataUrl } from "./image";
 import { getVertexAccessToken } from "../lib/gcp-adc";
 import { fetchAntigravityWithRetry, fetchVertexWithRetry } from "./google-http";
@@ -346,6 +347,13 @@ function messagesToGeminiFormat(
               parts.push(data ? { inline_data: { mime_type: data.mediaType, data: data.base64 } } : { text: `[video: ${p.videoUrl}]` });
               continue;
             }
+            if (p.type === "document") {
+              // Gemini takes document bytes through the same inline_data part as images and
+              // video. The marker on the part is the fallback for wires without one, not this
+              // wire's best effort (#5212).
+              parts.push({ inline_data: { mime_type: p.mediaType, data: p.data } });
+              continue;
+            }
             // Drop empty/malformed text instead of emitting `{ text: "" }` or a bare `{}` part.
             const textPart = geminiTextPart(p.text);
             if (textPart) parts.push(textPart);
@@ -465,9 +473,7 @@ function messagesToGeminiFormat(
 
 function toolsToGeminiFormat(parsed: OcxParsedRequest): unknown[] | undefined {
   if (!parsed.context.tools?.length) return undefined;
-  const tools = isAllowedToolChoice(parsed.options.toolChoice)
-    ? parsed.context.tools.filter(toolChoiceToolPredicate(parsed.options.toolChoice, parsed.context.tools))
-    : parsed.context.tools;
+  const tools = advertisedGeminiTools(parsed);
   if (tools.length === 0) return undefined;
   return [{
     functionDeclarations: tools.map(t => ({
@@ -478,19 +484,37 @@ function toolsToGeminiFormat(parsed: OcxParsedRequest): unknown[] | undefined {
   }];
 }
 
+/** The declarations this request actually advertises, after any allowed-tools filter. */
+function advertisedGeminiTools(parsed: OcxParsedRequest): readonly OcxTool[] {
+  const declared = parsed.context.tools ?? [];
+  return isAllowedToolChoice(parsed.options.toolChoice)
+    ? declared.filter(toolChoiceToolPredicate(parsed.options.toolChoice, declared))
+    : declared;
+}
+
 /**
  * Client tool_choice enforcement on the wire. The catalog nudge states the same contract in
  * prose, but without functionCallingConfig the model is free to ignore it. "auto" stays absent
  * so the common case is byte-identical. The allowedTools variant already filters the
  * declarations in toolsToGeminiFormat; only its "required" half needs a wire mode.
+ *
+ * A caller that declares strict tools is asking for its argument schemas to be enforced, and
+ * Gemini expresses that as VALIDATED. The mode existed and was plumbed end to end, but was only
+ * ever reachable by matching a model name, so a strict declaration arrived as an ordinary
+ * unvalidated AUTO turn and the response looked the same either way (#5210). VALIDATED replaces
+ * AUTO only: ANY and NONE are stronger constraints the caller asked for explicitly, and
+ * overwriting either of them would lose the choice this function exists to enforce.
  */
 function toolChoiceToGeminiToolConfig(parsed: OcxParsedRequest): Record<string, unknown> | undefined {
   const choice = parsed.options.toolChoice;
-  if (!choice || choice === "auto") return undefined;
+  const validated = advertisedGeminiTools(parsed).some(t => t.strict === true)
+    ? { functionCallingConfig: { mode: "VALIDATED" } }
+    : undefined;
+  if (!choice || choice === "auto") return validated;
   if (choice === "none") return { functionCallingConfig: { mode: "NONE" } };
   if (choice === "required") return { functionCallingConfig: { mode: "ANY" } };
   if (isAllowedToolChoice(choice)) {
-    return choice.mode === "required" ? { functionCallingConfig: { mode: "ANY" } } : undefined;
+    return choice.mode === "required" ? { functionCallingConfig: { mode: "ANY" } } : validated;
   }
   return {
     functionCallingConfig: {
diff --git a/src/adapters/image.ts b/src/adapters/image.ts
index 39c5d683e50..1a6569fb0f4 100644
--- a/src/adapters/image.ts
+++ b/src/adapters/image.ts
@@ -18,6 +18,9 @@ export function parseDataUrl(url: string): { mediaType: string; base64: string }
  */
 export function contentPartsToText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
-  const text = content.map(p => p.type === "text" ? p.text : p.type === "image" ? "[image]" : "[video]").join("");
+  // A document carries its own marker, so this wire states the attachment instead of
+  // mislabelling it as a video.
+  const text = content.map(p =>
+    p.type === "text" || p.type === "document" ? p.text : p.type === "image" ? "[image]" : "[video]").join("");
   return text || "[image]";
 }
diff --git a/src/adapters/input-media-guard.ts b/src/adapters/input-media-guard.ts
index ad8f468a95b..96c554782d1 100644
--- a/src/adapters/input-media-guard.ts
+++ b/src/adapters/input-media-guard.ts
@@ -1,31 +1,45 @@
 import type { ProviderAdapter } from "./base";
 import { untranslatedInputMediaMessage, untranslatedResponsesInputMedia } from "../responses/input-media";
+import { unrepresentableDeclaration } from "./declaration-carrier";
+import type { AdapterWire } from "./registry";
+import type { OcxParsedRequest } from "../types";
 
 /**
  * Refuse unrepresentable input at the final translated-adapter boundary. The registry
  * applies this after wire resolution; Responses passthrough (including Azure) opts
  * out because it uses the original body rather than the lossy normalized content.
+ *
+ * Two of the three checks are wire-scoped, and that is the point. A constraint the normalized
+ * request CAN carry — a caller restriction on a tool, an attached document's bytes — still has
+ * to reach a wire that can express it. Leaving that to each adapter means an adapter that never
+ * learned about the carrier rebuilds without it and answers normally, so the allowlist in
+ * `declaration-carrier.ts` is default-deny and this is the one place every registered adapter
+ * passes through.
  */
-export function withInputMediaGuard<T extends ProviderAdapter>(adapter: T): T {
+export function withInputMediaGuard<T extends ProviderAdapter>(adapter: T, wire: AdapterWire): T {
+  const refusal = (parsed: OcxParsedRequest): string | undefined => {
+    const kind = untranslatedResponsesInputMedia(parsed._rawBody);
+    return kind ? untranslatedInputMediaMessage(kind) : unrepresentableDeclaration(parsed, wire);
+  };
   const build = adapter.buildRequest.bind(adapter);
   adapter.buildRequest = (parsed, incoming) => {
-    const kind = untranslatedResponsesInputMedia(parsed._rawBody);
-    if (kind) throw new Error(untranslatedInputMediaMessage(kind));
+    const message = refusal(parsed);
+    if (message) throw new Error(message);
     return build(parsed, incoming);
   };
 
   const runTurn = adapter.runTurn?.bind(adapter);
   if (runTurn) {
     adapter.runTurn = async (parsed, incoming, emit) => {
-      const kind = untranslatedResponsesInputMedia(parsed._rawBody);
-      if (kind) {
+      const message = refusal(parsed);
+      if (message) {
         emit({
           type: "error",
           status: 400,
           errorType: "invalid_request_error",
           code: "unsupported_input_modality",
           retryable: false,
-          message: untranslatedInputMediaMessage(kind),
+          message,
         });
         return;
       }
@@ -37,9 +51,7 @@ export function withInputMediaGuard<T extends ProviderAdapter>(adapter: T): T {
   if (localTerminal) {
     // This hook is outside the builder's error catch. Decline its success shortcut;
     // the ordinary buildRequest path then returns the established client-safe 400.
-    adapter.localTerminal = parsed => untranslatedResponsesInputMedia(parsed._rawBody)
-      ? undefined
-      : localTerminal(parsed);
+    adapter.localTerminal = parsed => refusal(parsed) ? undefined : localTerminal(parsed);
   }
   return adapter;
 }
diff --git a/src/adapters/kiro-tool-fallback.ts b/src/adapters/kiro-tool-fallback.ts
index 1164277368a..24c917f2853 100644
--- a/src/adapters/kiro-tool-fallback.ts
+++ b/src/adapters/kiro-tool-fallback.ts
@@ -9,7 +9,7 @@ function contentText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
   return content
     .map(part => {
-      if (part.type === "text") return part.text;
+      if (part.type === "text" || part.type === "document") return part.text;
       if (part.type === "image") return `[image:${part.detail ?? "auto"}]`;
       return "";
     })
diff --git a/src/adapters/kiro/usage.ts b/src/adapters/kiro/usage.ts
index 5f417b57295..3bb8f2b0ffe 100644
--- a/src/adapters/kiro/usage.ts
+++ b/src/adapters/kiro/usage.ts
@@ -12,14 +12,15 @@ import type { KiroHistoryEntry } from "./wire";
 
 export function userContentText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
-  return content.map(p => (p.type === "text" ? p.text : "")).filter(Boolean).join("\n");
+  // A document carries its own marker: dropping it built an empty user turn that Kiro rejects.
+  return content.map(p => (p.type === "text" || p.type === "document" ? p.text : "")).filter(Boolean).join("\n");
 }
 
 export function usageContentText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
   return content
     .map(p => {
-      if (p.type === "text") return p.text;
+      if (p.type === "text" || p.type === "document") return p.text;
       if (p.type === "image") return `[image:${p.detail ?? "auto"}]`;
       return "";
     })
diff --git a/src/adapters/ollama-native.ts b/src/adapters/ollama-native.ts
index c78f154d49d..726fe55ad49 100644
--- a/src/adapters/ollama-native.ts
+++ b/src/adapters/ollama-native.ts
@@ -262,6 +262,12 @@ function contentToNative(
       text += part.text;
       continue;
     }
+    // No Ollama document carrier: keep the marker rather than falling through to the image
+    // branch below, which would read a nonexistent imageUrl.
+    if (part.type === "document") {
+      text += part.text;
+      continue;
+    }
     // Ollama's native /api/chat message shape carries `images: string[]` and has no video
     // counterpart, so a video part is refused rather than silently dropped or mis-sent as an image.
     if (part.type === "video") throw new Error(`ollama-native cannot send video content in ${label}`);
diff --git a/src/adapters/openai-chat.ts b/src/adapters/openai-chat.ts
index 633c693c7ff..98ba27cd203 100644
--- a/src/adapters/openai-chat.ts
+++ b/src/adapters/openai-chat.ts
@@ -1,4 +1,6 @@
 import { hasShrinkableOpenAIChatImages, normalizeOpenAIChatImages } from "./openai-chat-images";
+import { chatParallelToolCallsWireValue } from "./openai-chat/parallel-tool-calls";
+import { applyExplicitChatReasoningWirePolicy } from "./openai-chat/reasoning-wire";
 import type { AdapterRequest, IncomingMeta, ProviderAdapter } from "./base";
 import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig, OcxUsage } from "../types";
 import { modelInList } from "../types";
@@ -40,7 +42,7 @@ import {
 } from "./openai-chat/errors";
 import { messagesToChatFormat } from "./openai-chat/messages";
 import { withOpenAIChatToolNames } from "./openai-chat/tool-name-registry";
-import { isNativeOpenAIChatTarget, openAIChatTransport, stripBracketedModelSuffix } from "./openai-chat/wire";
+import { openAIChatTransport, stripBracketedModelSuffix } from "./openai-chat/wire";
 import { toolChoiceToChatFormat, toolsToChatFormatForProvider } from "./openai-chat/tool-schema";
 
 export { stripBracketedModelSuffix } from "./openai-chat/wire";
@@ -142,51 +144,21 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         }
         if (parsed.options.stopSequences !== undefined) body.stop = parsed.options.stopSequences;
         const reasoningDisabled = modelInList(provider.noReasoningModels, parsed.modelId);
-        // Some gateways accept a reasoning-effort field on a plain turn but reject the
-        // effort + tools combination. `noReasoningModels` would fix that only by
-        // stripping reasoning everywhere, costing the model its whole picker. This keeps
-        // the ladder advertised and drops the wire field for tool-bearing requests only.
-        const omitReasoningEffortWithTools = !!tools
-          && modelInList(provider.omitReasoningEffortWithToolsModels, parsed.modelId);
-        const reasoningEffort = omitReasoningEffortWithTools
-          ? undefined
-          : mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning);
-        const nativeOpenAI = isNativeOpenAIChatTarget(provider);
+        const reasoningEffort = mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning);
+        const explicitReasoning = applyExplicitChatReasoningWirePolicy({
+          provider,
+          modelId: parsed.modelId,
+          hasTools: !!tools,
+          requestedEffort: parsed.options.reasoning,
+          wireEffort: reasoningEffort,
+          reasoningDisabled,
+          body,
+        });
         let reasoningLog: AdapterRequest["reasoningLog"];
-        if (!reasoningDisabled && !omitReasoningEffortWithTools && provider.reasoningWireFormat === "gateway-object" && parsed.options.reasoning === "none") {
-          if (nativeOpenAI) {
-            body.reasoning_effort = "none";
-            reasoningLog = {
-              effectiveEffort: "none",
-              wireField: "reasoning_effort",
-              wireValue: "none",
-            };
-          } else {
-            body.reasoning = { enabled: false };
-            reasoningLog = {
-              effectiveEffort: "none",
-              wireField: "reasoning.enabled",
-              wireValue: false,
-            };
-          }
+        if (explicitReasoning.handled) {
+          reasoningLog = explicitReasoning.reasoningLog;
         } else if (reasoningEffort !== undefined) {
-          if (provider.reasoningWireFormat === "gateway-object") {
-            if (nativeOpenAI) {
-              body.reasoning_effort = reasoningEffort;
-              reasoningLog = {
-                effectiveEffort: reasoningEffort,
-                wireField: "reasoning_effort",
-                wireValue: reasoningEffort,
-              };
-            } else {
-              body.reasoning = { enabled: true, effort: reasoningEffort };
-              reasoningLog = {
-                effectiveEffort: reasoningEffort,
-                wireField: "reasoning.effort",
-                wireValue: reasoningEffort,
-              };
-            }
-          } else if (modelInList(provider.thinkingBudgetModels, parsed.modelId)) {
+          if (modelInList(provider.thinkingBudgetModels, parsed.modelId)) {
             const budget = thinkingBudgetForEffort(parsed, reasoningEffort, maxTokens);
             if (budget !== undefined) {
               body.thinking_budget = budget;
@@ -249,19 +221,8 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         }
 
         if (tools) {
-          if (provider.parallelToolCalls === false) {
-            // NIM documents the Boolean defaulting to false and kimi rejects true; pin the
-            // wire bit so Codex cannot opt in via request.options. Other opted-out providers
-            // omit the field by default so strict OpenAI-compatible hosts never see an
-            // unsupported knob, but a self-hosted gateway that DOES honor the field and keeps
-            // emitting parallel calls without it can opt in via pinParallelToolCallsFalse.
-            if (provider.baseUrl === "https://integrate.api.nvidia.com/v1"
-                || provider.pinParallelToolCallsFalse === true) {
-              body.parallel_tool_calls = false;
-            }
-          } else if (provider.parallelToolCalls === true) {
-            body.parallel_tool_calls = parsed.options.parallelToolCalls !== false;
-          }
+          const parallelToolCalls = chatParallelToolCallsWireValue(provider, parsed.options.parallelToolCalls);
+          if (parallelToolCalls !== undefined) body.parallel_tool_calls = parallelToolCalls;
         }
         if (parsed.stream) body.stream_options = { include_usage: true };
 
diff --git a/src/adapters/openai-chat/developer-role.ts b/src/adapters/openai-chat/developer-role.ts
new file mode 100644
index 00000000000..3b2481b166a
--- /dev/null
+++ b/src/adapters/openai-chat/developer-role.ts
@@ -0,0 +1,61 @@
+import type { OcxProviderConfig } from "../../types";
+
+/**
+ * The role a `developer` message carries on the Chat wire, decided in one place for both the
+ * translated adapter and the native passthrough.
+ *
+ * `developer` belongs to the Chat Completions role set, but not every OpenAI-compatible gateway
+ * accepts it: one that does not answers `400 role 'developer' is not allowed` and the turn never
+ * starts. #5213 removed a hostname test that decided the role, which was right — a gateway
+ * proxying OpenAI accepts the role and the hostname cannot say so.
+ *
+ * `foldDeveloperRoleToSystem` is tri-state and only two of its states say anything about the
+ * destination: `true` records an upstream known to reject the role, `false` one known to accept
+ * it, and absent means nobody has recorded either. Returning `undefined` for the absent state
+ * instead of a role keeps the recorded fact separate from the default a route applies to
+ * silence, which is what lets the native route honour the first without inheriting the second.
+ *
+ * This decides the role and only the role. Which slot the message occupies is the caller's
+ * decision and must not change with this value.
+ */
+export function explicitChatDeveloperWireRole(
+  provider: OcxProviderConfig,
+): "developer" | "system" | undefined {
+  if (provider.foldDeveloperRoleToSystem === undefined) return undefined;
+  return provider.foldDeveloperRoleToSystem ? "system" : "developer";
+}
+
+/**
+ * The translated route's role: the recorded one, or `system` when nothing is recorded.
+ *
+ * The unrecorded state folds because the two mistakes are not symmetrical. Sending `developer`
+ * to a destination that rejects it fails the request outside this repository, where no test here
+ * can reach it; sending `system` to one that would have accepted `developer` costs the role name
+ * and nothing else.
+ */
+export function translatedChatDeveloperWireRole(provider: OcxProviderConfig): "developer" | "system" {
+  return explicitChatDeveloperWireRole(provider) ?? "system";
+}
+
+/**
+ * Apply a recorded role to a caller-supplied `messages` array, leaving every other field of
+ * every message, and the order of all of them, exactly as they arrived.
+ *
+ * The native route forwards the caller's messages verbatim, so an operator who recorded that a
+ * destination rejects the role still sent `developer` there and the turn failed upstream with a
+ * 400. Only an explicit record changes anything here: with the key unset, or set to the role the
+ * message already carries, the same array reference is returned and the wire is byte-identical
+ * to the one the caller sent.
+ */
+export function applyExplicitChatDeveloperRole(messages: unknown, provider: OcxProviderConfig): unknown {
+  const role = explicitChatDeveloperWireRole(provider);
+  if (role === undefined || role === "developer" || !Array.isArray(messages)) return messages;
+  let rewritten = false;
+  const applied = messages.map(message => {
+    if (typeof message !== "object" || message === null || Array.isArray(message)) return message;
+    if ((message as { role?: unknown }).role !== "developer") return message;
+    rewritten = true;
+    return { ...(message as Record<string, unknown>), role };
+  });
+  return rewritten ? applied : messages;
+}
diff --git a/src/adapters/openai-chat/messages.ts b/src/adapters/openai-chat/messages.ts
index 8e88dabc6b0..9ad0dec86f8 100644
--- a/src/adapters/openai-chat/messages.ts
+++ b/src/adapters/openai-chat/messages.ts
@@ -1,13 +1,14 @@
 import { isNativeOpenAIChatTarget, stripBracketedModelSuffix } from "./wire";
 import { reasoningDetailSegmentForWire } from "./response-events";
+import { translatedChatDeveloperWireRole } from "./developer-role";
 import { isVolcengineArkPaygChatTarget } from "./tool-schema";
 import { contentPartsToText } from "../image";
 import { EMPTY_TOOL_OUTPUT_ANNOTATION, isWhitespaceOnlyTextPartArray } from "../empty-tool-output-annotation";
 import { identifyRoutedModel } from "../identity";
 import { buildNonOpenAIToolCatalogNudgeForTools, shouldInjectNonOpenAIToolCatalogNudge } from "../tool-catalog-nudge";
-import { registryEntryForProviderDestination } from "../../providers/registry";
 import { peekReasoningForCall } from "../../responses/reasoning-replay-cache";
-import type { OcxAssistantMessage, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent, OcxThinkingContent, OcxToolCall } from "../../types";
+import { inlineDocumentDataUrl } from "../../responses/inline-document";
+import type { OcxAssistantMessage, OcxContentPart, OcxParsedRequest, OcxProviderConfig, OcxTextContent, OcxThinkingContent, OcxToolCall } from "../../types";
 import { modelInList, namespacedToolName } from "../../types";
 
 /**
@@ -21,13 +22,6 @@ import { modelInList, namespacedToolName } from "../../types";
  */
 const VIDEO_UNSUPPORTED_MARKER = "[video omitted: the translated Chat route has no video mapping]";
 
-export function developerSystemText(message: OcxMessage): string | undefined {
-  if (message.role !== "developer") return undefined;
-  if (typeof message.content === "string") return message.content;
-  if (message.content.some(part => part.type === "image")) return undefined;
-  return message.content.map(part => (part as OcxTextContent).text).join("");
-}
-
 /**
  * Chat-completions image_url parts for images carried inside a tool result (issue #888). role:"tool"
  * content is text-only on every chat provider, so these ride in a follow-up user message instead of
@@ -121,21 +115,26 @@ export function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProv
   };
 
   const nativeOpenAI = isNativeOpenAIChatTarget(provider);
-  // Hoisting a newly appended reminder rewrites the reusable prompt prefix.
-  // Keep this compatibility exception on the destination/model tested with OCG.
-  const chronologicalSystem = parsed.modelId === "deepseek-v4.1-flash"
-    && registryEntryForProviderDestination(provider)?.id === "opencode-go";
+  // Which role a developer message carries, and why the unrecorded state folds, is stated once
+  // in ./developer-role.ts and read from there by the native passthrough as well. Either way the
+  // message keeps the slot it arrived in — only the role changes, never the position.
+  const developerWireRole = translatedChatDeveloperWireRole(provider);
+  // A developer message keeps the slot it arrived in. Hoisting its text into the leading
+  // system block moved a mid-conversation instruction ahead of every turn it was written to
+  // follow, and the caller saw an ordinary answer either way (#5213). The Claude inbound mints
+  // chronological developer items for exactly this reason (#4161), so the two halves of the
+  // route were working against each other on every host but api.openai.com. Placement is now
+  // uniform; which ROLE that slot carries is decided separately below.
+  //
+  // One destination already had the chronological behaviour, keyed to a model and a registry
+  // id, because hoisting a newly appended reminder rewrites the reusable prompt prefix. That is
+  // a property of prompt-prefix caching rather than of that destination, and it is now what
+  // every destination gets.
   const toolCatalogNudge = shouldInjectNonOpenAIToolCatalogNudge(provider)
     ? buildNonOpenAIToolCatalogNudgeForTools(context.tools, options.toolChoice)
     : undefined;
-  const developerSystemParts = nativeOpenAI || chronologicalSystem
-    ? []
-    : context.messages
-      .map(developerSystemText)
-      .filter((part): part is string => part !== undefined && part.length > 0);
   const systemParts = [
     ...(context.systemPrompt ?? []),
-    ...developerSystemParts,
     ...(toolCatalogNudge ? [toolCatalogNudge] : []),
   ];
   if (systemParts.length > 0) {
@@ -152,20 +151,23 @@ export function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProv
       case "developer": {
         const parts = typeof msg.content === "string" ? undefined : msg.content as OcxContentPart[];
         const hasImages = parts?.some(p => p.type === "image") ?? false;
+        // A document has a structured counterpart on this wire, so it needs the parts array for
+        // the same reason an image does: flattening it to a string would drop the bytes.
+        const hasStructured = hasImages || (parts?.some(p => p.type === "document") ?? false);
         let chatMsg: Record<string, unknown>;
-        if (msg.role === "developer" && !hasImages) {
-          if (!nativeOpenAI && !chronologicalSystem) break;
+        if (msg.role === "developer" && !hasStructured) {
           const text = typeof msg.content === "string"
             ? msg.content
             : parts!.map(p => (p as OcxTextContent).text).join("");
-          // A non-text timeline part (video, for example) serializes to nothing here.
-          // The generic path drops such a message; the chronological exception must not
-          // turn it into an empty system message that some upstreams reject.
+          // A non-text timeline part (video, for example) serializes to nothing here. The
+          // generic user path drops such a message, and emitting a content-free system
+          // message instead is rejected by some upstreams. Native OpenAI keeps its existing
+          // empty-developer wire, which is a separate question from placement.
           if (!nativeOpenAI && text.length === 0) break;
-          chatMsg = { role: nativeOpenAI ? "developer" : "system", content: text };
+          chatMsg = { role: developerWireRole, content: text };
         } else if (typeof msg.content === "string") {
           chatMsg = { role: "user", content: msg.content };
-        } else if (!hasImages) {
+        } else if (!hasStructured) {
           // A video part has no `text`, so joining it produced "" and the whole message
           // was dropped: a video-only or text-plus-video turn vanished silently. OpenAI's
           // Chat Completions wire has no video content part, so state the omission
@@ -183,13 +185,30 @@ export function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProv
             if (p.type === "image") {
               return { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } };
             }
+            // Chat Completions carries an attached document as a file part with inline bytes,
+            // the direct counterpart of the Anthropic document block the caller sent.
+            if (p.type === "document") {
+              return {
+                type: "file",
+                file: {
+                  file_data: inlineDocumentDataUrl(p),
+                  ...(p.filename !== undefined ? { filename: p.filename } : {}),
+                },
+              };
+            }
             // Previously this produced { type: "text", text: undefined } for a video
             // part — a malformed part, worse than a drop because it can fail upstream
             // schema validation.
             if (p.type === "video") return { type: "text", text: VIDEO_UNSUPPORTED_MARKER };
             return { type: "text", text: (p as OcxTextContent).text };
           });
-          chatMsg = { role: "user", content: chatParts };
+          // A developer message with images keeps the user-compatible shape it has always had on
+          // this wire. One carrying only a document has no such precedent, and demoting it would
+          // undo the role this adapter just finished preserving.
+          chatMsg = {
+            role: msg.role === "developer" && !hasImages ? developerWireRole : "user",
+            content: chatParts,
+          };
         }
         if (pendingToolCalls.length > 0) deferredBarrierMessages.push(chatMsg);
         else out.push(chatMsg);
diff --git a/src/adapters/openai-chat/parallel-tool-calls.ts b/src/adapters/openai-chat/parallel-tool-calls.ts
new file mode 100644
index 00000000000..89d6e4326f2
--- /dev/null
+++ b/src/adapters/openai-chat/parallel-tool-calls.ts
@@ -0,0 +1,32 @@
+import type { OcxProviderConfig } from "../../types";
+
+/**
+ * The `parallel_tool_calls` value for a translated Chat request, or `undefined` to omit the key.
+ *
+ * A provider has three states here, not two, and the third is the default for every provider that
+ * never configured the knob. While the call site only branched on the two configured states, a
+ * caller's own explicit `parallel_tool_calls: false` reached the parser, was carried on
+ * `options.parallelToolCalls`, and was then dropped on the way to the wire — the upstream stayed
+ * free to emit concurrent calls and the response looked entirely normal (#5211).
+ *
+ * Only an explicit request-side `false` is forwarded in the unset state. `true` is already the
+ * upstream default, so emitting it would introduce the knob to strict OpenAI-compatible hosts
+ * that have never had to accept it, which is the reason the configured opt-out below omits the
+ * key rather than sending `false`.
+ */
+export function chatParallelToolCallsWireValue(
+  provider: OcxProviderConfig,
+  requested: boolean | undefined,
+): boolean | undefined {
+  if (provider.parallelToolCalls === false) {
+    // NIM documents the Boolean defaulting to false and kimi rejects true; pin the wire bit so
+    // Codex cannot opt in via request.options. Other opted-out providers omit the field, but a
+    // self-hosted gateway that DOES honor it and keeps emitting parallel calls without it can opt
+    // in via pinParallelToolCallsFalse.
+    const pinned = provider.baseUrl === "https://integrate.api.nvidia.com/v1"
+      || provider.pinParallelToolCallsFalse === true;
+    return pinned ? false : undefined;
+  }
+  if (provider.parallelToolCalls === true) return requested !== false;
+  return requested === false ? false : undefined;
+}
diff --git a/src/adapters/openai-chat/passthrough.ts b/src/adapters/openai-chat/passthrough.ts
index f7682b7a62d..16abcf08d83 100644
--- a/src/adapters/openai-chat/passthrough.ts
+++ b/src/adapters/openai-chat/passthrough.ts
@@ -1,6 +1,7 @@
 import { openAIChatTransport, stripBracketedModelSuffix } from "./wire";
 import type { AdapterRequest } from "../base";
 import { frameAgentRouterMessages } from "../agentrouter";
+import { applyExplicitChatDeveloperRole } from "./developer-role";
 import { openRouterProviderPayload, resolveOpenRouterRouting } from "../../providers/openrouter-routing";
 import { resolveVercelGatewayRouting, vercelGatewayProviderPayload } from "../../providers/vercel-gateway-routing";
 import { fastPolicyForModel } from "../../providers/service-tier";
@@ -9,6 +10,8 @@ import { debugProviderDiagnostic } from "../../lib/debug";
 import { isDebugEnabled } from "../../lib/debug-settings";
 import { modelRecordValue } from "../../reasoning-effort";
 import { modelInList, type OcxProviderConfig } from "../../types";
+import { chatParallelToolCallsWireValue } from "./parallel-tool-calls";
+import { applyExplicitChatReasoningWirePolicy } from "./reasoning-wire";
 
 const CHAT_PASSTHROUGH_FIELDS = [
   "audio",
@@ -54,16 +57,37 @@ export function buildOpenAIChatPassthroughRequest(
 
   const body: Record<string, unknown> = {
     model: provider.modelSuffixBracketStrip ? stripBracketedModelSuffix(modelId) : modelId,
-    messages: frameAgentRouterMessages(provider.baseUrl, rawBody.messages),
+    // The caller's messages are forwarded as they arrived, with one exception: an operator who
+    // recorded that this destination rejects the `developer` role gets that role converted in
+    // place. Verbatim was not neutral there — it sent the role anyway and the turn failed
+    // upstream with a 400 before the model saw it. An unrecorded destination is still verbatim,
+    // and the conversion changes the role of those messages and nothing else, so the position
+    // of every message and every other field survive unchanged.
+    messages: applyExplicitChatDeveloperRole(
+      frameAgentRouterMessages(provider.baseUrl, rawBody.messages),
+      provider,
+    ),
     stream,
   };
   for (const field of CHAT_PASSTHROUGH_FIELDS) {
     if (rawBody[field] !== undefined) body[field] = rawBody[field];
   }
   const rawEfforts = modelRecordValue(provider.modelReasoningEfforts, modelId) ?? provider.reasoningEfforts;
-  if (modelInList(provider.noReasoningModels, modelId) || rawEfforts?.length === 0) {
+  const reasoningDisabled = modelInList(provider.noReasoningModels, modelId) || rawEfforts?.length === 0;
+  if (reasoningDisabled) {
     delete body.reasoning_effort;
   }
+  const hasTools = Array.isArray(rawBody.tools) && rawBody.tools.length > 0;
+  const requestedEffort = typeof body.reasoning_effort === "string" ? body.reasoning_effort : undefined;
+  applyExplicitChatReasoningWirePolicy({
+    provider,
+    modelId,
+    hasTools,
+    requestedEffort,
+    wireEffort: requestedEffort,
+    reasoningDisabled,
+    body,
+  });
 
   const openRouterRouting = resolveOpenRouterRouting(provider, modelId);
   if (openRouterRouting) body.provider = openRouterProviderPayload(openRouterRouting);
@@ -107,13 +131,13 @@ export function buildOpenAIChatPassthroughRequest(
   if (provider.promptCacheKey && rawBody.prompt_cache_key !== undefined) {
     body.prompt_cache_key = rawBody.prompt_cache_key;
   }
-  if (Array.isArray(rawBody.tools) && rawBody.tools.length > 0) {
-    if (provider.parallelToolCalls === true) {
-      body.parallel_tool_calls = rawBody.parallel_tool_calls !== false;
-    } else if (provider.parallelToolCalls === false
-        && (provider.baseUrl === "https://integrate.api.nvidia.com/v1" || provider.pinParallelToolCallsFalse === true)) {
-      body.parallel_tool_calls = false;
-    }
+  if (hasTools) {
+    // Same three provider states as the translated path, and the same defect in the unset one:
+    // a caller's explicit false was dropped here too (#5211). The native route reads the bit off
+    // the raw request rather than the parsed options, since nothing projects this body.
+    const requested = typeof rawBody.parallel_tool_calls === "boolean" ? rawBody.parallel_tool_calls : undefined;
+    const parallelToolCalls = chatParallelToolCallsWireValue(provider, requested);
+    if (parallelToolCalls !== undefined) body.parallel_tool_calls = parallelToolCalls;
   }
   if (stream) {
     const callerOptions = rawBody.stream_options !== null
diff --git a/src/adapters/openai-chat/reasoning-wire.ts b/src/adapters/openai-chat/reasoning-wire.ts
new file mode 100644
index 00000000000..ac53a242352
--- /dev/null
+++ b/src/adapters/openai-chat/reasoning-wire.ts
@@ -0,0 +1,89 @@
+import { modelInList, type OcxProviderConfig } from "../../types";
+import type { AdapterRequest } from "../base";
+import { isNativeOpenAIChatTarget } from "./wire";
+
+export type ExplicitChatReasoningWireResult =
+  | { handled: false }
+  | { handled: true; reasoningLog?: AdapterRequest["reasoningLog"] };
+
+/**
+ * Apply provider-declared reasoning wire policy after the effective provider is resolved.
+ * Unset declarations are a no-op so native Chat keeps forwarding the caller's raw field.
+ */
+export function applyExplicitChatReasoningWirePolicy(options: {
+  provider: OcxProviderConfig;
+  modelId: string;
+  hasTools: boolean;
+  requestedEffort: string | undefined;
+  wireEffort: string | undefined;
+  reasoningDisabled: boolean;
+  body: Record<string, unknown>;
+}): ExplicitChatReasoningWireResult {
+  const {
+    provider,
+    modelId,
+    hasTools,
+    requestedEffort,
+    wireEffort,
+    reasoningDisabled,
+    body,
+  } = options;
+
+  if (reasoningDisabled) return { handled: false };
+  if (hasTools && modelInList(provider.omitReasoningEffortWithToolsModels, modelId)) {
+    delete body.reasoning_effort;
+    delete body.reasoning;
+    return { handled: true };
+  }
+  if (provider.reasoningWireFormat !== "gateway-object") return { handled: false };
+
+  const nativeOpenAI = isNativeOpenAIChatTarget(provider);
+  if (requestedEffort === "none") {
+    if (nativeOpenAI) {
+      delete body.reasoning;
+      body.reasoning_effort = "none";
+      return {
+        handled: true,
+        reasoningLog: {
+          effectiveEffort: "none",
+          wireField: "reasoning_effort",
+          wireValue: "none",
+        },
+      };
+    }
+    delete body.reasoning_effort;
+    body.reasoning = { enabled: false };
+    return {
+      handled: true,
+      reasoningLog: {
+        effectiveEffort: "none",
+        wireField: "reasoning.enabled",
+        wireValue: false,
+      },
+    };
+  }
+  if (wireEffort === undefined) return { handled: false };
+
+  if (nativeOpenAI) {
+    delete body.reasoning;
+    body.reasoning_effort = wireEffort;
+    return {
+      handled: true,
+      reasoningLog: {
+        effectiveEffort: wireEffort,
+        wireField: "reasoning_effort",
+        wireValue: wireEffort,
+      },
+    };
+  }
+  delete body.reasoning_effort;
+  body.reasoning = { enabled: true, effort: wireEffort };
+  return {
+    handled: true,
+    reasoningLog: {
+      effectiveEffort: wireEffort,
+      wireField: "reasoning.effort",
+      wireValue: wireEffort,
+    },
+  };
+}
diff --git a/src/adapters/openai-responses/passthrough.ts b/src/adapters/openai-responses/passthrough.ts
index 83ce6e1517b..cadcb2a38c2 100644
--- a/src/adapters/openai-responses/passthrough.ts
+++ b/src/adapters/openai-responses/passthrough.ts
@@ -42,6 +42,7 @@ import { bridgeSearchReplayScope } from "../../responses/bridge-search-replay-ca
 import { applyTierDecisionToResponsesBody, normalizeCanonicalForwardContinuationEnvelope, normalizeCanonicalForwardPromptEnvelope, stripCanonicalForwardSamplingParams, stripPreviousResponseId, stripStatefulResponsesParams, stripUnsupportedForwardParams } from "./canonical-forward";
 import { normalizeImageGenClientTools, preferConfiguredHostedTools } from "./image-gen";
 import { stripMuseSparkUnsupportedWebSearchFields, stripOpenAiOnlyWebSearchFields } from "./web-search";
+import { observeOutbound } from "../../usage/cache-diagnostic";
 
 /**
  * Identifies DeepSeek's strict Responses replay contract: tool-bearing continuations need
@@ -501,6 +502,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
       // here, on the serialized body, not on the parsed selector. One place covers both the
       // HTTP and the WebSocket outbound, because the WS path transports this same request
       // instead of rebuilding it.
+      observeOutbound(parsed._rawBody, finalBody, headers);
       const body = JSON.stringify(finalBody);
       const releaseBodyObservation = translatorBudget.observeExternallyCapped(
         "passthrough_serialization",
diff --git a/src/adapters/registry.ts b/src/adapters/registry.ts
index 8d6e8bc63d7..f077f92c2c5 100644
--- a/src/adapters/registry.ts
+++ b/src/adapters/registry.ts
@@ -181,8 +181,9 @@ export function createRegisteredAdapter(
   const definition = getAdapterDefinition(provider.adapter);
   if (!definition) throw new Error(`Unknown adapter: ${provider.adapter}`);
   const adapter = definition.create(provider, context);
-  if (effectiveAdapterContract(provider.adapter).wire !== "openai-responses") {
-    withInputMediaGuard(adapter);
+  const wire = effectiveAdapterContract(provider.adapter).wire;
+  if (wire !== "openai-responses") {
+    withInputMediaGuard(adapter, wire);
   }
   const buildRequest = adapter.buildRequest.bind(adapter);
   adapter.buildRequest = (parsed, incoming) => {
diff --git a/src/adapters/run-turn-queue.ts b/src/adapters/run-turn-queue.ts
index 76024b32662..23c1cd50f18 100644
--- a/src/adapters/run-turn-queue.ts
+++ b/src/adapters/run-turn-queue.ts
@@ -6,11 +6,107 @@ export const PREFLIGHT_HEARTBEAT_RETAIN_LIMIT = 16;
 
 /**
  * Coalescing threshold for adjacent text/thinking deltas buffered with no
- * waiting reader (UTF-16 code units). This is a merge-size ceiling, not a
- * byte-memory cap: a single oversized incoming event stays one item.
+ * waiting reader (UTF-16 code units). This is a merge-size ceiling; the two
+ * retention budgets below are what bound memory.
  */
 export const COALESCE_MAX_CHUNK_LENGTH = 64 * 1024;
 
+/**
+ * Retained-string budget for the WHOLE queue, in UTF-16 code units.
+ *
+ * This bounds what the queue is holding at one moment, not how much a turn
+ * streams: every dequeue gives its charge back, so a long healthy stream with a
+ * consumer attached never accumulates and is never capped by total length.
+ *
+ * 32 MiB is deliberately far above any single legitimate burst. A synchronous
+ * producer can legally fill the queue before its consumer is scheduled — the
+ * image loop does exactly that with over a million one-character deltas, which
+ * coalesce into roughly 1.2 MB of retained text — so a budget near that size
+ * aborts healthy turns rather than stalled ones. The previous effective bound
+ * was the 1024-event cap times the 64 KiB merge ceiling, so 64 MiB; this halves
+ * it while leaving that legitimate burst an order of magnitude of headroom.
+ */
+export const DEFAULT_MAX_BACKLOG_CODE_UNITS = 32 * 1024 * 1024;
+
+/**
+ * Retained-string budget for ONE queued event, in UTF-16 code units.
+ *
+ * Separate from the aggregate on purpose, because the two describe different
+ * failures. Passing the aggregate means the consumer is not keeping up. Passing
+ * this one means a single event is malformed or unbounded, which stays true
+ * however empty the queue is, so it must be refused even with the whole
+ * aggregate free. They also report different terminal messages, so an operator
+ * reading the turn's error learns which happened.
+ *
+ * Like the aggregate, this governs what the queue RETAINS. An event handed
+ * straight to a waiting consumer is never held here, so neither budget applies
+ * to it: refusing it would abort a turn over memory this queue does not own,
+ * and the consumer's own per-event bound governs that payload instead.
+ */
+export const DEFAULT_MAX_EVENT_CODE_UNITS = 8 * 1024 * 1024;
+
+const BACKLOG_EXCEEDED_MESSAGE = "consumer stalled: adapter event backlog exceeded — turn aborted";
+const EVENT_TOO_LARGE_MESSAGE = "adapter event exceeds the single-event retained-string budget — turn aborted";
+
+/**
+ * Bound on how far the retention measure walks into one event. AdapterEvent is
+ * a plain-data union, but two of its members carry open provider-shaped bags
+ * (`providerState`, `usage.rawUsage`) whose depth no type here controls. The
+ * ceilings keep a single push O(1)-ish rather than O(whatever an adapter
+ * attached), and under-counting a pathological object is the safe direction:
+ * the event-count cap still bounds how many of them can be retained.
+ */
+const RETENTION_MAX_DEPTH = 8;
+const RETENTION_MAX_NODES = 4096;
+
+/**
+ * Retained UTF-16 code units carried by one event's string payload.
+ *
+ * Measured by walking own enumerable properties rather than by naming each
+ * variant's string fields: a hand-written per-variant table is exhaustive over
+ * a union, so adding an event type on one branch while a consumer lands on
+ * another produces a measure that silently stops counting the new payload.
+ * The walk is the derived answer and needs no update when the union grows.
+ *
+ * `type` is skipped because it is the discriminant, identical for every event
+ * of a kind and not payload anyone is buffering.
+ */
+export function retainedEventCodeUnits(event: AdapterEvent): number {
+  // Defensive: this measures values an adapter produced. A malformed emission
+  // has to become a terminal event, not a TypeError thrown out of push() with
+  // the queue half-updated.
+  if (!event || typeof event !== "object") return 0;
+  let total = 0;
+  let nodes = 0;
+  const seen = new Set<object>();
+  const visit = (value: unknown, depth: number): void => {
+    if (typeof value === "string") {
+      total += value.length;
+      return;
+    }
+    if (!value || typeof value !== "object" || depth >= RETENTION_MAX_DEPTH || seen.has(value)) return;
+    seen.add(value);
+    for (const nested of Object.values(value)) {
+      if (nodes++ >= RETENTION_MAX_NODES) return;
+      visit(nested, depth + 1);
+    }
+  };
+  for (const [key, value] of Object.entries(event)) {
+    if (key === "type") continue;
+    if (nodes++ >= RETENTION_MAX_NODES) break;
+    visit(value, 1);
+  }
+  return total;
+}
+
+function positiveBudget(value: number | undefined, fallback: number, name: string): number {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+    throw new RangeError(`${name} must be a positive safe integer`);
+  }
+  return resolved;
+}
+
 export interface AdapterEventQueue {
   /**
    * Returns true when the event was merged into the buffered tail instead of
@@ -22,6 +118,13 @@ export interface AdapterEventQueue {
   close(): void;
   stream(): AsyncIterable<AdapterEvent>;
   collect(): Promise<AdapterEvent[]>;
+  /**
+   * Retained string payload the queue is currently holding, in UTF-16 code
+   * units. Exposed so a caller — and a regression — can assert the counter
+   * returns to zero on every terminal path instead of inferring it from an
+   * abort that happened to fire.
+   */
+  retainedCodeUnits(): number;
 }
 
 export interface AdapterEventPreflight {
@@ -73,47 +176,74 @@ export async function preflightAdapterEvents(
 
 export function createAdapterEventQueue(opts?: {
   maxBacklog?: number;
+  maxBacklogCodeUnits?: number;
+  maxEventCodeUnits?: number;
   onBacklogExceeded?: () => void;
 }): AdapterEventQueue {
   const queued: AdapterEvent[] = [];
+  /**
+   * What each queued item was charged, in lockstep with `queued`. Releasing the
+   * recorded charge rather than re-measuring is what makes the accounting exact
+   * on every path: a merge, a terminal record admitted past the budget and a
+   * plain event all give back precisely what they took, so the counter cannot
+   * drift positive (a leak) or negative (a budget the next turn gets for free).
+   */
+  const charged: number[] = [];
   const readers: QueueReader[] = [];
   const maxBacklog = opts?.maxBacklog ?? 1_024;
+  const maxBacklogCodeUnits = positiveBudget(opts?.maxBacklogCodeUnits, DEFAULT_MAX_BACKLOG_CODE_UNITS, "maxBacklogCodeUnits");
+  const maxEventCodeUnits = positiveBudget(opts?.maxEventCodeUnits, DEFAULT_MAX_EVENT_CODE_UNITS, "maxEventCodeUnits");
+  let retained = 0;
   let closed = false;
 
   // Merge an incoming delta into the buffered tail when no reader is waiting.
-  // The backlog cap counts events, not tokens, so a detached or briefly
-  // stalled consumer (e.g. a Codex app mid-reconnect whose disconnect Bun has
-  // not yet delivered) used to hit the cap within seconds of token-granular
-  // streaming and abort a healthy turn. Adjacent same-phase text deltas,
-  // adjacent thinking deltas, and consecutive heartbeats carry no ordering
-  // information between themselves, so merging them preserves every consumer
-  // contract while making the cap approximate buffered items again.
+  // The event cap counts events, not tokens, so a detached or briefly stalled
+  // consumer (e.g. a Codex app mid-reconnect whose disconnect Bun has not yet
+  // delivered) used to hit it within seconds of token-granular streaming and
+  // abort a healthy turn. Adjacent same-phase text deltas, adjacent thinking
+  // deltas, and consecutive heartbeats carry no ordering information between
+  // themselves, so merging them preserves every consumer contract while making
+  // the cap approximate buffered items again.
   // Pushed objects may be retained by adapters, so the tail is REPLACED with
-  // a fresh object — never mutated (alias safety).
-  const coalesceIntoTail = (event: AdapterEvent): boolean => {
-    const tail = queued[queued.length - 1];
-    if (!tail) return false;
+  // a fresh object — never mutated (alias safety). Returning the replacement
+  // instead of installing it lets push price the merge before committing to it.
+  const planTailMerge = (tail: AdapterEvent, event: AdapterEvent): AdapterEvent | null => {
     if (event.type === "heartbeat") {
-      if (tail.type !== "heartbeat") return false;
+      if (tail.type !== "heartbeat") return null;
       // Heartbeats carry no ordering between themselves, but the replay-unsafe
       // marker is not ordering — it is a latch. Dropping the incoming event
       // would discard the only record that Cursor already performed a local
       // side effect, and preflight would then permit an OAuth replay of it.
       if (event.replayUnsafe === true && tail.replayUnsafe !== true) {
-        queued[queued.length - 1] = { type: "heartbeat", replayUnsafe: true };
+        return { type: "heartbeat", replayUnsafe: true };
       }
-      return true;
+      return tail;
     }
     if (event.type === "text_delta" && tail.type === "text_delta" && tail.phase === event.phase) {
-      if (tail.text.length + event.text.length > COALESCE_MAX_CHUNK_LENGTH) return false;
-      queued[queued.length - 1] = { type: "text_delta", text: tail.text + event.text, phase: tail.phase };
-      return true;
+      if (tail.text.length + event.text.length > COALESCE_MAX_CHUNK_LENGTH) return null;
+      return { type: "text_delta", text: tail.text + event.text, phase: tail.phase };
     }
     if (event.type === "thinking_delta" && tail.type === "thinking_delta") {
-      if (tail.thinking.length + event.thinking.length > COALESCE_MAX_CHUNK_LENGTH) return false;
-      queued[queued.length - 1] = { type: "thinking_delta", thinking: tail.thinking + event.thinking };
-      return true;
+      if (tail.thinking.length + event.thinking.length > COALESCE_MAX_CHUNK_LENGTH) return null;
+      return { type: "thinking_delta", thinking: tail.thinking + event.thinking };
     }
+    return null;
+  };
+
+  /**
+   * Record why the turn is ending and close. The terminal error is admitted
+   * past both budgets — refusing to retain the explanation of a refusal would
+   * leave the consumer with a silent truncation — but it is charged like any
+   * other item so the counter stays exact through the final drain.
+   */
+  const abortWith = (message: string): false => {
+    opts?.onBacklogExceeded?.();
+    const terminal: AdapterEvent = { type: "error", message };
+    const cost = retainedEventCodeUnits(terminal);
+    queued.push(terminal);
+    charged.push(cost);
+    retained += cost;
+    close();
     return false;
   };
 
@@ -121,17 +251,35 @@ export function createAdapterEventQueue(opts?: {
     if (closed) return false;
     const reader = readers.shift();
     if (reader) {
+      // Handed straight to a waiting consumer, so the queue retains nothing and
+      // charges nothing. Neither budget applies to an event it never holds.
       reader({ done: false, value: event });
       return false;
     }
-    if (coalesceIntoTail(event)) return true;
-    if (queued.length >= maxBacklog) {
-      opts?.onBacklogExceeded?.();
-      queued.push({ type: "error", message: "consumer stalled: adapter event backlog exceeded — turn aborted" });
-      close();
-      return false;
+    const tail = queued[queued.length - 1];
+    const merged = tail ? planTailMerge(tail, event) : null;
+    if (merged && tail) {
+      const replacement = retainedEventCodeUnits(merged);
+      if (replacement > maxEventCodeUnits) return abortWith(EVENT_TOO_LARGE_MESSAGE);
+      // Charge only what the backlog actually gains. A merge keeps the tail's
+      // own fields, so the incoming event's duplicated phase is never retained
+      // twice and an unchanged tail costs nothing at all.
+      const delta = replacement - charged[charged.length - 1]!;
+      if (delta > maxBacklogCodeUnits - retained) return abortWith(BACKLOG_EXCEEDED_MESSAGE);
+      queued[queued.length - 1] = merged;
+      charged[charged.length - 1] = replacement;
+      retained += delta;
+      return true;
     }
+    const cost = retainedEventCodeUnits(event);
+    if (cost > maxEventCodeUnits) return abortWith(EVENT_TOO_LARGE_MESSAGE);
+    // Both refusals are priced before anything is retained, so an event that is
+    // turned away is never charged for.
+    if (queued.length >= maxBacklog) return abortWith(BACKLOG_EXCEEDED_MESSAGE);
+    if (cost > maxBacklogCodeUnits - retained) return abortWith(BACKLOG_EXCEEDED_MESSAGE);
     queued.push(event);
+    charged.push(cost);
+    retained += cost;
     return false;
   };
 
@@ -147,6 +295,7 @@ export function createAdapterEventQueue(opts?: {
     while (true) {
       const next = queued.shift();
       if (next) {
+        retained -= charged.shift() ?? 0;
         yield next;
         continue;
       }
@@ -165,5 +314,5 @@ export function createAdapterEventQueue(opts?: {
     return events;
   };
 
-  return { push, close, stream, collect };
+  return { push, close, stream, collect, retainedCodeUnits: () => retained };
 }
diff --git a/src/adapters/xai-web-search.ts b/src/adapters/xai-web-search.ts
index e558e39f2ed..4dbb77d7364 100644
--- a/src/adapters/xai-web-search.ts
+++ b/src/adapters/xai-web-search.ts
@@ -1,4 +1,5 @@
 import type { OcxProviderConfig } from "../types";
+import { debugProviderDiagnostic } from "../lib/debug";
 import { isXaiResponsesDestination } from "../providers/xai-transport";
 
 const CODEX_WEB_SEARCH_TOOL = "web_search";
@@ -192,7 +193,21 @@ export function normalizeXaiResponsesWebSearch(
     if (inputChanged) next = { ...next, input };
   }
 
-  return normalizeToolChoice(next);
+  const normalized = normalizeToolChoice(next);
+  const choice = normalized.tool_choice;
+  if ((choice === "auto" || choice === "none") && !hasAnyDeclaredTool(normalized)) {
+    debugProviderDiagnostic("xai", "tool-choice-omitted", { choice });
+    const { tool_choice: _toolChoice, ...rest } = normalized;
+    // `auto` selects from the catalog, so a catalog with nothing in it makes it meaningless and
+    // the omission says nothing the request did not already say. `none` is the opposite: it is a
+    // prohibition, and on a request whose catalog this normalizer just emptied it is the only
+    // place the turn's client-call boundary is written down. Downstream repair reads that
+    // boundary off the final outbound body, so omitting the word alone would hand back a call the
+    // caller ruled out. Restate it as the explicit empty catalog, which carries the same deny-all
+    // and which this destination already receives whenever a caller sends one itself.
+    return choice === "none" && !Array.isArray(rest.tools) ? { ...rest, tools: [] } : rest;
+  }
+  return normalized;
 }
 
 function isLiveWebSearchTool(tool: unknown): boolean {
diff --git a/src/bridge/errors.ts b/src/bridge/errors.ts
index aa270195792..e39aa1f4b45 100644
--- a/src/bridge/errors.ts
+++ b/src/bridge/errors.ts
@@ -1,9 +1,10 @@
 import {
+  applyReplayRefusalClientHeaders,
   isNonReplayableUpstreamCode,
   isReplayRefusalCode,
-  markReplayRefusalResponse,
   markResponseNonReplayable,
   REPLAY_REFUSED_STATUS,
+  retainReplayRefusal,
 } from "../lib/upstream-retry";
 import {
   adapterFailureFromMessage,
@@ -45,6 +46,11 @@ export function formatErrorResponse(
     && retryAfter.length <= 128) {
     headers.set("Retry-After", retryAfter);
   }
+  // The refusal's client policy, restated here for the same reason its status is: this
+  // formatter is the last thing several adapter and combo paths touch before the client,
+  // and no wait of its own does not stop a client that retries every 429 by default.
+  const refusal = isReplayRefusalCode(error.code) && replayBlocked;
+  if (refusal) applyReplayRefusalClientHeaders(headers);
   const response = new Response(JSON.stringify({ error }), {
     status: finalStatus,
     headers,
@@ -53,6 +59,6 @@ export function formatErrorResponse(
   // Re-wrapping is where the refusal loses its provenance: combo failure consumption parses
   // the JSON and builds a new Response, and the code alone does not tell a later quota
   // recorder that no upstream produced this status. Carry the narrower marker across too.
-  if (replayBlocked && isReplayRefusalCode(error.code)) markReplayRefusalResponse(response);
+  if (refusal) retainReplayRefusal(response);
   return response;
 }
diff --git a/src/bridge/response-json.ts b/src/bridge/response-json.ts
index cdc9cd1a02e..ccb03b62087 100644
--- a/src/bridge/response-json.ts
+++ b/src/bridge/response-json.ts
@@ -7,6 +7,7 @@ import type {
   OcxUsage,
 } from "../types";
 import { coerceIntegerToolArguments } from "../lib/tool-argument-integers";
+import { attemptDeliveryRecorder } from "../usage/attempt-delivery";
 import {
   adapterFailureFromMessage,
   classifyError,
@@ -51,7 +52,14 @@ export function buildResponseJSON(
 ): Record<string, unknown> {
   // Default-budget safety net: a caller that omits the budget gets a bounded
   // default (disposed with the call), never the unbounded append path.
-  if (options?.translatorBudget) return buildResponseJSONWithBudget(events, modelId, options);
+  if (options?.translatorBudget) {
+    const body = buildResponseJSONWithBudget(events, modelId, options);
+    // A buffered turn delivers its whole answer as one body, so nothing calls the per-frame
+    // recorder on the SSE bridge. Without this the attempt would persist adapter events with
+    // zero relayed ones, which is the loss signal -- raised on every non-streaming request.
+    attemptDeliveryRecorder(options.translatorBudget)?.noteBufferedDelivery(body);
+    return body;
+  }
   const budget = createTranslatorBudget();
   try {
     return buildResponseJSONWithBudget(events, modelId, { ...options, translatorBudget: budget });
diff --git a/src/bridge/sse.ts b/src/bridge/sse.ts
index 0466963eb57..a1f5a0fb8a4 100644
--- a/src/bridge/sse.ts
+++ b/src/bridge/sse.ts
@@ -16,6 +16,7 @@ import {
   type OcxErrorPayload,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
+import { attemptDeliveryRecorder, classifyRelayedResponseEvent } from "../usage/attempt-delivery";
 import {
   mayBecomePatchEnvelope,
   repairFreeformToolInput,
@@ -162,6 +163,10 @@ export function bridgeToResponsesSSE(
   // at terminal/cancel below.
   const ownsBudget = !options?.translatorBudget;
   const budget = options?.translatorBudget ?? createTranslatorBudget();
+  // Resolved from the CALLER's budget only. A bridge that owns its budget is not serving a
+  // logged request -- there is no attempt to count against, and a locally created scope would
+  // never have had a recorder bound to it.
+  const delivery = attemptDeliveryRecorder(options?.translatorBudget);
   // Idempotent: safe to call at every stream-death path; disposal must come
   // AFTER the final charges (emitDone), never inside reportTerminal.
   const disposeOwnedBudget = () => { if (ownsBudget) budget.dispose(); };
@@ -278,6 +283,11 @@ export function bridgeToResponsesSSE(
           controller.enqueue(frame);
           budget?.releaseRetained(frameBytes, { kind: "live_transient" });
           emittedFrames++;
+          // After a SUCCESSFUL enqueue, never before it. A frame that threw on the way to the
+          // transport did not reach the caller, and counting it here would make the relayed
+          // total equal the adapter total by construction -- erasing the one discrepancy these
+          // counters exist to expose (#3983).
+          delivery?.noteRelayedEvent(classifyRelayedResponseEvent(name, data));
         } catch (error) {
           if (isTranslatorBudgetExceededError(error)) {
             terminateForTranslatorOverflow?.(error);
diff --git a/src/chat/inbound.ts b/src/chat/inbound.ts
index b12761c8e4e..8630cc0dd79 100644
--- a/src/chat/inbound.ts
+++ b/src/chat/inbound.ts
@@ -92,11 +92,32 @@ function userContentToBlocks(content: unknown): Rec[] {
       continue;
     }
     const videoUrl = videoUrlFromPart(raw);
-    if (videoUrl) blocks.push({ type: "input_video", video_url: videoUrl });
+    if (videoUrl) {
+      blocks.push({ type: "input_video", video_url: videoUrl });
+      continue;
+    }
+    const file = fileFromPart(raw);
+    if (file) blocks.push(file);
   }
   return blocks;
 }
 
+/**
+ * A Chat Completions `file` part carrying inline bytes, as the Responses `input_file` block.
+ *
+ * Nothing here recognized the shape, so the part reached the end of the loop with no branch and
+ * was dropped in silence (#5212). A part with no inline bytes is still not translatable and is
+ * left to the untranslated-media refusal, which runs before this loop.
+ */
+function fileFromPart(part: Rec): Rec | null {
+  if (part.type !== "file" && part.type !== "input_file") return null;
+  const file = isRec(part.file) ? part.file : part;
+  const fileData = file.file_data;
+  if (typeof fileData !== "string" || fileData.length === 0) return null;
+  const filename = typeof file.filename === "string" && file.filename.length > 0 ? file.filename : undefined;
+  return { type: "input_file", file_data: fileData, ...(filename ? { filename } : {}) };
+}
+
 /**
  * The assistant's prior thinking, as plaintext, from either Chat spelling.
  *
@@ -146,7 +167,27 @@ function pushSystemText(parts: string[], content: unknown): void {
   if (text) parts.push(text);
 }
 
-function toolCallsToItems(toolCalls: unknown, input: Rec[], knownNameByCallId: Map<string, string>): void {
+/**
+ * A mid-conversation instruction, as the input item the rest of the pipeline already reads.
+ *
+ * The role is `developer` rather than `system` for two reasons that both bite. The native
+ * ChatGPT backend refuses a `role:"system"` item inside `input`, and canonical forwarding
+ * folds every message-shaped `system` item back onto `instructions`
+ * (src/adapters/openai-responses/canonical-forward.ts), which would undo the placement one hop
+ * later. `developer` is first-class in responsesRequestSchema, survives parseRequest as a
+ * chronological conversation message, and is exactly what src/claude/inbound.ts already emits
+ * for the same shape.
+ */
+function developerInstructionItem(text: string): Rec {
+  return { type: "message", role: "developer", content: [{ type: "input_text", text }] };
+}
+
+function toolCallsToItems(
+  toolCalls: unknown,
+  input: Rec[],
+  knownNameByCallId: Map<string, string>,
+  awaitingToolResult: Set<string>,
+): void {
   if (!Array.isArray(toolCalls)) return;
   for (const raw of toolCalls) {
     if (!isRec(raw)) continue;
@@ -166,6 +207,7 @@ function toolCallsToItems(toolCalls: unknown, input: Rec[], knownNameByCallId: M
     if (!name) throw new ChatCompletionsRequestError("tool_calls entries require function.name");
     knownNameByCallId.set(callId, name);
     input.push({ type: "function_call", call_id: callId, name, arguments: args });
+    awaitingToolResult.add(callId);
   }
 }
 
@@ -218,11 +260,67 @@ function toolChoiceToResponses(choice: unknown, body: Rec): void {
     body.tool_choice = { type: "function", name };
     return;
   }
+  if (choice.type === "allowed_tools") {
+    body.tool_choice = allowedToolsChoiceToResponses(choice);
+    return;
+  }
   if (isRec(choice.function) && typeof choice.function.name === "string") {
     body.tool_choice = { type: "function", name: choice.function.name };
   }
 }
 
+/**
+ * Chat Completions nests the subset under `allowed_tools`, Responses carries `mode`/`tools`
+ * on the choice itself, and each entry names its tool under a member keyed by its own type
+ * (`{"type":"function","function":{"name"}}`) rather than a flat `name`. Neither level lines up
+ * with `mapToolChoice`, so an unflattened choice fell past every branch and the caller's subset
+ * was dropped while the full catalogue was still advertised (#5211).
+ *
+ * An entry nobody can name is refused rather than skipped: dropping one widens the very subset
+ * the caller sent this field to narrow.
+ */
+function allowedToolsChoiceToResponses(choice: Rec): Rec {
+  const spec = isRec(choice.allowed_tools) ? choice.allowed_tools : choice;
+  if (!Array.isArray(spec.tools) || spec.tools.length === 0) {
+    throw new ChatCompletionsRequestError("tool_choice.allowed_tools requires a non-empty tools array");
+  }
+  return {
+    type: "allowed_tools",
+    mode: spec.mode === "required" ? "required" : "auto",
+    tools: spec.tools.map(allowedToolEntryToResponses),
+  };
+}
+
+/** Hosted entries are named by their type alone; a function or custom entry must carry a name. */
+const HOSTED_ALLOWED_TOOL_TYPES = new Set([
+  "web_search",
+  "web_search_preview",
+  "image_generation",
+  "image_gen",
+  "tool_search",
+]);
+const NAMED_ALLOWED_TOOL_TYPES = new Set(["function", "custom"]);
+
+function allowedToolEntryToResponses(raw: unknown): Rec {
+  if (!isRec(raw)) {
+    throw new ChatCompletionsRequestError("tool_choice.allowed_tools.tools entries must be objects");
+  }
+  const type = typeof raw.type === "string" && raw.type.length > 0 ? raw.type : "function";
+  if (!NAMED_ALLOWED_TOOL_TYPES.has(type) && !HOSTED_ALLOWED_TOOL_TYPES.has(type)) {
+    // An unknown selector kind is not a narrower subset, it is a subset nobody can evaluate.
+    throw new ChatCompletionsRequestError(`unsupported tool_choice.allowed_tools.tools entry type: ${type}`);
+  }
+  const nested = isRec(raw[type]) ? raw[type] as Rec : undefined;
+  const name = typeof raw.name === "string" && raw.name.length > 0
+    ? raw.name
+    : nested !== undefined && typeof nested.name === "string" && nested.name.length > 0
+      ? nested.name
+      : undefined;
+  if (name !== undefined) return { type, name };
+  if (HOSTED_ALLOWED_TOOL_TYPES.has(type)) return { type };
+  throw new ChatCompletionsRequestError("tool_choice.allowed_tools.tools entries require a name");
+}
+
 function responseFormatToText(format: unknown): Rec | undefined {
   if (format === undefined) return undefined;
   if (!isRec(format)) throw new ChatCompletionsRequestError("response_format must be an object");
@@ -291,21 +389,54 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
   // Recover replace-style tool calls incrementally instead of rebuilding the
   // call-id index from the entire translated transcript for every message.
   const knownNameByCallId = new Map<string, string>();
+  // Tool calls whose result has not arrived yet. Several adapters need a call and its output
+  // to stay adjacent — Kiro refuses an interrupted pair (src/adapters/kiro/payload.ts) and the
+  // Anthropic and Google mappers synthesize a missing result — so an instruction that arrives
+  // inside an open batch waits for the batch to drain instead of splitting it.
+  const awaitingToolResult = new Set<string>();
+  const heldInstructions: string[] = [];
+  const releaseHeldInstructions = (): void => {
+    if (heldInstructions.length === 0) return;
+    input.push(developerInstructionItem(heldInstructions.join("\n\n")));
+    heldInstructions.length = 0;
+  };
+  // A user or assistant turn ends any open tool batch, so held text rejoins the timeline
+  // before that turn rather than drifting past it.
+  const beginConversationTurn = (): void => {
+    releaseHeldInstructions();
+    awaitingToolResult.clear();
+  };
 
   for (const msg of raw.messages) {
     if (!isRec(msg)) continue;
     const role = typeof msg.role === "string" ? msg.role : "";
     switch (role) {
       case "system":
-      case "developer":
-        pushSystemText(systemParts, msg.content);
+      case "developer": {
+        // A leading block is this request's instructions and keeps that treatment: it is the
+        // prompt head, and hoisting it is what the upstream prefix cache wants.
+        if (input.length === 0) {
+          pushSystemText(systemParts, msg.content);
+          break;
+        }
+        // Past the first turn the slot carries meaning. `U1 -> A1 -> D2 -> U2` says D2 applies
+        // to U2 and not to U1, and folding it into `instructions` moved it ahead of both while
+        // rewriting the prompt head on every turn that carried one. The outbound adapter has
+        // preserved this slot since #4161; the position was already gone by the time it ran.
+        const text = contentToText(msg.content).trim();
+        if (!text) break;
+        if (awaitingToolResult.size > 0) heldInstructions.push(text);
+        else input.push(developerInstructionItem(text));
         break;
+      }
       case "user": {
+        beginConversationTurn();
         const blocks = userContentToBlocks(msg.content);
         if (blocks.length > 0) input.push({ type: "message", role: "user", content: blocks });
         break;
       }
       case "assistant": {
+        beginConversationTurn();
         // A reasoning item precedes the assistant message it belongs to: the
         // Responses assistant item schema admits only output content blocks, so there
         // is no attachment point on the message itself, and the parser buffers a
@@ -328,7 +459,9 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
         }
         const blocks = assistantContentToBlocks(msg.content);
         if (blocks.length > 0) input.push({ type: "message", role: "assistant", content: blocks });
-        if (msg.tool_calls !== undefined) toolCallsToItems(msg.tool_calls, input, knownNameByCallId);
+        if (msg.tool_calls !== undefined) {
+          toolCallsToItems(msg.tool_calls, input, knownNameByCallId, awaitingToolResult);
+        }
         break;
       }
       case "function": {
@@ -351,12 +484,15 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
           ? blocks.filter(part => part.type === "input_text" || part.type === "input_image")
           : contentToText(msg.content);
         input.push({ type: "function_call_output", call_id: callId, output });
+        awaitingToolResult.delete(callId);
+        if (awaitingToolResult.size === 0) releaseHeldInstructions();
         break;
       }
       default:
         break;
     }
   }
+  releaseHeldInstructions();
 
   if (input.length === 0 && systemParts.length === 0) {
     throw new ChatCompletionsRequestError("messages must include at least one user/assistant/tool turn");
diff --git a/src/claude/desktop-3p.ts b/src/claude/desktop-3p.ts
index ec50f765ab0..e7ffcfb72ba 100644
--- a/src/claude/desktop-3p.ts
+++ b/src/claude/desktop-3p.ts
@@ -473,6 +473,12 @@ export function removeDesktop3pStandardPivot(
   options: Desktop3pConfigLibraryOptions & {
     appliedFingerprint?: string | null; unlink?: (path: string) => void;
     lifecycleLockDeps?: ClientLifecycleLockDeps;
+    /**
+     * The desired-state guard below exists for OFF flows racing a concurrent enable. A
+     * mode switch (gateway → first-party) removes the profile while the integration stays
+     * ON on purpose, so the caller opts out of that guard.
+     */
+    replaceWhileEnabled?: boolean;
   } = {},
 ): Desktop3pRemovalResult {
   const libraryPath = resolveDesktop3pConfigLibraryPath(options);
@@ -488,7 +494,7 @@ export function removeDesktop3pStandardPivot(
       }
       const latest = readConfigDiagnostics();
       if (latest.source === "fallback") return { ok: false, changed: false, kind: "unsafe", libraryPath, reason: "desktop_config_invalid" };
-      if (claudeDesktopIntegrationEnabled(latest.config)) {
+      if (!options.replaceWhileEnabled && claudeDesktopIntegrationEnabled(latest.config)) {
         const observed = inspectDesktop3pConfigLibrary(options);
         if (observed.kind === "not_installed" || observed.kind === "no_owned_state") {
           return { ok: true, changed: false, kind: "noop", libraryPath };
diff --git a/src/claude/desktop-first-party.ts b/src/claude/desktop-first-party.ts
new file mode 100644
index 00000000000..0946aafddd5
--- /dev/null
+++ b/src/claude/desktop-first-party.ts
@@ -0,0 +1,172 @@
+/**
+ * Claude Desktop first-party mode.
+ *
+ * Desktop has two ways to reach opencodex:
+ *
+ *   - `first-party` (default): the app keeps its ordinary claude.ai login, Chat tab, connectors
+ *     and remote control. Only the Claude Code process it spawns for the Code tab (and that
+ *     process's subagents) is redirected, through the `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` env
+ *     in `~/.claude/settings.json` (src/claude/intercept/settings.ts) and the server's intercept
+ *     pair (src/claude/intercept/runtime.ts). Nothing is written under Desktop's config library.
+ *   - `gateway`: the historical third-party deployment profile (src/claude/desktop-3p.ts). The
+ *     whole app is switched to a gateway build; picker entries are opencodex aliases.
+ *
+ * The two are mutually exclusive on disk: applying one removes the other. The mode is persisted
+ * in `claudeCode.desktopMode`; installs that predate the field but already carry an applied
+ * gateway profile keep `gateway` until they explicitly re-apply, so an update never flips a
+ * working Desktop under the operator.
+ */
+import { getConfigDir } from "../config/paths";
+import type { OcxConfig } from "../types";
+import { claudeInterceptCaCertPath, ensureLocalInterceptCa } from "./intercept/local-ca";
+import { claudeInterceptEnabled, claudeInterceptProxyPort } from "./intercept/runtime";
+import {
+  applyClaudeInterceptSettings,
+  buildClaudeInterceptEnv,
+  inspectClaudeInterceptSettings,
+  removeClaudeInterceptSettings,
+  type ClaudeInterceptEnv,
+  type ClaudeInterceptSettingsState,
+  type ClaudeInterceptSettingsWrite,
+} from "./intercept/settings";
+
+export const CLAUDE_DESKTOP_MODES = ["first-party", "gateway"] as const;
+export type ClaudeDesktopMode = typeof CLAUDE_DESKTOP_MODES[number];
+export const DEFAULT_CLAUDE_DESKTOP_MODE: ClaudeDesktopMode = "first-party";
+
+export function isClaudeDesktopMode(value: unknown): value is ClaudeDesktopMode {
+  return typeof value === "string" && (CLAUDE_DESKTOP_MODES as readonly string[]).includes(value);
+}
+
+type DesktopModeConfig = Pick<OcxConfig, "claudeCode">;
+
+/**
+ * Effective Desktop mode. An explicit `claudeCode.desktopMode` wins; otherwise a persisted
+ * gateway apply marker (`desktopProfile.appliedFingerprint`) means a pre-existing gateway
+ * install and keeps `gateway`; everything else is the first-party default.
+ */
+export function resolveClaudeDesktopMode(config: DesktopModeConfig): ClaudeDesktopMode {
+  const explicit = config.claudeCode?.desktopMode;
+  if (isClaudeDesktopMode(explicit)) return explicit;
+  if (config.claudeCode?.desktopProfile?.appliedFingerprint) return "gateway";
+  return DEFAULT_CLAUDE_DESKTOP_MODE;
+}
+
+/**
+ * Config mutation that records the applied Desktop mode. Switching to first-party also drops
+ * the gateway apply marker: the profile assignments stay for a later gateway apply, but a
+ * stale `appliedFingerprint` must not make `resolveClaudeDesktopMode` read `gateway` again
+ * should the explicit marker ever go missing.
+ */
+export function recordClaudeDesktopMode(
+  config: DesktopModeConfig,
+  mode: ClaudeDesktopMode,
+): { changed: boolean; value: true } {
+  const claudeCode = config.claudeCode ?? {};
+  const profile = claudeCode.desktopProfile;
+  const dropMarker = mode === "first-party" && profile !== undefined
+    && (profile.appliedFingerprint !== undefined || profile.appliedAt !== undefined);
+  if (claudeCode.desktopMode === mode && !dropMarker) return { changed: false, value: true };
+  if (dropMarker) {
+    const { appliedFingerprint: _fingerprint, appliedAt: _at, ...rest } = profile;
+    config.claudeCode = { ...claudeCode, desktopMode: mode, desktopProfile: rest };
+  } else {
+    config.claudeCode = { ...claudeCode, desktopMode: mode };
+  }
+  return { changed: true, value: true };
+}
+
+/**
+ * Mode an *apply* without an explicit choice should use. The first-party default only holds
+ * where the intercept proxy actually runs; with it disabled (or on a client role) an implied
+ * first-party apply would point Claude Code at a proxy that never starts, so fall back to the
+ * gateway profile. An explicit `desktopMode: "first-party"` is still honoured (and refused
+ * later with `intercept_disabled`, which names the fix).
+ */
+export function resolveClaudeDesktopApplyMode(
+  config: Pick<OcxConfig, "claudeCode" | "runtimeRole">,
+): ClaudeDesktopMode {
+  const resolved = resolveClaudeDesktopMode(config);
+  if (resolved === "gateway" || isClaudeDesktopMode(config.claudeCode?.desktopMode)) return resolved;
+  return claudeInterceptEnabled(config) ? "first-party" : "gateway";
+}
+
+export interface DesktopFirstPartyTarget {
+  proxyPort: number;
+  caCertPath: string;
+  env: ClaudeInterceptEnv;
+}
+
+/** The settings env a first-party apply on this machine writes (CA is created on demand). */
+export function desktopFirstPartyTarget(
+  config: Pick<OcxConfig, "claudeCode" | "port">,
+  opencodexConfigDir = getConfigDir(),
+): DesktopFirstPartyTarget {
+  const proxyPort = claudeInterceptProxyPort(config, config.port ?? 10100);
+  const caCertPath = claudeInterceptCaCertPath(opencodexConfigDir);
+  return { proxyPort, caCertPath, env: buildClaudeInterceptEnv(proxyPort, caCertPath) };
+}
+
+export interface DesktopFirstPartyInspection {
+  /** False when the server will not run the intercept pair (client role, intercept disabled). */
+  interceptEnabled: boolean;
+  proxyPort: number;
+  caCertPath: string;
+  settings: ClaudeInterceptSettingsState;
+  /** settings.json carries exactly the env the current config would write. */
+  applied: boolean;
+  /** Ours, but for an older port/config directory. Re-apply refreshes it. */
+  stale: boolean;
+}
+
+export interface DesktopFirstPartyOptions {
+  opencodexConfigDir?: string;
+  claudeConfigDir?: string;
+}
+
+export function inspectDesktopFirstParty(
+  config: Pick<OcxConfig, "claudeCode" | "port" | "runtimeRole">,
+  options: DesktopFirstPartyOptions = {},
+): DesktopFirstPartyInspection {
+  const target = desktopFirstPartyTarget(config, options.opencodexConfigDir);
+  const settings = inspectClaudeInterceptSettings(target.env, options.claudeConfigDir);
+  return {
+    interceptEnabled: claudeInterceptEnabled(config),
+    proxyPort: target.proxyPort,
+    caCertPath: target.caCertPath,
+    settings,
+    applied: settings.kind === "applied",
+    stale: settings.kind === "stale",
+  };
+}
+
+export type DesktopFirstPartyApplyResult =
+  | { ok: true; changed: boolean; path: string; env: ClaudeInterceptEnv; proxyPort: number }
+  | { ok: false; reason: "intercept_disabled" | "ca_unavailable" | "unreadable" | "foreign_env"; path: string };
+
+/**
+ * Write the first-party env into Claude Code's settings. Creates the local CA first so the
+ * path we point `NODE_EXTRA_CA_CERTS` at exists before Claude Code ever reads it.
+ */
+export function applyDesktopFirstParty(
+  config: Pick<OcxConfig, "claudeCode" | "port" | "runtimeRole">,
+  options: DesktopFirstPartyOptions = {},
+): DesktopFirstPartyApplyResult {
+  const opencodexConfigDir = options.opencodexConfigDir ?? getConfigDir();
+  const target = desktopFirstPartyTarget(config, opencodexConfigDir);
+  if (!claudeInterceptEnabled(config)) return { ok: false, reason: "intercept_disabled", path: "" };
+  try {
+    ensureLocalInterceptCa(opencodexConfigDir);
+  } catch {
+    return { ok: false, reason: "ca_unavailable", path: target.caCertPath };
+  }
+  const written = applyClaudeInterceptSettings(target.env, options.claudeConfigDir);
+  if (!written.ok) return { ok: false, reason: written.reason, path: written.path };
+  return { ok: true, changed: written.changed, path: written.path, env: target.env, proxyPort: target.proxyPort };
+}
+
+/** Remove the first-party env. Only values anchored on our CA path are touched. */
+export function removeDesktopFirstParty(options: DesktopFirstPartyOptions = {}): ClaudeInterceptSettingsWrite {
+  const caCertPath = claudeInterceptCaCertPath(options.opencodexConfigDir ?? getConfigDir());
+  return removeClaudeInterceptSettings(caCertPath, options.claudeConfigDir);
+}
diff --git a/src/claude/inbound-content-options.ts b/src/claude/inbound-content-options.ts
index 0b59a93073a..fbfe6ed503e 100644
--- a/src/claude/inbound-content-options.ts
+++ b/src/claude/inbound-content-options.ts
@@ -35,6 +35,12 @@ export function toolsToResponses(tools: unknown): Rec[] | undefined {
         // call, so carry the source intent instead of the destination default. A
         // non-boolean value is not a valid Anthropic opt-in and must not become one.
         strict: typeof raw.strict === "boolean" ? raw.strict : false,
+        // Anthropic restricts who may invoke a tool through allowed_callers. Nothing read it,
+        // so the restriction never reached the internal tool and every destination rebuilt the
+        // declaration without it while the request still succeeded (#5210).
+        ...(Array.isArray(raw.allowed_callers)
+          ? { allowed_callers: raw.allowed_callers.filter((c): c is string => typeof c === "string") }
+          : {}),
       });
       continue;
     }
diff --git a/src/claude/inbound.ts b/src/claude/inbound.ts
index e3664bf01c2..2938c9b2a9d 100644
--- a/src/claude/inbound.ts
+++ b/src/claude/inbound.ts
@@ -19,6 +19,7 @@ import { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, f
 import { systemToInstructions, toolsToResponses, toolChoiceToResponses } from "./inbound-content-options";
 import { stabilizeClaudeInstructionsForPromptCache } from "./inbound-cache-stabilize";
 import { decodeReasoningEnvelope, encodeReasoningEnvelope, OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
+import { inlineDocumentMarker } from "../responses/inline-document";
 import { createTranslatorBudget, type TranslatorBudget } from "../lib/translator-budget";
 
 
@@ -41,6 +42,26 @@ function imageBlockToInputImage(block: Rec): Rec | null {
   return null;
 }
 
+function documentTitle(block: Rec): string | undefined {
+  return typeof block.title === "string" && block.title.length > 0 ? block.title : undefined;
+}
+
+/** An Anthropic base64 document as the Responses `input_file` block that carries its bytes. */
+function documentBlockToInputFile(block: Rec): Rec | null {
+  const source = block.source;
+  if (!isRec(source) || source.type !== "base64") return null;
+  const mediaType = typeof source.media_type === "string" && source.media_type.length > 0
+    ? source.media_type
+    : "application/octet-stream";
+  if (typeof source.data !== "string" || source.data.length === 0) return null;
+  const title = documentTitle(block);
+  return {
+    type: "input_file",
+    file_data: `data:${mediaType};base64,${source.data}`,
+    ...(title !== undefined ? { filename: title } : {}),
+  };
+}
+
 function toolResultOutput(block: Rec): string | Rec[] {
   const isError = block.is_error === true;
   const content = block.content;
@@ -55,9 +76,11 @@ function toolResultOutput(block: Rec): string | Rec[] {
         const img = imageBlockToInputImage(item);
         if (img) out.push(img);
       } else if (item.type === "document") {
-        // Same marker as the user-message document case below: the model should see the
-        // attachment happened instead of an empty tool output.
-        out.push({ type: "input_text", text: `[document${typeof item.title === "string" ? `: ${item.title}` : ""}]` });
+        // Tool output has no structured document carrier on this route — the Responses tool
+        // output vocabulary has no input_file block, and every adapter's tool-result path
+        // flattens to text — so this keeps the #939 marker. The user-message branch below is
+        // where bytes survive. Recorded as the remaining half of #5212.
+        out.push({ type: "input_text", text: inlineDocumentMarker(documentTitle(item)) });
       }
     }
     if (isError) out.unshift({ type: "input_text", text: "[tool error]" });
@@ -208,9 +231,12 @@ function userMessageToItems(content: unknown, input: Rec[], elide: SkillElisionC
         break;
       }
       case "document":
-        // No Responses equivalent for raw document blocks; surface the title so the
-        // model at least sees the attachment happened.
-        pending.push({ type: "input_text", text: `[document${typeof raw.title === "string" ? `: ${raw.title}` : ""}]` });
+        // A base64 document now rides the Responses input_file block, so a target with a
+        // counterpart receives the bytes instead of a sentence about them (#5212). Every other
+        // source is a reference this route cannot dereference, and keeps the marker #939
+        // introduced — which is also what a target with no document representation still sees.
+        pending.push(documentBlockToInputFile(raw)
+          ?? { type: "input_text", text: inlineDocumentMarker(documentTitle(raw)) });
         break;
       default:
         break; // thinking/redacted_thinking never appear in user messages; ignore unknowns
diff --git a/src/claude/intercept/connect-proxy.ts b/src/claude/intercept/connect-proxy.ts
new file mode 100644
index 00000000000..86c9375513f
--- /dev/null
+++ b/src/claude/intercept/connect-proxy.ts
@@ -0,0 +1,179 @@
+import { BlockList, createServer, connect, isIP, type Server, type Socket } from "node:net";
+
+/**
+ * Loopback HTTP CONNECT proxy for Claude Code.
+ *
+ * Claude Code honours `HTTPS_PROXY` and opens `CONNECT <host>:443` for every upstream. This
+ * proxy splices tunnels for the intercepted hosts onto the local TLS listener (which holds a
+ * leaf certificate for them) and blindly relays every other tunnel to its real destination,
+ * so telemetry, OAuth refresh and claude.ai traffic stay native and opaque to opencodex.
+ *
+ * Only CONNECT is served. Plain proxied HTTP requests are refused: Claude Code never sends
+ * them, and answering them would turn this socket into a generic forward proxy.
+ */
+
+export const CLAUDE_INTERCEPT_HOSTS = ["api.anthropic.com"] as const;
+
+const MAX_HEAD_BYTES = 8 * 1024;
+const HEAD_TIMEOUT_MS = 10_000;
+const UPSTREAM_CONNECT_TIMEOUT_MS = 15_000;
+
+export interface ConnectProxyOptions {
+  /** Loopback port of the TLS listener that terminates intercepted tunnels. */
+  interceptPort: number;
+  /** Hostnames (lowercase) whose 443 tunnels are spliced onto `interceptPort`. */
+  interceptHosts?: readonly string[];
+  /** Test seam: dial the real destination for a blind tunnel. */
+  dialUpstream?: (host: string, port: number) => Socket;
+}
+
+export interface ConnectProxyHandle {
+  port: number;
+  close(): Promise<void>;
+}
+
+interface ConnectTarget {
+  host: string;
+  port: number;
+}
+
+/** Parse `CONNECT host:port HTTP/1.1` from a request head; `null` for anything else. */
+export function parseConnectRequestLine(head: string): ConnectTarget | null {
+  const requestLine = head.split("\r\n", 1)[0] ?? "";
+  const match = /^CONNECT\s+(\S+)\s+HTTP\/1\.[01]$/.exec(requestLine);
+  if (!match) return null;
+  const authority = match[1]!;
+  // Bracketed IPv6 (`[::1]:443`) and plain `host:port`.
+  const ipv6 = /^\[([^\]]+)\]:(\d{1,5})$/.exec(authority);
+  const hostPort = ipv6 ?? /^([^:]+):(\d{1,5})$/.exec(authority);
+  if (!hostPort) return null;
+  const port = Number(hostPort[2]);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+  return { host: hostPort[1]!.toLowerCase().replace(/\.$/, ""), port };
+}
+
+// 127/8 and ::1, which `BlockList` also matches in IPv4-mapped form (`::ffff:127.0.0.1`,
+// `::ffff:7f00:1`). The unspecified addresses dial the local host too.
+const LOCAL_TARGETS = new BlockList();
+LOCAL_TARGETS.addSubnet("127.0.0.0", 8, "ipv4");
+LOCAL_TARGETS.addAddress("0.0.0.0", "ipv4");
+LOCAL_TARGETS.addAddress("::1", "ipv6");
+LOCAL_TARGETS.addAddress("::", "ipv6");
+
+export function isLoopbackTarget(host: string): boolean {
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  const family = isIP(host);
+  if (family !== 0) return LOCAL_TARGETS.check(host, family === 6 ? "ipv6" : "ipv4");
+  // `127.1`, `0x7f000001`, `2130706433`: resolver shorthand for a loopback literal, not a name.
+  return /^(0x[0-9a-f]+|\d+)(\.(0x[0-9a-f]+|\d+))*$/.test(host);
+}
+
+function respond(socket: Socket, status: number, reason: string): void {
+  if (socket.destroyed) return;
+  socket.end(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+}
+
+function splice(client: Socket, upstream: Socket, pending: Uint8Array): void {
+  const teardown = () => {
+    client.destroy();
+    upstream.destroy();
+  };
+  client.on("error", teardown);
+  upstream.on("error", teardown);
+  client.on("close", () => upstream.destroy());
+  upstream.on("close", () => client.destroy());
+  client.setTimeout(0);
+  client.setNoDelay(true);
+  upstream.setNoDelay(true);
+  if (pending.length > 0) upstream.write(pending);
+  client.pipe(upstream);
+  upstream.pipe(client);
+}
+
+function handleConnection(socket: Socket, options: Required<Pick<ConnectProxyOptions, "interceptPort" | "interceptHosts" | "dialUpstream">>): void {
+  let head: Buffer = Buffer.alloc(0);
+  socket.on("error", () => socket.destroy());
+  socket.setTimeout(HEAD_TIMEOUT_MS, () => respond(socket, 408, "Request Timeout"));
+
+  const onData = (chunk: Buffer) => {
+    head = head.length === 0 ? chunk : Buffer.concat([head, chunk]);
+    const end = head.indexOf("\r\n\r\n");
+    if (end === -1) {
+      if (head.length > MAX_HEAD_BYTES) {
+        socket.off("data", onData);
+        respond(socket, 431, "Request Header Fields Too Large");
+      }
+      return;
+    }
+    socket.off("data", onData);
+    socket.pause();
+    const target = parseConnectRequestLine(head.subarray(0, end).toString("latin1"));
+    // Bytes after the head belong to the tunnel (a client may pipeline its TLS ClientHello).
+    const pending = head.subarray(end + 4);
+    if (!target) {
+      respond(socket, 405, "Method Not Allowed");
+      return;
+    }
+    if (isLoopbackTarget(target.host)) {
+      respond(socket, 403, "Forbidden");
+      return;
+    }
+    const intercept = target.port === 443 && options.interceptHosts.includes(target.host);
+    const upstream = intercept
+      ? connect({ host: "127.0.0.1", port: options.interceptPort })
+      : options.dialUpstream(target.host, target.port);
+    let established = false;
+    const connectTimer = setTimeout(() => {
+      if (!established) {
+        upstream.destroy();
+        respond(socket, 504, "Gateway Timeout");
+      }
+    }, UPSTREAM_CONNECT_TIMEOUT_MS);
+    upstream.once("error", () => {
+      clearTimeout(connectTimer);
+      if (!established) respond(socket, 502, "Bad Gateway");
+    });
+    upstream.once("connect", () => {
+      established = true;
+      clearTimeout(connectTimer);
+      if (socket.destroyed) {
+        upstream.destroy();
+        return;
+      }
+      socket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      splice(socket, upstream, pending);
+      socket.resume();
+    });
+  };
+  socket.on("data", onData);
+}
+
+/** Bind the CONNECT proxy on 127.0.0.1. Rejects when the port is unavailable. */
+export function startConnectProxy(port: number, options: ConnectProxyOptions): Promise<ConnectProxyHandle> {
+  const resolved = {
+    interceptPort: options.interceptPort,
+    interceptHosts: options.interceptHosts ?? CLAUDE_INTERCEPT_HOSTS,
+    dialUpstream: options.dialUpstream ?? ((host: string, targetPort: number) => connect({ host, port: targetPort })),
+  };
+  return new Promise((resolve, reject) => {
+    const server: Server = createServer(socket => handleConnection(socket, resolved));
+    const sockets = new Set<Socket>();
+    server.on("connection", socket => {
+      sockets.add(socket);
+      socket.once("close", () => sockets.delete(socket));
+    });
+    server.once("error", reject);
+    server.listen({ port, host: "127.0.0.1", exclusive: true }, () => {
+      server.off("error", reject);
+      const address = server.address();
+      const boundPort = address && typeof address === "object" ? address.port : port;
+      resolve({
+        port: boundPort,
+        close: () => new Promise<void>(done => {
+          for (const socket of sockets) socket.destroy();
+          server.close(() => done());
+        }),
+      });
+    });
+  });
+}
diff --git a/src/claude/intercept/listener.ts b/src/claude/intercept/listener.ts
new file mode 100644
index 00000000000..8b4cdbb1409
--- /dev/null
+++ b/src/claude/intercept/listener.ts
@@ -0,0 +1,122 @@
+import type { Server } from "bun";
+import type { PemKeyPair } from "./local-ca";
+
+/**
+ * TLS listener that terminates intercepted `api.anthropic.com` tunnels.
+ *
+ * The CONNECT proxy splices a Claude Code tunnel onto this socket; the client then speaks
+ * HTTPS believing it reached Anthropic. Messages traffic is rewritten to a loopback URL and
+ * handed to the router's own request handler, which already knows how to route mapped models
+ * to providers and pass genuine Claude models through with the caller's subscription
+ * credential. Every other path (usage, feedback, model listings, …) is relayed verbatim to
+ * the real upstream so the client keeps behaving like a first-party install.
+ */
+
+export const CLAUDE_INTERCEPT_UPSTREAM = "https://api.anthropic.com";
+
+const INTERCEPTED_PATHS = new Set(["/v1/messages", "/v1/messages/count_tokens"]);
+
+const HOP_BY_HOP_HEADERS = new Set([
+  "connection", "keep-alive", "transfer-encoding", "upgrade", "te", "trailer",
+  "proxy-authenticate", "proxy-authorization", "proxy-connection", "host", "content-length",
+  "accept-encoding",
+]);
+
+// fetch() transparently decodes the body, so the encoding headers would describe bytes the
+// client never sees.
+const RESPONSE_STRIP_HEADERS = new Set([
+  "connection", "keep-alive", "transfer-encoding", "content-encoding", "content-length",
+]);
+
+export function isClaudeInterceptedPath(pathname: string, method: string): boolean {
+  return method === "POST" && INTERCEPTED_PATHS.has(pathname);
+}
+
+/**
+ * Rebuild the request as if the client had dialled the router directly on loopback: the
+ * admission and Host checks then take the same path a plain loopback bind always has.
+ */
+export function rewriteInterceptedRequest(req: Request, loopbackOrigin: string): Request {
+  const url = new URL(req.url);
+  const headers = new Headers(req.headers);
+  headers.set("host", loopbackOrigin.replace(/^https?:\/\//, ""));
+  return new Request(`${loopbackOrigin}${url.pathname}${url.search}`, {
+    method: req.method,
+    headers,
+    body: req.body,
+    signal: req.signal,
+    redirect: "manual",
+    // @ts-expect-error -- streaming request bodies require half duplex under the fetch spec.
+    duplex: "half",
+  });
+}
+
+export function forwardHeadersForUpstream(source: Headers): Headers {
+  const headers = new Headers();
+  source.forEach((value, name) => {
+    if (!HOP_BY_HOP_HEADERS.has(name.toLowerCase())) headers.append(name, value);
+  });
+  return headers;
+}
+
+export async function relayToUpstream(req: Request, upstreamBase: string, fetchImpl: typeof fetch = fetch): Promise<Response> {
+  const url = new URL(req.url);
+  const target = `${upstreamBase.replace(/\/$/, "")}${url.pathname}${url.search}`;
+  const hasBody = req.method !== "GET" && req.method !== "HEAD";
+  let upstream: Response;
+  try {
+    upstream = await fetchImpl(target, {
+      method: req.method,
+      headers: forwardHeadersForUpstream(req.headers),
+      body: hasBody ? req.body : undefined,
+      signal: req.signal,
+      redirect: "manual",
+      // @ts-expect-error -- streaming request bodies require half duplex under the fetch spec.
+      duplex: "half",
+    });
+  } catch (error) {
+    return Response.json(
+      { type: "error", error: { type: "api_error", message: `intercept relay failed: ${error instanceof Error ? error.message : String(error)}` } },
+      { status: 502 },
+    );
+  }
+  const headers = new Headers();
+  upstream.headers.forEach((value, name) => {
+    if (!RESPONSE_STRIP_HEADERS.has(name.toLowerCase())) headers.append(name, value);
+  });
+  return new Response(upstream.body, { status: upstream.status, statusText: upstream.statusText, headers });
+}
+
+export interface ClaudeInterceptListenerOptions<T = undefined> {
+  leaf: PemKeyPair;
+  /** Router request handler; receives the loopback-rewritten request and the intercept server. */
+  dispatch: (req: Request, server: Server<T>) => Promise<Response>;
+  upstreamBase?: string;
+  maxRequestBodySize?: number;
+  idleTimeout?: number;
+  fetchImpl?: typeof fetch;
+  /** Test seam: bind a fixed port instead of an ephemeral one. */
+  port?: number;
+}
+
+/** Bind the intercept TLS listener on an ephemeral loopback port. */
+export function startClaudeInterceptListener<T = undefined>(options: ClaudeInterceptListenerOptions<T>): Server<T> {
+  const upstreamBase = options.upstreamBase ?? CLAUDE_INTERCEPT_UPSTREAM;
+  let loopbackOrigin = "";
+  const server = Bun.serve<T>({
+    port: options.port ?? 0,
+    hostname: "127.0.0.1",
+    tls: { cert: options.leaf.certPem, key: options.leaf.keyPem },
+    idleTimeout: options.idleTimeout ?? 255,
+    ...(options.maxRequestBodySize !== undefined ? { maxRequestBodySize: options.maxRequestBodySize } : {}),
+    async fetch(req, requestServer) {
+      const url = new URL(req.url);
+      if (isClaudeInterceptedPath(url.pathname, req.method)) {
+        return options.dispatch(rewriteInterceptedRequest(req, loopbackOrigin), requestServer);
+      }
+      return relayToUpstream(req, upstreamBase, options.fetchImpl);
+    },
+  });
+  loopbackOrigin = `http://127.0.0.1:${server.port}`;
+  return server;
+}
diff --git a/src/claude/intercept/local-ca.ts b/src/claude/intercept/local-ca.ts
new file mode 100644
index 00000000000..d3baf4a6c5e
--- /dev/null
+++ b/src/claude/intercept/local-ca.ts
@@ -0,0 +1,278 @@
+import { createHash, generateKeyPairSync, createPrivateKey, createPublicKey, sign, type KeyObject } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Local certificate authority for the Claude intercept listener.
+ *
+ * Claude Code opens `CONNECT api.anthropic.com:443` through `HTTPS_PROXY` and then expects a
+ * TLS server that presents a certificate for that name. This module mints that authority and
+ * its leaves with nothing but `node:crypto`: no OpenSSL shell-out, no third-party ASN.1
+ * library. The CA is trusted by the Claude Code process alone via `NODE_EXTRA_CA_CERTS`; it is
+ * never installed into an OS trust store.
+ *
+ * Only the subset of X.509 needed for a v3 CA and a serverAuth leaf is encoded. ECDSA P-256 is
+ * used for both, which Node's TLS stack accepts without any additional configuration.
+ */
+
+export const CLAUDE_INTERCEPT_CA_COMMON_NAME = "opencodex Claude Intercept CA";
+const ORGANIZATION = "opencodex";
+const CA_VALIDITY_DAYS = 3650;
+const LEAF_VALIDITY_DAYS = 365;
+
+// ── DER encoding ────────────────────────────────────────────────────────────────
+
+function derLength(length: number): Uint8Array {
+  if (length < 0x80) return Uint8Array.of(length);
+  const bytes: number[] = [];
+  let rest = length;
+  while (rest > 0) {
+    bytes.unshift(rest & 0xff);
+    rest >>= 8;
+  }
+  return Uint8Array.of(0x80 | bytes.length, ...bytes);
+}
+
+function concat(...parts: Uint8Array[]): Uint8Array {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}
+
+function tlv(tag: number, body: Uint8Array): Uint8Array {
+  return concat(Uint8Array.of(tag), derLength(body.length), body);
+}
+
+const sequence = (...parts: Uint8Array[]) => tlv(0x30, concat(...parts));
+const set = (...parts: Uint8Array[]) => tlv(0x31, concat(...parts));
+const boolean = (value: boolean) => tlv(0x01, Uint8Array.of(value ? 0xff : 0x00));
+const octetString = (body: Uint8Array) => tlv(0x04, body);
+const utf8String = (text: string) => tlv(0x0c, new TextEncoder().encode(text));
+const contextTag = (n: number, body: Uint8Array, constructed = true) => tlv((constructed ? 0xa0 : 0x80) | n, body);
+
+function integer(bytes: Uint8Array): Uint8Array {
+  return tlv(0x02, (bytes[0]! & 0x80) !== 0 ? concat(Uint8Array.of(0), bytes) : bytes);
+}
+
+function bitString(bytes: Uint8Array, unusedBits = 0): Uint8Array {
+  return tlv(0x03, concat(Uint8Array.of(unusedBits), bytes));
+}
+
+function objectIdentifier(dotted: string): Uint8Array {
+  const arcs = dotted.split(".").map(Number);
+  const bytes: number[] = [arcs[0]! * 40 + arcs[1]!];
+  for (const arc of arcs.slice(2)) {
+    const encoded: number[] = [arc & 0x7f];
+    let rest = arc >> 7;
+    while (rest > 0) {
+      encoded.unshift((rest & 0x7f) | 0x80);
+      rest >>= 7;
+    }
+    bytes.push(...encoded);
+  }
+  return tlv(0x06, Uint8Array.from(bytes));
+}
+
+function utcTime(date: Date): Uint8Array {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const text = `${pad(date.getUTCFullYear() % 100)}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}`
+    + `${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}Z`;
+  return tlv(0x17, new TextEncoder().encode(text));
+}
+
+const OID = {
+  commonName: "2.5.4.3",
+  organization: "2.5.4.10",
+  ecdsaWithSha256: "1.2.840.10045.4.3.2",
+  basicConstraints: "2.5.29.19",
+  keyUsage: "2.5.29.15",
+  subjectAltName: "2.5.29.17",
+  extendedKeyUsage: "2.5.29.37",
+  subjectKeyIdentifier: "2.5.29.14",
+  authorityKeyIdentifier: "2.5.29.35",
+  serverAuth: "1.3.6.1.5.5.7.3.1",
+} as const;
+
+function distinguishedName(commonName: string): Uint8Array {
+  return sequence(
+    set(sequence(objectIdentifier(OID.organization), utf8String(ORGANIZATION))),
+    set(sequence(objectIdentifier(OID.commonName), utf8String(commonName))),
+  );
+}
+
+function extension(oid: string, critical: boolean, value: Uint8Array): Uint8Array {
+  return critical
+    ? sequence(objectIdentifier(oid), boolean(true), octetString(value))
+    : sequence(objectIdentifier(oid), octetString(value));
+}
+
+function subjectPublicKeyInfo(key: KeyObject): Uint8Array {
+  return new Uint8Array(key.export({ type: "spki", format: "der" }));
+}
+
+/** RFC 5280 permits any unique octet string; a truncated SHA-256 of the SPKI is stable and collision-safe. */
+function keyIdentifier(key: KeyObject): Uint8Array {
+  return new Uint8Array(createHash("sha256").update(subjectPublicKeyInfo(key)).digest()).subarray(0, 20);
+}
+
+function randomSerial(): Uint8Array {
+  const serial = crypto.getRandomValues(new Uint8Array(16));
+  serial[0]! &= 0x7f;
+  if (serial[0] === 0) serial[0] = 1;
+  return serial;
+}
+
+function toPem(label: string, der: Uint8Array): string {
+  const base64 = Buffer.from(der).toString("base64").replace(/(.{64})/g, "$1\n").trimEnd();
+  return `-----BEGIN ${label}-----\n${base64}\n-----END ${label}-----\n`;
+}
+
+interface IssueOptions {
+  subject: Uint8Array;
+  issuer: Uint8Array;
+  subjectKey: KeyObject;
+  signingKey: KeyObject;
+  validityDays: number;
+  extensions: Uint8Array[];
+}
+
+function issueCertificate(options: IssueOptions): Uint8Array {
+  // Back-date slightly so a client whose clock trails ours by a few minutes still accepts it.
+  const notBefore = new Date(Date.now() - 5 * 60_000);
+  const notAfter = new Date(notBefore.getTime() + options.validityDays * 86_400_000);
+  const algorithm = sequence(objectIdentifier(OID.ecdsaWithSha256));
+  const tbsCertificate = sequence(
+    contextTag(0, tlv(0x02, Uint8Array.of(2))),
+    integer(randomSerial()),
+    algorithm,
+    options.issuer,
+    sequence(utcTime(notBefore), utcTime(notAfter)),
+    options.subject,
+    subjectPublicKeyInfo(options.subjectKey),
+    contextTag(3, sequence(...options.extensions)),
+  );
+  const signature = new Uint8Array(sign("sha256", tbsCertificate, { key: options.signingKey, dsaEncoding: "der" }));
+  return sequence(tbsCertificate, algorithm, bitString(signature));
+}
+
+// ── Authority + leaves ──────────────────────────────────────────────────────────
+
+export interface PemKeyPair {
+  certPem: string;
+  keyPem: string;
+}
+
+export interface LocalInterceptCa extends PemKeyPair {
+  publicKey: KeyObject;
+  privateKey: KeyObject;
+}
+
+export function createLocalInterceptCa(): LocalInterceptCa {
+  const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const name = distinguishedName(CLAUDE_INTERCEPT_CA_COMMON_NAME);
+  const der = issueCertificate({
+    subject: name,
+    issuer: name,
+    subjectKey: publicKey,
+    signingKey: privateKey,
+    validityDays: CA_VALIDITY_DAYS,
+    extensions: [
+      extension(OID.basicConstraints, true, sequence(boolean(true), tlv(0x02, Uint8Array.of(0)))),
+      // keyCertSign | cRLSign
+      extension(OID.keyUsage, true, bitString(Uint8Array.of(0x06), 1)),
+      extension(OID.subjectKeyIdentifier, false, octetString(keyIdentifier(publicKey))),
+    ],
+  });
+  return {
+    certPem: toPem("CERTIFICATE", der),
+    keyPem: privateKey.export({ type: "pkcs8", format: "pem" }) as string,
+    publicKey,
+    privateKey,
+  };
+}
+
+/** Issue a serverAuth leaf for `hosts` (first entry becomes the CN; all become SAN dNSNames). */
+export function issueLocalInterceptLeaf(ca: LocalInterceptCa, hosts: readonly string[]): PemKeyPair {
+  if (hosts.length === 0) throw new Error("intercept leaf requires at least one host");
+  const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const der = issueCertificate({
+    subject: distinguishedName(hosts[0]!),
+    issuer: distinguishedName(CLAUDE_INTERCEPT_CA_COMMON_NAME),
+    subjectKey: publicKey,
+    signingKey: ca.privateKey,
+    validityDays: LEAF_VALIDITY_DAYS,
+    extensions: [
+      extension(OID.basicConstraints, true, sequence()),
+      // digitalSignature
+      extension(OID.keyUsage, true, bitString(Uint8Array.of(0x80), 7)),
+      extension(OID.extendedKeyUsage, false, sequence(objectIdentifier(OID.serverAuth))),
+      extension(OID.subjectAltName, false, sequence(
+        ...hosts.map(host => contextTag(2, new TextEncoder().encode(host), false)),
+      )),
+      extension(OID.authorityKeyIdentifier, false, sequence(contextTag(0, keyIdentifier(ca.publicKey), false))),
+    ],
+  });
+  return {
+    certPem: toPem("CERTIFICATE", der),
+    keyPem: privateKey.export({ type: "pkcs8", format: "pem" }) as string,
+  };
+}
+
+// ── Persistence ─────────────────────────────────────────────────────────────────
+
+export const CLAUDE_INTERCEPT_STATE_DIR = "claude-intercept";
+export const CLAUDE_INTERCEPT_CA_CERT_FILE = "ca.pem";
+const CA_KEY_FILE = "ca.key";
+
+export function claudeInterceptStateDir(configDir: string): string {
+  return join(configDir, CLAUDE_INTERCEPT_STATE_DIR);
+}
+
+/** Path Claude Code must see in `NODE_EXTRA_CA_CERTS`. Stable across restarts. */
+export function claudeInterceptCaCertPath(configDir: string): string {
+  return join(claudeInterceptStateDir(configDir), CLAUDE_INTERCEPT_CA_CERT_FILE);
+}
+
+function writeFileAtomic(path: string, contents: string, mode: number): void {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, contents, { mode });
+  try { chmodSync(tmp, mode); } catch { /* best-effort on platforms without POSIX modes */ }
+  renameSync(tmp, path);
+}
+
+function loadPersistedCa(dir: string): LocalInterceptCa | null {
+  const certPath = join(dir, CLAUDE_INTERCEPT_CA_CERT_FILE);
+  const keyPath = join(dir, CA_KEY_FILE);
+  if (!existsSync(certPath) || !existsSync(keyPath)) return null;
+  try {
+    const certPem = readFileSync(certPath, "utf8");
+    const keyPem = readFileSync(keyPath, "utf8");
+    const privateKey = createPrivateKey(keyPem);
+    const publicKey = createPublicKey(keyPem);
+    if (!certPem.includes("BEGIN CERTIFICATE")) return null;
+    return { certPem, keyPem, publicKey, privateKey };
+  } catch { // no-excuse-ok: catch -- an unreadable or corrupt authority is regenerated below.
+    return null;
+  }
+}
+
+/**
+ * Load the persisted authority under `<configDir>/claude-intercept/`, minting one when absent
+ * or unreadable. The private key is written 0600; the certificate is world-readable because
+ * `NODE_EXTRA_CA_CERTS` only needs the public half.
+ */
+export function ensureLocalInterceptCa(configDir: string): LocalInterceptCa {
+  const dir = claudeInterceptStateDir(configDir);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const existing = loadPersistedCa(dir);
+  if (existing) return existing;
+  const ca = createLocalInterceptCa();
+  writeFileAtomic(join(dir, CA_KEY_FILE), ca.keyPem, 0o600);
+  writeFileAtomic(join(dir, CLAUDE_INTERCEPT_CA_CERT_FILE), ca.certPem, 0o644);
+  return ca;
+}
diff --git a/src/claude/intercept/runtime.ts b/src/claude/intercept/runtime.ts
new file mode 100644
index 00000000000..a1452117d8c
--- /dev/null
+++ b/src/claude/intercept/runtime.ts
@@ -0,0 +1,98 @@
+import type { Server } from "bun";
+import type { OcxConfig } from "../../types";
+import { getConfigDir } from "../../config/paths";
+import { CLAUDE_INTERCEPT_HOSTS, startConnectProxy, type ConnectProxyHandle } from "./connect-proxy";
+import { startClaudeInterceptListener } from "./listener";
+import { claudeInterceptCaCertPath, ensureLocalInterceptCa, issueLocalInterceptLeaf } from "./local-ca";
+
+/**
+ * Lifecycle for the Claude intercept pair (CONNECT proxy + TLS listener).
+ *
+ * Started next to the public listener, torn down with it. The proxy port is derived from the
+ * public port unless configured, because Claude Code's `settings.json` must name a port that
+ * survives restarts; the TLS listener is ephemeral and only ever reached through the proxy.
+ */
+
+export const CLAUDE_INTERCEPT_PORT_OFFSET = 100;
+
+export function claudeInterceptEnabled(config: Pick<OcxConfig, "claudeCode" | "runtimeRole">): boolean {
+  if (config.runtimeRole === "client") return false;
+  if (config.claudeCode?.enabled === false) return false;
+  return config.claudeCode?.intercept?.enabled !== false;
+}
+
+export function claudeInterceptProxyPort(config: Pick<OcxConfig, "claudeCode">, publicPort: number): number {
+  const configured = config.claudeCode?.intercept?.port;
+  if (typeof configured === "number" && Number.isInteger(configured) && configured >= 1 && configured <= 65535) return configured;
+  return publicPort + CLAUDE_INTERCEPT_PORT_OFFSET;
+}
+
+export interface ClaudeInterceptState {
+  proxyPort: number;
+  caCertPath: string;
+}
+
+export interface ClaudeInterceptHandle<T = undefined> extends ClaudeInterceptState {
+  listener: Server<T>;
+  stop(): Promise<void>;
+}
+
+let activeState: ClaudeInterceptState | null = null;
+
+/** Live intercept endpoints, or `null` when the pair is not running in this process. */
+export function getClaudeInterceptState(): ClaudeInterceptState | null {
+  return activeState;
+}
+
+export interface StartClaudeInterceptOptions<T> {
+  config: OcxConfig;
+  /** Bound public port; the derived proxy port is offset from it. */
+  publicPort: number;
+  /**
+   * Port the operator asked for. `0` (ephemeral) gives the derived proxy port no stable value
+   * to write into `settings.json`, so intercept stays off unless `intercept.port` is explicit.
+   */
+  requestedPort?: number;
+  dispatch: (req: Request, server: Server<T>) => Promise<Response>;
+  maxRequestBodySize?: number;
+  configDir?: string;
+}
+
+/**
+ * Bind both halves. Resolves `null` when intercept is disabled. A bind failure is reported by
+ * rejecting; callers treat it as a degraded optional integration, never as a startup failure.
+ */
+export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptions<T>): Promise<ClaudeInterceptHandle<T> | null> {
+  if (!claudeInterceptEnabled(options.config)) return null;
+  const explicitPort = typeof options.config.claudeCode?.intercept?.port === "number";
+  if (options.requestedPort === 0 && !explicitPort) return null;
+  const configDir = options.configDir ?? getConfigDir();
+  const ca = ensureLocalInterceptCa(configDir);
+  const leaf = issueLocalInterceptLeaf(ca, CLAUDE_INTERCEPT_HOSTS);
+  const listener = startClaudeInterceptListener<T>({
+    leaf,
+    dispatch: options.dispatch,
+    upstreamBase: options.config.claudeCode?.anthropicBaseUrl,
+    ...(options.maxRequestBodySize !== undefined ? { maxRequestBodySize: options.maxRequestBodySize } : {}),
+  });
+  let proxy: ConnectProxyHandle;
+  try {
+    proxy = await startConnectProxy(claudeInterceptProxyPort(options.config, options.publicPort), {
+      interceptPort: listener.port!,
+    });
+  } catch (error) {
+    await listener.stop(true);
+    throw error;
+  }
+  const state: ClaudeInterceptState = { proxyPort: proxy.port, caCertPath: claudeInterceptCaCertPath(configDir) };
+  activeState = state;
+  return {
+    ...state,
+    listener,
+    stop: async () => {
+      if (activeState === state) activeState = null;
+      await proxy.close();
+      await listener.stop(true);
+    },
+  };
+}
diff --git a/src/claude/intercept/settings.ts b/src/claude/intercept/settings.ts
new file mode 100644
index 00000000000..5b291a7b401
--- /dev/null
+++ b/src/claude/intercept/settings.ts
@@ -0,0 +1,161 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { claudeConfigDir } from "../auth-detect";
+
+/**
+ * Claude Code `settings.json` env block for intercept mode.
+ *
+ * Both the Claude Desktop Code tab and the standalone `claude` CLI read the user
+ * `~/.claude/settings.json` and export its `env` map into the process before any network
+ * call. Two keys make every Claude Code process route through the local CONNECT proxy while
+ * the app itself stays a first-party install:
+ *
+ *   env.HTTPS_PROXY         = http://127.0.0.1:<proxy port>
+ *   env.NODE_EXTRA_CA_CERTS = <configDir>/claude-intercept/ca.pem
+ *
+ * Ownership is tracked by value, never by a marker key. The CA path is the anchor: it lives
+ * under opencodex's own config directory, so only a block whose `NODE_EXTRA_CA_CERTS` names
+ * that file is treated as ours. A user's own proxy or CA setting is left alone.
+ */
+
+export const CLAUDE_INTERCEPT_MANAGED_ENV = ["HTTPS_PROXY", "NODE_EXTRA_CA_CERTS"] as const;
+export type ClaudeInterceptManagedEnv = typeof CLAUDE_INTERCEPT_MANAGED_ENV[number];
+
+export interface ClaudeInterceptEnv {
+  HTTPS_PROXY: string;
+  NODE_EXTRA_CA_CERTS: string;
+}
+
+export function claudeInterceptProxyUrl(port: number): string {
+  return `http://127.0.0.1:${port}`;
+}
+
+export function buildClaudeInterceptEnv(proxyPort: number, caCertPath: string): ClaudeInterceptEnv {
+  return { HTTPS_PROXY: claudeInterceptProxyUrl(proxyPort), NODE_EXTRA_CA_CERTS: caCertPath };
+}
+
+export type ClaudeInterceptSettingsState =
+  | { kind: "absent" }
+  | { kind: "applied"; env: ClaudeInterceptEnv }
+  | { kind: "stale"; env: Partial<ClaudeInterceptEnv> }
+  | { kind: "foreign"; env: Partial<Record<ClaudeInterceptManagedEnv, string>> }
+  | { kind: "unreadable"; path: string };
+
+type SettingsDoc = Record<string, unknown> & { env?: Record<string, unknown> };
+
+function settingsPath(configDir: string): string {
+  return join(configDir, "settings.json");
+}
+
+function readSettings(path: string): { doc: SettingsDoc } | { error: "missing" | "unreadable" } {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) { // no-excuse-ok: catch -- an absent settings file is the fresh-install state.
+    return { error: (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unreadable" };
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { error: "unreadable" };
+    return { doc: parsed as SettingsDoc };
+  } catch { // no-excuse-ok: catch -- a corrupt settings file must be reported, not overwritten.
+    return { error: "unreadable" };
+  }
+}
+
+function envRecord(doc: SettingsDoc): Record<string, unknown> {
+  return doc.env && typeof doc.env === "object" && !Array.isArray(doc.env) ? doc.env : {};
+}
+
+/** Loopback proxy URLs are the only shape opencodex ever writes. */
+export function isClaudeInterceptProxyUrl(value: unknown): value is string {
+  return typeof value === "string" && /^http:\/\/127\.0\.0\.1:\d{1,5}\/?$/.test(value.trim());
+}
+
+function isOwnedCaPath(value: unknown, ownedCaPath: string): value is string {
+  return typeof value === "string" && value.trim() === ownedCaPath;
+}
+
+/** Classify the current settings env against the values this router would write. */
+export function inspectClaudeInterceptSettings(
+  expected: ClaudeInterceptEnv,
+  configDir = claudeConfigDir(),
+): ClaudeInterceptSettingsState {
+  const path = settingsPath(configDir);
+  const read = readSettings(path);
+  if ("error" in read) return read.error === "missing" ? { kind: "absent" } : { kind: "unreadable", path };
+  const env = envRecord(read.doc);
+  const proxy = env.HTTPS_PROXY;
+  const ca = env.NODE_EXTRA_CA_CERTS;
+  if (proxy === undefined && ca === undefined) return { kind: "absent" };
+  if (proxy === expected.HTTPS_PROXY && ca === expected.NODE_EXTRA_CA_CERTS) return { kind: "applied", env: expected };
+  const caOurs = isOwnedCaPath(ca, expected.NODE_EXTRA_CA_CERTS);
+  const proxyOurs = proxy === undefined || isClaudeInterceptProxyUrl(proxy);
+  if (caOurs && proxyOurs) {
+    return {
+      kind: "stale",
+      env: {
+        ...(typeof proxy === "string" ? { HTTPS_PROXY: proxy } : {}),
+        ...(typeof ca === "string" ? { NODE_EXTRA_CA_CERTS: ca } : {}),
+      },
+    };
+  }
+  return {
+    kind: "foreign",
+    env: {
+      ...(typeof proxy === "string" ? { HTTPS_PROXY: proxy } : {}),
+      ...(typeof ca === "string" ? { NODE_EXTRA_CA_CERTS: ca } : {}),
+    },
+  };
+}
+
+function writeSettings(path: string, doc: SettingsDoc): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+  renameSync(tmp, path);
+}
+
+export type ClaudeInterceptSettingsWrite =
+  | { ok: true; changed: boolean; path: string }
+  | { ok: false; reason: "unreadable" | "foreign_env"; path: string };
+
+/**
+ * Write the intercept env into `settings.json`. Refuses when a managed key already holds a
+ * value opencodex did not write (a user-configured corporate proxy, for instance).
+ */
+export function applyClaudeInterceptSettings(
+  env: ClaudeInterceptEnv,
+  configDir = claudeConfigDir(),
+): ClaudeInterceptSettingsWrite {
+  const path = settingsPath(configDir);
+  const state = inspectClaudeInterceptSettings(env, configDir);
+  if (state.kind === "unreadable") return { ok: false, reason: "unreadable", path };
+  if (state.kind === "foreign") return { ok: false, reason: "foreign_env", path };
+  if (state.kind === "applied") return { ok: true, changed: false, path };
+  const read = readSettings(path);
+  const doc: SettingsDoc = "doc" in read ? read.doc : {};
+  doc.env = { ...envRecord(doc), ...env };
+  writeSettings(path, doc);
+  return { ok: true, changed: true, path };
+}
+
+/** Remove the managed keys, but only the values opencodex owns. */
+export function removeClaudeInterceptSettings(
+  ownedCaPath: string,
+  configDir = claudeConfigDir(),
+): ClaudeInterceptSettingsWrite {
+  const path = settingsPath(configDir);
+  const read = readSettings(path);
+  if ("error" in read) {
+    return read.error === "missing" ? { ok: true, changed: false, path } : { ok: false, reason: "unreadable", path };
+  }
+  const env = envRecord(read.doc);
+  if (!isOwnedCaPath(env.NODE_EXTRA_CA_CERTS, ownedCaPath)) return { ok: true, changed: false, path };
+  delete env.NODE_EXTRA_CA_CERTS;
+  if (isClaudeInterceptProxyUrl(env.HTTPS_PROXY)) delete env.HTTPS_PROXY;
+  if (Object.keys(env).length === 0) delete read.doc.env;
+  else read.doc.env = env;
+  writeSettings(path, read.doc);
+  return { ok: true, changed: true, path };
+}
diff --git a/src/cli/access.ts b/src/cli/access.ts
index 51b351f9042..9cc0ec091a2 100644
--- a/src/cli/access.ts
+++ b/src/cli/access.ts
@@ -12,6 +12,8 @@ import {
 const USAGE = `Usage:
   ocx access key [list] [--json]
   ocx access key create [name] [--json]
+  ocx access key get <id-or-name> [--json]
+  ocx access key set <id-or-name> [--allow-provider <name>]... [--allow-model <id>]... [--clear] [--json]
   ocx access key rotate <id> [--json]
   ocx access key rotate commit <id> <rotation-id> [--json]
   ocx access key rotate abort <id> <rotation-id> [--json]
@@ -65,6 +67,51 @@ function formatKeyRows(payload: Record<string, unknown>, keys: Array<Record<stri
   return footer.length > 0 ? [...lines, "", ...footer] : lines;
 }
 
+/**
+ * Repeatable option values, in the order given.
+ *
+ * takeOption removes one occurrence, so a scope with several entries needs the
+ * loop: reading it once would silently keep only the first `--allow-model` and
+ * write a narrower scope than the operator typed.
+ */
+function takeAllOptions(args: string[], name: string): string[] {
+  const values: string[] = [];
+  for (;;) {
+    const value = takeOption(args, name);
+    if (value === undefined) break;
+    values.push(value);
+  }
+  return values;
+}
+
+/**
+ * Find a key by id or by name, without ever reading the secret.
+ *
+ * The management API keys every mutation by id, so a name has to be resolved
+ * here. An ambiguous name is refused rather than resolved to the first match:
+ * silently scoping one of two keys that share a name is the kind of mistake
+ * only discovered when the wrong client stops working.
+ */
+function findKeyRow(keys: Array<Record<string, unknown>>, selector: string): Record<string, unknown> {
+  const wanted = selector.trim().toLowerCase();
+  const byId = keys.filter(entry => String(entry.id ?? "").toLowerCase() === wanted);
+  if (byId.length === 1) return byId[0]!;
+  const byName = keys.filter(entry => String(entry.name ?? "").trim().toLowerCase() === wanted);
+  if (byName.length === 1) return byName[0]!;
+  if (byName.length > 1) throw new CliUsageError("key name " + selector + " is ambiguous; use the id", USAGE);
+  throw new CliUsageError("no API key matches " + selector, USAGE);
+}
+
+function scopeLines(entry: Record<string, unknown>): string[] {
+  const list = (value: unknown): string =>
+    Array.isArray(value) && value.length > 0 ? (value as string[]).join(", ") : "(any)";
+  return [
+    "API key " + String(entry.name ?? "") + " (" + String(entry.id ?? "") + ")",
+    "  allowed providers: " + list(entry.allowedProviders),
+    "  allowed models:    " + list(entry.allowedModels),
+  ];
+}
+
 async function key(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const action = (args.shift() ?? "list").toLowerCase();
@@ -90,6 +137,46 @@ async function key(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     ]);
     return;
   }
+  if (action === "get") {
+    const selector = args.shift();
+    if (!selector) throw new CliUsageError("key id or name is required", USAGE);
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest<Record<string, unknown>>("/api/keys", {}, deps);
+    const entry = findKeyRow(Array.isArray(result.keys) ? result.keys as Array<Record<string, unknown>> : [], selector);
+    // The list response carries the masked prefix and never the secret, so the
+    // row is safe to print as-is under --json.
+    printData(entry, wantsJson, scopeLines(entry));
+    return;
+  }
+  if (action === "set") {
+    const selector = args.shift();
+    if (!selector) throw new CliUsageError("key id or name is required", USAGE);
+    const clear = takeFlag(args, "--clear");
+    const providers = takeAllOptions(args, "--allow-provider");
+    const models = takeAllOptions(args, "--allow-model");
+    rejectArgs(args, USAGE);
+    if (!clear && providers.length === 0 && models.length === 0) {
+      throw new CliUsageError("set requires --allow-provider, --allow-model, or --clear", USAGE);
+    }
+    const listed = await runtimeRequest<Record<string, unknown>>("/api/keys", {}, deps);
+    const target = findKeyRow(Array.isArray(listed.keys) ? listed.keys as Array<Record<string, unknown>> : [], selector);
+    // A set REPLACES the named dimension rather than appending to it, and
+    // --clear removes both. Naming one dimension leaves the other alone, so
+    // narrowing providers cannot accidentally widen models.
+    const body: Record<string, unknown> = { id: target.id };
+    if (clear) {
+      body.allowedProviders = null;
+      body.allowedModels = null;
+    }
+    if (providers.length > 0) body.allowedProviders = providers;
+    if (models.length > 0) body.allowedModels = models;
+    const result = await runtimeRequest<Record<string, unknown>>("/api/keys", {
+      method: "PATCH",
+      body: JSON.stringify(body),
+    }, deps);
+    printData(result, wantsJson, scopeLines(result));
+    return;
+  }
   if (action === "rotate") {
     const operation = args[0] === "commit" || args[0] === "abort" ? args.shift()! : "start";
     const id = args.shift();
diff --git a/src/cli/account-auth.ts b/src/cli/account-auth.ts
index 73838f9da8e..bf233f0462c 100644
--- a/src/cli/account-auth.ts
+++ b/src/cli/account-auth.ts
@@ -2,6 +2,7 @@ import { writeSync } from "node:fs";
 import { modelSelectionGuidance, modelSelectionNextSteps } from "./model-selection-guidance";
 import { warnIfCodexCatalogRefreshPending } from "./account-catalog-refresh";
 import { isCodexResetCreditOperationId } from "../codex/reset-credit-recovery";
+import { BROWSER_LAUNCH_FAILED_NOTICE } from "../lib/browser-launch-notice";
 import {
   CliUsageError,
   printData,
@@ -69,8 +70,25 @@ interface LoginStart {
   flowId?: string;
   instructions?: string;
   deviceCode?: string;
+  /** Whether the host actually opened a browser. Absent from older proxies. */
+  browserLaunch?: "started" | "failed" | "skipped";
 }
 
+/**
+ * Said only when the host could not open a browser (#5261).
+ *
+ * Without it, a failed launch is indistinguishable from a successful one: the URL is printed
+ * either way, so the user waits at a terminal that looks like it is working. Names the fixed
+ * callback port because that is the part people cannot guess — ChatGPT supplies the redirect
+ * URI, so the flow cannot move to a free port, and `--device` is the way around it.
+ *
+ * Extends the shared notice rather than repeating it: only the second line is specific to this
+ * flow, and the first is the sentence every other login prints for the same failure.
+ */
+export const BROWSER_LAUNCH_FAILED_HINT =
+  BROWSER_LAUNCH_FAILED_NOTICE
+  + "\n   If nothing on this machine can reach http://localhost:1455, rerun with --device instead.";
+
 /** `-` means "read it from stdin", the documented way to pass a code silently. */
 const STDIN_SENTINEL = "-";
 
@@ -145,6 +163,7 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
         start.url ? `Open this URL to sign in:\n${start.url}` : "",
         start.deviceCode ? `Device code: ${start.deviceCode}` : "",
         start.instructions ?? "",
+        start.browserLaunch === "failed" ? BROWSER_LAUNCH_FAILED_HINT : "",
         start.flowId ? `Flow: ${start.flowId}` : "",
       ].filter(line => line !== "").join("\n");
       if (block) writeStdoutFully(`${block}\n`);
diff --git a/src/cli/capabilities.ts b/src/cli/capabilities.ts
index e67390041b9..cb117bcba05 100644
--- a/src/cli/capabilities.ts
+++ b/src/cli/capabilities.ts
@@ -211,6 +211,21 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "envelope",
     details: ["Reads /healthz plus local config; drives no management API route."],
   },
+  {
+    command: ["resolve"],
+    summary: "One JSON document naming the config home, the effective port, and the identity-checked proxy liveness verdict.",
+    // No management route, same split as status: discovery is the identity-checked
+    // /healthz probe inside findLiveProxy plus local config and the home from
+    // src/config/paths.ts.
+    routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the resolve document as JSON (the shell contract)." }],
+    mutates: false,
+    json: "envelope",
+    details: [
+      "Exit 0 carries a trustworthy verdict (live or proven absent); exit 1 means the CLI could not resolve and a caller must refuse to guess — unknown liveness never reads as absent.",
+      "Built for embedding shells (desktop app): the liveness budgets stay owned by src/server/proxy-liveness.ts.",
+    ],
+  },
   {
     command: ["hub", "invite"],
     summary: "Mint a single-use pairing code on a hub and print the exact `ocx connect` line for one more machine.",
@@ -314,6 +329,22 @@ export const CAPABILITIES: readonly Capability[] = [
       "Headless services usually have no unlocked keychain session; prefer ${ENV_VAR} references there.",
     ],
   },
+  {
+    command: ["companion"],
+    summary: "Inspect and configure menu-bar and widget companion usage settings.",
+    routes: [
+      { method: "GET", path: "/api/companion/settings" },
+      { method: "GET", path: "/api/usage/timeline" },
+      { method: "PUT", path: "/api/companion/settings" },
+    ],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit companion settings as JSON." }],
+    mutates: true,
+    json: "payload",
+    details: [
+      "`show` (the default) reads settings; `set key=value ...` updates selected settings; `reset` restores defaults.",
+      "Values accepted by `set` are parsed as JSON when valid, so booleans, numbers, arrays, objects, and null can be passed directly.",
+    ],
+  },
   {
     command: ["account", "history"],
     summary: "Cached quota observations for one stored Codex pool account.",
diff --git a/src/cli/claude-desktop.ts b/src/cli/claude-desktop.ts
index 7ff04dfe4e4..238e6bb03e8 100644
--- a/src/cli/claude-desktop.ts
+++ b/src/cli/claude-desktop.ts
@@ -15,13 +15,24 @@ import {
   type DesktopFamily,
   type DesktopProfile,
 } from "../claude/desktop-profile";
-import { writeDesktop3pConfig, type Desktop3pConfigMode, parseDesktop3pModeArgs } from "../claude/desktop-3p";
+import { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot, writeDesktop3pConfig, type Desktop3pConfigMode, parseDesktop3pModeArgs } from "../claude/desktop-3p";
+import {
+  applyDesktopFirstParty,
+  isClaudeDesktopMode,
+  recordClaudeDesktopMode,
+  removeDesktopFirstParty,
+  resolveClaudeDesktopApplyMode,
+  type ClaudeDesktopMode,
+} from "../claude/desktop-first-party";
 import { claudeDesktopPolicyWarning, probeClaudeDesktopPolicy } from "../claude/desktop-policy";
 import { filterCatalogVisibleModels, desktopVisibleNativeSlugs, nativeContextLimits } from "../codex/catalog";
 import { buildClaudeDesktopState, fetchAllModels } from "../server/management-api";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { CliUsageError, runtimeRequest, takeJsonFlag } from "./runtime-api";
 import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+import type { OcxConfig } from "../types";
+
+const APPLY_FLAGS = ["--first-party", "--gateway", "--static", "--hybrid", "--discovery-only"];
 
 function isFamily(value: string | undefined): value is DesktopFamily {
   return !!value && (DESKTOP_FAMILIES as readonly string[]).includes(value);
@@ -29,7 +40,10 @@ function isFamily(value: string | undefined): value is DesktopFamily {
 
 function printDesktopHelp(): void {
   console.log(`Usage:
-  ocx claude desktop [apply] [--static|--hybrid|--discovery-only]
+  ocx claude desktop [apply] [--first-party | --gateway [--static|--hybrid|--discovery-only]]
+      --first-party  (default) keep Desktop on claude.ai; route only the Code tab's Claude Code
+                     through the local intercept proxy via ~/.claude/settings.json env
+      --gateway      install the third-party gateway profile for the whole app
   ocx claude desktop show [--json]
   ocx claude desktop status [--json]
   ocx claude desktop move <provider/model> <opus|fable|sonnet|haiku> [--default]
@@ -135,6 +149,142 @@ async function applyConnectedDesktopProfile(
   }
 }
 
+/** Persist the operator's Desktop mode choice; a failed marker save never undoes the apply. */
+function saveDesktopMode(mode: ClaudeDesktopMode, deps: ApplyProfileDeps): boolean {
+  try {
+    return withClientLifecycleSync(() => {
+      const outcome = mutatePersistedConfig(current => recordClaudeDesktopMode(current, mode));
+      return outcome.status !== "unavailable";
+    }, deps.lifecycleLockDeps);
+  } catch {
+    return false;
+  }
+}
+
+export type DesktopApplyTarget =
+  | { kind: "first-party" }
+  | { kind: "gateway"; mode: Desktop3pConfigMode };
+
+/** Parse `ocx claude desktop apply` flags into a target; legacy gateway shape flags imply --gateway. */
+/**
+ * Default mode when no flag is given: first-party wherever the local intercept proxy can
+ * run; a connected client (proxy lives on the hub) or a disabled intercept falls back to
+ * the gateway profile rather than pointing Claude Code at a proxy that does not exist.
+ */
+export function defaultDesktopApplyMode(
+  config: Pick<OcxConfig, "claudeCode" | "runtimeRole">,
+  connection: ClientConnectionState = readClientConnectionState(),
+): ClaudeDesktopMode {
+  const resolved = resolveClaudeDesktopApplyMode(config);
+  if (resolved === "gateway") return resolved;
+  return connection.kind === "connected" ? "gateway" : "first-party";
+}
+
+export function parseDesktopApplyArgs(
+  flags: string[],
+  config: Pick<OcxConfig, "claudeCode" | "runtimeRole">,
+): { target: DesktopApplyTarget } | { error: string } {
+  const shapeFlags = flags.filter(arg => ["--static", "--hybrid", "--discovery-only"].includes(arg));
+  const wantsFirstParty = flags.includes("--first-party");
+  const wantsGateway = flags.includes("--gateway") || shapeFlags.length > 0;
+  if (wantsFirstParty && wantsGateway) return { error: "--first-party cannot be combined with --gateway or gateway shape flags." };
+  const unknown = flags.filter(arg => !["--first-party", "--gateway", "--static", "--hybrid", "--discovery-only"].includes(arg));
+  if (unknown.length > 0) return { error: `알 수 없는 인자: ${unknown.join(" ")}` };
+  const kind: ClaudeDesktopMode = wantsFirstParty ? "first-party" : wantsGateway ? "gateway" : defaultDesktopApplyMode(config);
+  if (kind === "first-party") return { target: { kind } };
+  const parsedMode = parseDesktop3pModeArgs(shapeFlags);
+  if ("error" in parsedMode) return parsedMode;
+  return { target: { kind, mode: parsedMode.mode } };
+}
+
+/**
+ * Why a gateway apply happened when the help text calls first-party the default.
+ *
+ * `resolveClaudeDesktopMode` keeps an existing install where it is: an explicit
+ * `claudeCode.desktopMode` wins, and a stored gateway apply marker keeps gateway. Both rules are
+ * right — a working Desktop install must not flip underneath its user because a default moved.
+ * Together they mean an existing gateway user never arrives at first-party without discovering
+ * `--first-party` unaided, while `ocx claude desktop --help` tells them first-party is "(default)".
+ *
+ * The fix is not to change the resolution. It is to say, at the moment of the apply, that the
+ * other mode exists and what selects it. Returns null when the user asked for gateway explicitly,
+ * because they already know, and when first-party is simply unavailable here — a connected client
+ * or a disabled intercept cannot run it, so offering it would be advice that fails.
+ */
+export function gatewayModeExplanation(input: {
+  requestedExplicitly: boolean;
+  config: Pick<OcxConfig, "claudeCode" | "runtimeRole">;
+  connection?: ClientConnectionState;
+}): string[] {
+  if (input.requestedExplicitly) return [];
+  const connection = input.connection ?? readClientConnectionState();
+  if (connection.kind === "connected") return [];
+  // Only a stored preference is worth explaining. Without one, gateway was chosen because
+  // first-party cannot run here, and naming an unavailable alternative is advice that fails.
+  const savedMode = input.config.claudeCode?.desktopMode;
+  const hasSavedGateway = isClaudeDesktopMode(savedMode) && savedMode === "gateway";
+  const hasApplyMarker = input.config.claudeCode?.desktopProfile?.appliedFingerprint !== undefined;
+  if (!hasSavedGateway && !hasApplyMarker) return [];
+  const reason = hasSavedGateway
+    ? "this machine has claudeCode.desktopMode saved as gateway"
+    : "this machine carries a previous gateway apply";
+  return [
+    `Applied the gateway profile because ${reason}; an existing install is never switched for you.`,
+    "First-party keeps Desktop on your claude.ai account and routes only the Code tab through the local proxy:",
+    "  ocx claude desktop apply --first-party",
+  ];
+}
+
+/**
+ * First-party apply: settings.json env only. The intercept pair the env points at runs inside
+ * the hub process, so this is a local-hub operation — a connected client machine cannot reach
+ * a loopback proxy on the hub and is refused rather than left with a dead `HTTPS_PROXY`.
+ */
+async function applyFirstPartyDesktop(
+  deps: ApplyProfileDeps,
+): Promise<{ ok: boolean; path: string; reason?: string; warning?: string }> {
+  try { assertNoClientDisconnectPending(); } catch { return { ok: false, path: "", reason: "client_disconnect_pending" }; }
+  const connection = readClientConnectionState();
+  if (connection.kind === "connected") return { ok: false, path: "", reason: "first_party_requires_local_hub" };
+  if (connection.kind !== "disconnected") return { ok: false, path: "", reason: "client_connection_invalid" };
+  const config = loadConfig();
+  const desired = setIntegrationEnabled("claude-desktop", true);
+  if (!desired.ok) return { ok: false, path: "", reason: desired.message };
+  // First-party replaces gateway; the two must never be active together.
+  const appliedFingerprint = config.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
+  const library = inspectDesktop3pConfigLibrary({ appliedFingerprint });
+  if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
+    const removed = removeDesktop3pStandardPivot({ appliedFingerprint, replaceWhileEnabled: true });
+    if (!removed.ok) {
+      return { ok: false, path: library.selectedProfilePath ?? "", reason: removed.kind === "cleanup_incomplete" ? "gateway_cleanup_incomplete" : `gateway_profile_active:${removed.reason ?? removed.kind}` };
+    }
+  }
+  const applied = applyDesktopFirstParty(config);
+  if (!applied.ok) return { ok: false, path: applied.path, reason: applied.reason };
+  const saved = saveDesktopMode("first-party", deps);
+  return {
+    ok: true,
+    path: applied.path,
+    ...(saved ? {} : { warning: "desktop mode marker was not saved" }),
+  };
+}
+
+export async function applyDesktop(
+  profile: DesktopProfile | undefined,
+  target: DesktopApplyTarget,
+  deps: ApplyProfileDeps = {},
+): Promise<{ ok: boolean; path: string; reason?: string; warning?: string }> {
+  if (target.kind === "first-party") return applyFirstPartyDesktop(deps);
+  // Gateway replaces first-party; the two must never be active together.
+  const removed = removeDesktopFirstParty();
+  if (!removed.ok) return { ok: false, path: removed.path, reason: "first_party_settings_unreadable" };
+  const result = await applyProfile(profile, target.mode, deps);
+  if (result.ok && !saveDesktopMode("gateway", deps)) {
+    return { ...result, warning: [result.warning, "desktop mode marker was not saved"].filter(Boolean).join(" ") };
+  }
+  return result;
+}
+
 export async function applyProfile(
   profile: DesktopProfile | undefined,
   mode: Desktop3pConfigMode,
@@ -222,24 +372,41 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
     return 0;
   }
 
-  // Legacy mode flags remain apply aliases and are parsed before subcommands.
-  const legacyFlags = argv.filter(arg => ["--static", "--hybrid", "--discovery-only"].includes(arg));
-  const applyInvocation = argv.length === 0 || command === "apply" || legacyFlags.length > 0;
+  // Mode flags remain apply aliases and are parsed before subcommands.
+  const applyFlags = argv.filter(arg => APPLY_FLAGS.includes(arg));
+  const applyInvocation = argv.length === 0 || command === "apply" || applyFlags.length > 0;
   if (applyInvocation) {
-    const nonMode = argv.filter(arg => !["apply", "--static", "--hybrid", "--discovery-only"].includes(arg));
-    if (nonMode.length > 0) {
-      console.error(`알 수 없는 인자: ${nonMode.join(" ")}`);
-      return 2;
-    }
-    const parsedMode = parseDesktop3pModeArgs(legacyFlags);
-    if ("error" in parsedMode) { console.error(parsedMode.error); return 2; }
+    const rest = argv.filter(arg => arg !== "apply");
+    const parsedTarget = parseDesktopApplyArgs(rest, loadConfig());
+    if ("error" in parsedTarget) { console.error(parsedTarget.error); return 2; }
+    const { target } = parsedTarget;
     try {
-      const result = await applyProfile(undefined, parsedMode.mode, deps);
+      const result = await applyDesktop(undefined, target, deps);
       if (!result.ok) {
         console.error(`설정 적용 실패: ${result.reason ?? "unknown error"}`);
+        if (result.reason?.startsWith("gateway_")) {
+          console.error("The gateway profile could not be removed safely, so first-party mode was not applied. Turn the integration off (dashboard toggle) and retry, or keep gateway with `ocx claude desktop apply --gateway`.");
+        } else if (result.reason === "foreign_env") {
+          console.error(`~/.claude/settings.json already sets HTTPS_PROXY or NODE_EXTRA_CA_CERTS to a value opencodex does not own (${result.path}). Remove them or use --gateway.`);
+        } else if (result.reason === "intercept_disabled") {
+          console.error("First-party mode needs the Claude intercept proxy (claudeCode.intercept.enabled on a hub). Use --gateway instead.");
+        } else if (result.reason === "first_party_requires_local_hub") {
+          console.error("First-party mode runs on the hub machine only; on a connected client use --gateway.");
+        }
         return 1;
       }
-      console.log(`Claude Desktop 설정을 적용했습니다: ${result.path}`);
+      if (target.kind === "first-party") {
+        console.log(`Claude Desktop first-party 설정을 적용했습니다: ${result.path}`);
+        console.log("Desktop 앱 설정은 그대로이며, Code 탭의 Claude Code만 로컬 프록시를 거칩니다.");
+      } else {
+        console.log(`Claude Desktop gateway 설정을 적용했습니다: ${result.path}`);
+        for (const line of gatewayModeExplanation({
+          requestedExplicitly: applyFlags.some(flag => flag !== "--first-party"),
+          config: loadConfig(),
+        })) {
+          console.log(line);
+        }
+      }
       // The write landed; only the bookkeeping marker did not. Saying nothing
       // would leave the saved-vs-applied display wrong with no explanation.
       if (result.warning) console.warn(`⚠️  ${result.warning}`);
@@ -336,7 +503,8 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
       }
       saveLocalDesktopProfile(reconciled, config.claudeCode?.desktopProfile, connection, deps);
       if (flags.includes("--apply")) {
-        const result = await applyProfile(reconciled, "static", deps);
+        // A routing profile is a gateway-mode artifact: importing with --apply installs it there.
+        const result = await applyDesktop(reconciled, { kind: "gateway", mode: "static" }, deps);
         if (!result.ok) { console.error(`프로필은 저장했지만 Desktop 적용에 실패했습니다: ${result.reason ?? "unknown error"}`); return 1; }
         if (result.warning) console.warn(`⚠️  ${result.warning}`);
       }
diff --git a/src/cli/codex-shim-autorestore.ts b/src/cli/codex-shim-autorestore.ts
index 87b59feefbb..a3419e665a1 100644
--- a/src/cli/codex-shim-autorestore.ts
+++ b/src/cli/codex-shim-autorestore.ts
@@ -19,6 +19,9 @@ export function skipsCodexShimAutoRestore(command: string | undefined, args: str
   if (command === "uninstall" || command === "remove") return true;
   // `lab` is read-only inspection; it must not trigger shim side effects.
   if (command === "lab") return true;
+  // `resolve` is read-only inspection for embedding shells: a lookup made to populate
+  // a consent surface must not trigger a shim repair side effect first.
+  if (command === "resolve") return true;
   // The entire updater-inspection namespace is zero-effect, including malformed
   // or future actions. A later `apply` implementation must own its preflight.
   if (command === "system" && args[1] === "codex-cli-update") return true;
diff --git a/src/cli/companion.ts b/src/cli/companion.ts
new file mode 100644
index 00000000000..2b24258fcc3
--- /dev/null
+++ b/src/cli/companion.ts
@@ -0,0 +1,56 @@
+import { CliUsageError, printData, rejectArgs, runCliAction, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx companion [show] [--json]
+  ocx companion set <key>=<value> [...] [--json]
+  ocx companion reset [--json]`;
+
+function parseValue(raw: string): unknown {
+  if (raw === "null") return null;
+  try { return JSON.parse(raw); } catch { return raw; }
+}
+
+async function show(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  printData(await runtimeRequest("/api/companion/settings", {}, deps), wantsJson);
+}
+
+async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  if (args.length === 0) throw new CliUsageError("companion set requires key=value assignments", USAGE);
+  const patch: Record<string, unknown> = {};
+  for (const assignment of args) {
+    const separator = assignment.indexOf("=");
+    if (separator <= 0) throw new CliUsageError(`invalid companion setting "${assignment}"; use key=value`, USAGE);
+    patch[assignment.slice(0, separator)] = parseValue(assignment.slice(separator + 1));
+  }
+  printData(await runtimeRequest("/api/companion/settings", {
+    method: "PUT",
+    body: JSON.stringify({ settings: patch }),
+  }, deps), wantsJson, ["Companion settings saved."]);
+}
+
+async function reset(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  printData(await runtimeRequest("/api/companion/settings", {
+    method: "PUT",
+    body: JSON.stringify({ reset: true }),
+  }, deps), wantsJson, ["Companion settings reset."]);
+}
+
+export async function handleCompanionCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "show", ...rest] = argv;
+    if (sub === "show") await show(rest, deps);
+    else if (sub === "set") await set(rest, deps);
+    else if (sub === "reset") await reset(rest, deps);
+    else throw new CliUsageError(`unknown companion command ${sub}`, USAGE);
+  });
+}
+
+export const COMPANION_USAGE = USAGE;
diff --git a/src/cli/dispatch.ts b/src/cli/dispatch.ts
index 029336f66c9..cea39a48d23 100644
--- a/src/cli/dispatch.ts
+++ b/src/cli/dispatch.ts
@@ -29,6 +29,8 @@ import { stripGrokConfig } from "../grok/inject";
 import { handleRestartScopeAfterWrite, readRestartScope, type RestartScope } from "./restart-scope";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
 import { isJsonOption, takeFlag, terminalSafeError } from "./runtime-api";
+import { printStopSummary, type StopOutcome } from "./stop-report";
+import type { ResolveArgs } from "./resolve";
 import type { ClientConnectionState } from "../client/state";
 import { OCX_NATIVE_REPLAY_RECOVERY_NOTE } from "../responses/compaction";
 
@@ -44,8 +46,9 @@ export interface CliDispatchDeps {
   /** Spawn a detached proxy child (stdio ignore, unref'd, provenance env). */
   spawnDetached: (argv: readonly string[]) => void;
   handleStart: () => Promise<void>;
-  handleStop: () => Promise<boolean>;
+  handleStop: () => Promise<StopOutcome>;
   handleEnsure: (options?: { existingIsSuccess?: boolean }) => Promise<boolean>;
+  handleResolve: (args: ResolveArgs) => Promise<number>;
   handleTrayProxyStart: (existingIsSuccess?: boolean) => Promise<boolean>;
   handleTrayProxyRestart: () => Promise<void>;
   handleRestartStartWhenStopped: () => Promise<boolean | "skipped">;
@@ -98,11 +101,39 @@ const commandRunners: Record<string, CommandRunner> = {
   stop: async deps => {
     // Downtime warning lives HERE, not in handleStop: `restart`/tray-restart callers
     // re-start the proxy immediately, so warning there would contradict the next line.
-    if (await deps.handleStop()) {
-      console.log("⚠️  Codex/Claude requests through the proxy will fail until it is restarted ('ocx start' or 'ocx service start').");
+    const warning = "⚠️  Codex/Claude requests through the proxy will fail until it is restarted ('ocx start' or 'ocx service start').";
+    if (!takeFlag(deps.args.slice(1), "--json")) {
+      // handleStop returns the structured outcome now; an object is always truthy, so
+      // the warning must key on .ok — otherwise a failed stop would still claim downtime.
+      if ((await deps.handleStop()).ok) console.log(warning);
+      return Number(process.exitCode ?? 0);
     }
+    // --json is a reporting layer over the SAME stop path: the receipt, the drain, the
+    // respawn verification and the client-config restore run unchanged. Human output
+    // still prints, but on stderr, so stdout carries exactly one JSON summary document.
+    // The exit code (0/1/79/80) crosses the process boundary untouched — the shell reads
+    // it from the child, and the stop-contract codes must survive the JSON mode.
+    const humanLog = console.log;
+    console.log = console.error;
+    let outcome: StopOutcome | undefined;
+    try {
+      outcome = await deps.handleStop();
+      if (outcome.ok) console.log(warning);
+    } finally {
+      console.log = humanLog;
+    }
+    // A throw above propagates after the finally restores the console, so reaching here
+    // with an undefined outcome cannot happen; the guard keeps the assignment provable.
+    if (outcome) printStopSummary(outcome.summary);
     return Number(process.exitCode ?? 0);
   },
+  resolve: async deps => {
+    // Same fail-closed shape as `ready`: parseCliHead pre-parsed the verb before any
+    // preflight side effect, so a missing resolveArgs means dispatch diverged. Refuse
+    // with code 64 and perform NO I/O.
+    if (!deps.head.resolveArgs) return 64;
+    return await deps.handleResolve(deps.head.resolveArgs);
+  },
   restore: async deps => {
     const restoreArgs = deps.args.slice(1);
     const restoreJson = takeFlag(restoreArgs, "--json");
@@ -615,7 +646,11 @@ const commandRunners: Record<string, CommandRunner> = {
         const guiUrl = selectDefaultGuiUrl(config, live, deps.probeHostname);
         console.log(`Opening ${guiUrl}`);
         const { openUrl } = await import("../lib/open-url");
-        openUrl(guiUrl);
+        // Awaited so a launcher that never opened anything is said out loud (#5261). Still exit
+        // 0: the proxy is serving and the URL above is reachable, only the launch did not happen.
+        if ((await openUrl(guiUrl)).status === "failed") {
+          console.error("⚠️  No browser could be opened here; open the URL above yourself.");
+        }
         return 0;
       },
     });
@@ -782,6 +817,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleComboCommand } = await import("./combo");
     return await handleComboCommand(deps.args.slice(1));
   },
+  companion: async deps => {
+    const { handleCompanionCommand } = await import("./companion");
+    return await handleCompanionCommand(deps.args.slice(1));
+  },
   route: async deps => {
     if (deps.args[1] !== "combo" && deps.args[1] !== "policy") {
       console.error("Usage: ocx route <combo|policy> <subcommand>");
diff --git a/src/cli/ensure-desired-integrations.ts b/src/cli/ensure-desired-integrations.ts
index fe94a0b76e2..6a23b5a00c5 100644
--- a/src/cli/ensure-desired-integrations.ts
+++ b/src/cli/ensure-desired-integrations.ts
@@ -10,7 +10,13 @@
  */
 import { loadConfig } from "../config";
 import { stripGrokConfig, type GrokInjectResult } from "../grok/inject";
-import { removeDesktop3pStandardPivot } from "../claude/desktop-3p";
+import { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot } from "../claude/desktop-3p";
+import {
+  applyDesktopFirstParty,
+  inspectDesktopFirstParty,
+  removeDesktopFirstParty,
+  resolveClaudeDesktopMode,
+} from "../claude/desktop-first-party";
 import {
   claudeDesktopIntegrationEnabled,
   grokIntegrationEnabled,
@@ -35,6 +41,10 @@ export interface EnsureDesiredIntegrationsDeps {
     opts?: { hostname?: string },
   ) => Promise<GrokInjectResult>;
   removeDesktop3pStandardPivot: typeof removeDesktop3pStandardPivot;
+  removeDesktopFirstParty?: typeof removeDesktopFirstParty;
+  applyDesktopFirstParty?: typeof applyDesktopFirstParty;
+  inspectDesktopFirstParty?: typeof inspectDesktopFirstParty;
+  inspectDesktop3pConfigLibrary?: typeof inspectDesktop3pConfigLibrary;
   log?: (message: string) => void;
   error?: (message: string) => void;
 }
@@ -113,16 +123,44 @@ export async function ensureGrokFenceMatchesDesired(
 }
 
 /**
- * When Claude Desktop is durably OFF, clear any leftover owned gateway profile.
- * ensure/update used to leave Claude-3p residue in place after a failed disable
- * (drifted fingerprint), so the Integrations card kept looking applied/stale.
+ * When Claude Desktop is durably OFF, clear any leftover owned gateway profile and the
+ * first-party settings env. ensure/update used to leave Claude-3p residue in place after a
+ * failed disable (drifted fingerprint), so the Integrations card kept looking applied/stale.
+ *
+ * When it is ON in first-party mode, refresh a stale env (the intercept port follows the
+ * public port, so a port change would otherwise leave Claude Code pointed at a dead proxy).
  */
 export function ensureClaudeDesktopMatchesDesired(
   deps: EnsureDesiredIntegrationsDeps = productionDeps,
 ): void {
   const config = deps.loadConfig();
   const { log, error } = io(deps);
-  if (claudeDesktopIntegrationEnabled(config)) return;
+  if (claudeDesktopIntegrationEnabled(config)) {
+    if (resolveClaudeDesktopMode(config) !== "first-party") return;
+    const library = (deps.inspectDesktop3pConfigLibrary ?? inspectDesktop3pConfigLibrary)({
+      appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null,
+    });
+    if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
+      // The mode marker and the disk disagree. Replacing a live Desktop profile is an operator
+      // action, not something an update hook should do silently.
+      error("⚠️  Claude Desktop mode is first-party but a gateway profile is still applied; run `ocx claude desktop apply --first-party` (or `--gateway`) to reconcile.");
+      return;
+    }
+    const seen = (deps.inspectDesktopFirstParty ?? inspectDesktopFirstParty)(config);
+    if (!seen.stale) return;
+    const applied = (deps.applyDesktopFirstParty ?? applyDesktopFirstParty)(config);
+    if (applied.ok && applied.changed) log(`   + Claude Desktop first-party env refreshed (${applied.path})`);
+    else if (!applied.ok) error(`⚠️  Claude Desktop first-party env refresh skipped: ${applied.reason}.`);
+    return;
+  }
+  try {
+    const env = (deps.removeDesktopFirstParty ?? removeDesktopFirstParty)();
+    if (env.ok && env.changed) log("   ↩️  Claude Desktop first-party env removed.");
+    else if (!env.ok) error(`⚠️  Claude Desktop first-party env cleanup skipped: ${env.reason} (${env.path}).`);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    error(`⚠️  Claude Desktop first-party env cleanup failed: ${detail}.`);
+  }
   try {
     const removed = deps.removeDesktop3pStandardPivot({
       appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null,
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 0be199f1a5a..b9b7a6e2e1b 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -1,9 +1,5 @@
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { findCommand } from "./registry";
-
-const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));
+import { packageVersion as readPackageVersion } from "../lib/package-version";
 
 /**
  * Version of the `ocx` bundle this process is running from.
@@ -13,9 +9,7 @@ const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta
  * rather than throwing; callers must treat that as "cannot compare", not as a mismatch.
  */
 export function packageVersion(): string {
-  const raw = readFileSync(join(repoRoot, "package.json"), "utf8");
-  const parsed = JSON.parse(raw) as { version?: unknown };
-  return typeof parsed.version === "string" ? parsed.version : "unknown";
+  return readPackageVersion();
 }
 
 export function printVersion(): void {
@@ -29,9 +23,11 @@ Usage:
   ocx setup                   Interactive setup (alias: init)
   ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]
                               Start the proxy; SOCKS5 defaults to 127.0.0.1:10808
-  ocx stop                    Stop the proxy AND restore native Codex (plain codex works again)
+  ocx stop [--json]           Stop the proxy AND restore native Codex (plain codex works again)
   ocx restore                 Restore native Codex without stopping (alias: eject)
   ocx restore back            Re-point codex at the running proxy (undo restore)
+  ocx restore --remove-codex-provider-table
+                              Also drop [model_providers.opencodex] that a paginated restore kept
   ocx recover-history --legacy-openai --yes
                                Force all user-message opencodex rows to OpenAI (legacy recovery)
   ocx recover-history --ocx-compaction <thread-id> --yes
@@ -67,6 +63,7 @@ Usage:
   ocx health [--json]          Check proxy health (exit 0=healthy, 1=not)
   ocx capabilities [--json]    List declared capabilities and the API routes they drive
   ocx ready [--json] [--wait [--timeout <s>]]  Check post-sync readiness (exit 0 only when ready)
+  ocx resolve [--json]        Config home, effective port, and liveness (JSON for shells)
   ocx provider <sub>          Providers, connectivity, quota, and selected models
   ocx account <sub>           Accounts, login/reauth, key pools, and quota controls
   ocx models <sub>            Live/custom models, visibility, context, and shadow calls
@@ -89,6 +86,7 @@ Usage:
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection
   ocx config <sub>            Validated configuration show/get/set/import/export
+  ocx companion <show|set|reset>  Menu-bar and widget companion usage settings
   ocx lab <sub>               Read-only Compatibility Lab projection inspection
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 00d89469fd3..88ab11392d7 100755
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -1,6 +1,9 @@
 #!/usr/bin/env bun
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
+import { join } from "node:path";
+import { findGuiDist } from "../server/gui-static";
+import { inspectGuiBundleFreshness, staleGuiBundleLines } from "../server/gui-freshness";
 
 // Best-effort recovery for runtime execution and spawned children if launched
 // from an unlinked/deleted working directory (runs after hoisted ESM module imports).
@@ -63,8 +66,8 @@ import {
   pendingTeardownsAreExactly,
   quarantinePendingTeardown,
 } from "../config/pending-teardown";
-import { collectStatus, hubStatusLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
-import { endpointsToProve, everyEndpointProvenDown, sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
+import { collectStatus, deadProxyRoutingAdviceLines, detectMissingCodexCatalogPath, hubStatusLines, missingCodexCatalogLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
+import { endpointsToProve, everyEndpointProvenDownAsync, sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
 import { takeFlag } from "./runtime-api";
 import { parseStartOptions, StartArgsError } from "./start-args";
 
@@ -82,14 +85,24 @@ import { SpendLedgerOwnerError } from "../lib/spend-ledger-owner";
 import { redactUrlForLog } from "../lib/redact";
 import { dispatchCommand, decideBusyPreferredPort, decideStartWithLiveOwner } from "./dispatch";
 import { AuxiliaryListenerBindError, findAvailablePort, isAddrInUse, PortUnavailableError, shouldPersistSelectedPort, waitForPortAvailable } from "../server/ports";
-import { findLiveProxy, probeHostname, probePortOwner, START_OWNERSHIP_LIVENESS, type LiveProxy } from "../server/proxy-liveness";
+import {
+  findLiveProxy,
+  probeEndpointLiveness,
+  probeHostname,
+  probePortOwner,
+  START_OWNERSHIP_LIVENESS,
+  type LiveProxy,
+} from "../server/proxy-liveness";
 import { createReadinessGate } from "../server/readiness";
 import { isApiAuthRequired } from "../server/auth-cors";
 import { runReady, type ReadyArgs } from "./ready";
+import { runResolve, type ResolveArgs } from "./resolve";
+import { summarizeStopRun, type StopOutcome, type StopRunRecord } from "./stop-report";
 import { runCli } from "./root";
 import { isProcessAlive, ProxyOwnershipRefusedError, refusalNextStep, stopProxy } from "../lib/process-control";
 import { startupDataPlaneToken } from "../lib/service-secrets";
-import { assertNotAdminToken, diagnoseService, isServiceOwnershipError, proxyStillLiveAfterStop, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatusSummary, stopServiceIfInstalledDetailed, uninstallServiceIfInstalled, uninstallServiceDetailed } from "../service";
+import { assertNotAdminToken, diagnoseService, isServiceOwnershipError, proxyStillLiveAfterStop, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatePaths, serviceStatusSummary, stopServiceIfInstalledDetailed, uninstallServiceIfInstalled, uninstallServiceDetailed } from "../service";
+import { acquireOwnershipMutationLease } from "../service/ownership-mutation-lease.mjs";
 import { formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
 import { injectSystemEnv, reconcileShellHook, revertSystemEnv, uninstallShellHook } from "../server/system-env";
 import { buildDesktop3pRegistry } from "../claude/desktop-3p";
@@ -98,6 +111,10 @@ import { startHistoryMigrationGuardian } from "../codex/history-migration-guardi
 import { maybeShowStarPrompt } from "./star-prompt";
 import { scheduleCatalogPrewarm } from "./catalog-prewarm";
 import { maybeShowUpdatePrompt } from "../update/notify";
+import {
+  bindAndPublishStartOwnership,
+  StartOwnershipRollbackUncertainError,
+} from "./start-ownership-publication";
 import { syncModelsToCodex } from "../codex/sync";
 import {
   HUB_GATED_SKIP_MESSAGE,
@@ -216,6 +233,13 @@ function startArgv(port?: number): string[] {
   return selfLaunchArgv(args);
 }
 
+class StartCommandExit extends Error {
+  constructor(readonly exitCode: number) {
+    super(`start command exited with code ${exitCode}`);
+    this.name = "StartCommandExit";
+  }
+}
+
 async function chooseListenPort(
   requestedPort?: number,
   options: { sibling?: boolean } = {},
@@ -288,17 +312,17 @@ async function chooseListenPort(
         // Same contract as the pre-bind owner check: the wrapper's retry loop terminates
         // on a zero exit, and the port it was asked to serve is already served.
         console.log(`Proxy already running (PID ${holder?.pid ?? "unknown"}, port ${preferred}); service wrapper staying out of the way.`);
-        process.exit(0);
+        throw new StartCommandExit(0);
       }
       if (decision === "refuse-live-proxy") {
         console.error(`⚠️  Proxy already running (PID ${holder?.pid ?? "unknown"}, port ${preferred}). Use 'ocx stop' first.`);
-        process.exit(1);
+        throw new StartCommandExit(1);
       }
       if (decision === "refuse-unidentified-holder") {
         console.error(`❌ Port ${preferred} is busy and its holder did not identify as opencodex.`);
         console.error("   Starting on another port would leave Codex pointed at a proxy you did not ask for.");
         console.error("   Stop whatever holds that port, or start on a free one with 'ocx start --port <port>'.");
-        process.exit(1);
+        throw new StartCommandExit(1);
       }
       if (preferred > 0) {
         console.log(`⚠️  Port ${preferred} is busy; starting opencodex on ${selected}.`);
@@ -313,7 +337,7 @@ async function chooseListenPort(
     if (err instanceof PortUnavailableError) {
       console.error(`❌ ${err.message}`);
       console.error("   Stop whatever holds that port, or change config.port, then retry.");
-      process.exit(1);
+      throw new StartCommandExit(1);
     }
     throw err;
   }
@@ -443,53 +467,99 @@ async function handleStart(options: { block?: boolean } = {}) {
   // live daemon holding resources while it overwrites its own binary.
   await maybeShowUpdatePrompt();
 
-  // Port selection is check-then-bind: a concurrent `ocx start`/`ensure` can win the port
-  // between the probe and Bun.serve. Soft starts may re-pick; hard-pinned `--port` retries
-  // the same port only (never hop — that was the remaining PR #152 gap).
-  let port = await chooseListenPort(requestedPort, { sibling: siblingStart });
-  const { drainAndShutdown, isRecyclingForExit, startServer } = await import("../server");
-  // One private readiness gate for this startServer invocation, captured by the
-  // listener's closure. handleStart owns it and transitions it after the
-  // post-startup sync settles. A second startServer in the same process would
-  // get its own gate and could never reset/mutate this one.
-  const readinessGate = createReadinessGate();
-  let server: ReturnType<typeof startServer>;
-  const localAttestationSecret = createLocalAttestationSecret();
-  for (let attempt = 0; ; attempt++) {
-    try {
-      server = startServer(port, { localAttestationSecret, readinessGate });
-      // Prewarm the live provider model cache as soon as the port is bound so the
-      // first GUI /v1/models (and syncModelsToCodex below) share one discovery flight
-      // instead of racing duplicate upstream /models fetches.
-      scheduleCatalogPrewarm();
-      break;
-    } catch (err) {
-      if (err instanceof SpendLedgerOwnerError) {
-        console.error(`❌ ${err.message}`);
-        process.exit(1);
-      }
-      if (err instanceof AuxiliaryListenerBindError || !isAddrInUse(err) || attempt >= 2) throw err;
-      if (requestedPort !== undefined) {
-        console.log(`⚠️  Port ${port} was taken while starting; waiting to retry the same port...`);
-        const hostname = loadConfig().hostname ?? "127.0.0.1";
-        const freed = await waitForPortAvailable(port, hostname, { timeoutMs: 3_000, intervalMs: 50 });
-        if (!freed) {
-          console.error(`❌ Port ${port} stayed busy; refusing to hop to an ephemeral port.`);
-          process.exit(1);
+  type StartServerModule = typeof import("../server");
+  type BoundStart = {
+    server: ReturnType<StartServerModule["startServer"]>;
+    serverModule: StartServerModule;
+    port: number;
+    readinessGate: ReturnType<typeof createReadinessGate>;
+    localAttestationSecret: string;
+    config: ReturnType<typeof loadConfig>;
+  };
+  let boundStart: BoundStart;
+  try {
+    boundStart = await bindAndPublishStartOwnership({
+      acquireLease: () => acquireOwnershipMutationLease(serviceStatePaths()),
+      bind: async () => {
+        // The earlier probe owned journal cleanup. This one owns the bind decision: an
+        // updater may have stopped the old runtime and acquired this lease for replacement.
+        const fencedLive = await findLiveProxy(START_OWNERSHIP_LIVENESS);
+        if (fencedLive) {
+          const decision = decideStartWithLiveOwner({
+            livePort: fencedLive.port,
+            requestedPort,
+            ocxService: process.env.OCX_SERVICE,
+          });
+          if (decision === "service-stay-out") {
+            console.log(`Proxy already running (PID ${fencedLive.pid ?? "unknown"}, port ${fencedLive.port}); service wrapper staying out of the way.`);
+            throw new StartCommandExit(0);
+          }
+          if (decision === "refuse") {
+            console.error(`⚠️  Proxy appeared before bind (PID ${fencedLive.pid ?? "unknown"}, port ${fencedLive.port}). Use 'ocx stop' first.`);
+            throw new StartCommandExit(1);
+          }
+          siblingStart = true;
         }
-        continue;
-      }
-      console.log(`⚠️  Port ${port} was taken while starting; picking another...`);
-      port = await chooseListenPort(requestedPort, { sibling: siblingStart });
-    }
+
+        // Port selection is check-then-bind. The lease prevents every cooperating start or
+        // updater from turning that check into a different ownership decision.
+        let port = await chooseListenPort(requestedPort, { sibling: siblingStart });
+        const serverModule = await import("../server");
+        const readinessGate = createReadinessGate();
+        const localAttestationSecret = createLocalAttestationSecret();
+        const config = loadConfig();
+        let server: ReturnType<typeof serverModule.startServer>;
+        for (let attempt = 0; ; attempt++) {
+          try {
+            server = serverModule.startServer(port, { localAttestationSecret, readinessGate });
+            break;
+          } catch (err) {
+            try { await serverModule.waitForFailedStartRollback(err); }
+            catch (rollbackError) {
+              throw new StartOwnershipRollbackUncertainError([err, rollbackError]);
+            }
+            if (err instanceof SpendLedgerOwnerError) {
+              console.error(`❌ ${err.message}`);
+              throw new StartCommandExit(1);
+            }
+            if (err instanceof AuxiliaryListenerBindError || !isAddrInUse(err) || attempt >= 2) throw err;
+            if (requestedPort !== undefined) {
+              console.log(`⚠️  Port ${port} was taken while starting; waiting to retry the same port...`);
+              const hostname = config.hostname ?? "127.0.0.1";
+              const freed = await waitForPortAvailable(port, hostname, { timeoutMs: 3_000, intervalMs: 50 });
+              if (!freed) {
+                console.error(`❌ Port ${port} stayed busy; refusing to hop to an ephemeral port.`);
+                throw new StartCommandExit(1);
+              }
+              continue;
+            }
+            console.log(`⚠️  Port ${port} was taken while starting; picking another...`);
+            port = await chooseListenPort(requestedPort, { sibling: siblingStart });
+          }
+        }
+        return { server, serverModule, port, readinessGate, localAttestationSecret, config };
+      },
+      writePid: () => writePid(process.pid),
+      writeRuntime: bound => writeRuntimePort({
+        pid: process.pid,
+        port: bound.port,
+        hostname: bound.config.hostname,
+        attestationSecret: bound.localAttestationSecret,
+      }),
+      stopBound: bound => bound.server.stop(true),
+      removeRuntime: () => removeRuntimePortIfPidIs(process.pid),
+      removePid: () => removePidIfValueIs(process.pid),
+    });
+  } catch (error) {
+    if (error instanceof StartCommandExit) { process.exitCode = error.exitCode; return; }
+    throw error;
   }
-  // A single request's streaming error must never crash the daemon serving every
-  // other Codex session — capture the full stack to crash.log and stay up.
-  installCrashGuards();
-  writePid(process.pid);
 
-  const config = loadConfig();
-  writeRuntimePort({ pid: process.pid, port, hostname: config.hostname, attestationSecret: localAttestationSecret });
+  const { server, serverModule, port, readinessGate, config } = boundStart;
+  const { drainAndShutdown, isRecyclingForExit } = serverModule;
+  // Records are visible now; background work may observe this runtime without a gap.
+  scheduleCatalogPrewarm();
+  installCrashGuards();
   // No pre-emptive snapshot here. `injectCodexConfig` journals the exact bytes it
   // is about to transform; snapshotting earlier only captured a baseline that could
   // already be stale by the time injection ran (#477).
@@ -597,11 +667,11 @@ async function handleStart(options: { block?: boolean } = {}) {
       try {
         const { fetchAllModels } = await import("../server/management-api");
         const { desktopVisibleNativeSlugs } = await import("../codex/catalog");
-        const { resolveCodexModelEntitlements } = await import("../codex/model-entitlements");
+        const { resolveAdmittedCodexModelEntitlements } = await import("../codex/model-entitlement-admission");
         const { buildDesktopDiscoveryInputs } = await import("../claude/desktop-discovery-inputs");
         const [models, modelEntitlements] = await Promise.all([
           fetchAllModels(config),
-          resolveCodexModelEntitlements(config, { clientVersion: null }),
+          resolveAdmittedCodexModelEntitlements(config, { clientVersion: null }),
         ]);
         const inputs = buildDesktopDiscoveryInputs({
           config, models, modelEntitlements,
@@ -921,6 +991,12 @@ async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boole
 }
 
 async function handleStop() {
+  const lease = acquireOwnershipMutationLease(serviceStatePaths());
+  try { return await handleStopUnlocked(); }
+  finally { lease.release(); }
+}
+
+async function handleStopUnlocked() {
   // The receipt must name the endpoint the owner was stopping — an obligation nobody can
   // locate cannot be proven discharged. Only the runtime record knows it; a proxy started
   // with an explicit --port is not on the configured one.
@@ -952,8 +1028,7 @@ async function handleStop() {
     // An obligation that cannot name its endpoint cannot be proven discharged.
     if (!endpoint) return false;
     try {
-      const { probeProxyLiveness } = await import("../update/proxy-liveness-probe.mjs");
-      return probeProxyLiveness(endpoint.port, endpoint.hostname) === "dead";
+      return await probeEndpointLiveness(endpoint) === "dead";
     } catch {
       // A probe that could not run is not evidence of absence.
       return false;
@@ -977,6 +1052,16 @@ async function handleStop() {
   // service — the exact failure this flag prevents. A plain stop failure is different: we
   // tried, so local teardown still proceeds.
   let ownershipBlocked = false;
+  // Structured twin of the human lines below, for `ocx stop --json`: one document the
+  // desktop shell can read across the process boundary (D4). Every field is assigned
+  // where the corresponding boolean already flips — the summarizer never re-decides.
+  const record: StopRunRecord = {
+    service: "absent",
+    proxy: "unknown",
+    sharedTeardown: "skipped",
+    inheritedTeardownBlocks: false,
+    receiptClearFailed: false,
+  };
   // Deferring shared teardown to this process is an obligation, so record it on disk
   // before asking for it (#3008). A parent that dies mid-stop would otherwise leave the
   // client config routed at a proxy that is already gone, with nothing to find later.
@@ -1054,6 +1139,7 @@ async function handleStop() {
   };
   try {
     const serviceStop = stopServiceIfInstalledDetailed();
+    record.service = serviceStop;
     stoppedService = serviceStop === "stopped" || serviceStop === "stopped-respawnable";
     schedulerCanRespawn = serviceStop === "stopped-respawnable";
     // No "won't respawn" claim here: a stopped Task Scheduler can still respawn through
@@ -1074,6 +1160,7 @@ async function handleStop() {
       console.error("   Run 'ocx service status' to see the query error, repair Task Scheduler access, then retry.");
     }
   } catch (err) {
+    record.service = "error";
     if (isServiceOwnershipError(err)) {
       ownershipBlocked = true;
       stopFailed = true;
@@ -1097,8 +1184,10 @@ async function handleStop() {
       console.log(`✅ Proxy (PID ${pid}) stopped.`);
       removePid(pid);
       removeRuntimePort(pid);
+      record.proxy = "stopped";
     } catch (err) {
       stopFailed = true;
+      record.proxy = err instanceof ProxyOwnershipRefusedError ? "ownership-refused" : "stop-failed";
       console.error(`❌ Failed to stop proxy (PID ${pid}).`);
       // stopProxy throws with the reason — an ownership refusal (409) carries the
       // remediation ("run the stop from that home"). Swallowing it leaves the operator
@@ -1133,8 +1222,10 @@ async function handleStop() {
           { hostname: live.hostname ?? "127.0.0.1", port: live.port },
         );
         console.log(`✅ Proxy (PID ${live.pid}) stopped.`);
+        record.proxy = "stopped-orphan";
       } catch (err) {
         stopFailed = true;
+        record.proxy = err instanceof ProxyOwnershipRefusedError ? "ownership-refused" : "stop-failed";
         console.error(`❌ Failed to stop proxy (PID ${live.pid}).`);
         const detail = err instanceof Error ? err.message : String(err);
         if (detail) console.error(`   ${detail}`);
@@ -1152,12 +1243,14 @@ async function handleStop() {
       // under a proxy that is still serving — the exact failure the deferral exists to
       // prevent, arrived at from the other direction.
       stopFailed = true;
+      record.proxy = "unresolvable-pid";
       ownershipBlocked = true;
       console.error(`❌ A proxy is answering on port ${live.port}, but no process id could be resolved for it, so it cannot be stopped from here.`);
       console.error("   Skipping shared teardown: restoring client config while it serves would leave both pointing at each other.");
       console.error("   Stop it from the home that started it, or end the process manually, then rerun 'ocx stop'.");
-    } else if (!stoppedService) {
-      console.log("No running proxy found.");
+    } else {
+      record.proxy = "not-running";
+      if (!stoppedService) console.log("No running proxy found.");
     }
     if (!stopFailed) {
       // `readPid() === null` means the snapshotted pid file was absent, invalid, dead, or
@@ -1180,6 +1273,7 @@ async function handleStop() {
     const survivor = await proxyStillLiveAfterStop({ canRespawn: true });
     if (survivor) {
       stopFailed = true;
+      record.proxy = "respawned";
       console.error(`❌ A proxy is still listening on port ${survivor.port} after the service stop; it is being respawned.`);
       console.error("   Skipping shared teardown: restoring client config while the proxy runs leaves both pointing at each other.");
       ownershipBlocked = true;
@@ -1215,6 +1309,7 @@ async function handleStop() {
         // No file, no nonce: nothing to quarantine and nothing to remove. The home itself
         // may be hiding an obligation, so block and ask for the directory to be fixed.
         inheritedBlocks = true;
+        record.inheritedTeardownBlocks = true;
         stopFailed = true;
         console.error(`❌ ${read.detail}, so this stop cannot tell whether a shared teardown is still owed.`);
         console.error("   Skipping shared teardown. Fix access to the opencodex home, then rerun 'ocx stop'.");
@@ -1223,6 +1318,7 @@ async function handleStop() {
       if (read.state === "invalid") {
         unreadable.push(read);
         inheritedBlocks = true;
+        record.inheritedTeardownBlocks = true;
         stopFailed = true;
         console.error(`❌ A pending-teardown receipt could not be read (${read.detail}).`);
         console.error("   It names no endpoint, so this stop cannot prove the proxy it belonged to is down.");
@@ -1234,6 +1330,7 @@ async function handleStop() {
         // proxy on an explicit --port can be respawned there while this address refuses,
         // so "dead" here proves nothing and must not authorize a restore.
         inheritedBlocks = true;
+        record.inheritedTeardownBlocks = true;
         stopFailed = true;
         console.error("❌ A shared teardown from an earlier stop is outstanding, but that stop could not record the address it was stopping.");
         console.error(`   Only the configured address (${read.receipt.endpoint.hostname}:${read.receipt.endpoint.port}) was recorded, which cannot prove the right proxy is down.`);
@@ -1245,12 +1342,14 @@ async function handleStop() {
         continue;
       }
       inheritedBlocks = true;
+      record.inheritedTeardownBlocks = true;
       stopFailed = true;
       console.error(`❌ A shared teardown from an earlier stop is still outstanding, and the proxy on ${read.receipt.endpoint.hostname}:${read.receipt.endpoint.port} could not be confirmed down.`);
       console.error("   Skipping shared teardown: restoring client config under a proxy that may still be running is what the deferral exists to prevent.");
       console.error("   The obligation is preserved; retry once the proxy is confirmed stopped.");
     }
   }
+  if (nativeRestoreHandledByProxy) record.sharedTeardown = "performed-by-proxy";
   const restoreBlocked = ownershipBlocked || inheritedBlocks || nativeRestoreHandledByProxy;
   if (!restoreBlocked) {
     if (recoveredNonces.length > 0) {
@@ -1259,6 +1358,7 @@ async function handleStop() {
       console.log("↩️  Finishing a shared teardown left unfinished by an earlier stop.");
     }
     const restore = await restoreSharedClientStateAfterStop();
+    record.sharedTeardown = restore.historyDeferred ? "refused" : restore.other ? "failed" : "restored";
     if (restore.other) stopFailed = true;
     else if (restore.historyDeferred) historyDeferredNonces = teardownNonce ? [teardownNonce, ...recoveredNonces] : recoveredNonces;
     else if (restore.historyOnly) historyOnlyFailure = true;
@@ -1284,6 +1384,7 @@ async function handleStop() {
         // removal is surfaced rather than swallowed.
         if (!clearPendingTeardown(nonce)) {
           stopFailed = true;
+          record.receiptClearFailed = true;
           console.error(`❌ The shared teardown finished, but its receipt could not be removed: ${pendingTeardownPathFor(nonce)}`);
           console.error("   Remove it manually; otherwise every later stop and update will try to recover it again.");
         }
@@ -1328,18 +1429,23 @@ async function handleStop() {
       ? STOP_HISTORY_DEFERRED_EXIT_CODE
       : 1;
   }
-  return !stopFailed;
+  const summary = summarizeStopRun(record, {
+    failed: stopFailed,
+    historyOnly: historyOnlyFailure,
+    historyDeferred: historyDeferredNonces !== null,
+    exitCode: Number(process.exitCode ?? 0),
+  });
+  return { ok: !stopFailed, summary };
 }
 
 async function handleUninstall() {
   /** Definitive "nothing is answering" on the endpoint this home would serve. */
   const proxyEndpointProvenDown = async (): Promise<boolean> => {
     try {
-      const { probeProxyLiveness } = await import("../update/proxy-liveness-probe.mjs");
       // Every candidate, not just the preferred one: a stale runtime record pointing at a
       // closed port would otherwise "prove" a live proxy on the configured port is gone.
       const endpoints = endpointsToProve(readRuntimePort(), loadConfig());
-      return everyEndpointProvenDown(endpoints, e => probeProxyLiveness(e.port, e.hostname));
+      return await everyEndpointProvenDownAsync(endpoints, probeEndpointLiveness);
     } catch {
       return false;
     }
@@ -1586,8 +1692,26 @@ async function handleStatus() {
     console.log(installed
       ? "     Restart with 'ocx start', or refresh the installed service: 'ocx service repair'."
       : "     Restart with 'ocx start', or install the persistent service: 'ocx service install'.");
+    // Restarting is only half the choice. A user who cannot sign in to Codex at all needs the
+    // way out that does not require this proxy to come back (#5261).
+    for (const line of deadProxyRoutingAdviceLines({
+      proxyUp: false,
+      routingKind: status.json.startup.routingKind,
+    })) {
+      console.log(`     ${line}`);
+    }
   }
   console.log(`   Dashboard: ${status.json.dashboard.url}${local}`);
+  // The dashboard is a build artifact, so a checkout that moved without `bun run build:gui` keeps
+  // serving the previous bundle and every feature added since simply does not appear (#5196's
+  // usage panel was invisible this way for five days). Reported next to the dashboard URL, which
+  // is where someone looks when the page is wrong.
+  for (const line of staleGuiBundleLines(inspectGuiBundleFreshness({
+    bundlePath: findGuiDist(),
+    sourcePath: join(import.meta.dir, "..", "..", "gui", "src"),
+  }))) {
+    console.log(`     ${line}`);
+  }
   console.log(`   Config: ${status.json.paths.config}${local}`);
   console.log(`   PID file: ${status.json.paths.pid}${local}`);
   console.log(`   Runtime: ${status.json.paths.runtime}${local}`);
@@ -1606,6 +1730,12 @@ async function handleStatus() {
   console.log(`   Codex autostart: ${status.json.codexAutostart ? "enabled" : "disabled"}${local}`);
   console.log(`   Restart safety: ${startupHealthSummary(status.json.startup)}${local}`);
   console.log(`   ${formatStartupRoutingDetail(status.json.startup)}${local}`);
+  // Independent of whether the proxy is up: a catalog pointer whose file is gone stops Codex
+  // loading its config at all, and presents as the same blank wall as dead routing (#5261).
+  // Tagged `(local)` on its header like every other local-state line, so a connected client
+  // cannot read a finding about its own Codex home as something the hub reported.
+  missingCodexCatalogLines(detectMissingCodexCatalogPath())
+    .forEach((line, index) => console.log(`   ${line}${index === 0 ? local : ""}`));
   if (status.json.startup.routingKind === "native") {
     let retainedProviderTable = false;
     try {
@@ -1734,6 +1864,14 @@ async function handleReady(args: ReadyArgs): Promise<number> {
   return runReady(args);
 }
 
+/**
+ * `ocx resolve` — argument parsing already happened in src/cli/root.ts (before any
+ * preflight side effect), so this handler only runs the runner and returns its exit code.
+ */
+async function handleResolve(args: ResolveArgs): Promise<number> {
+  return runResolve(args);
+}
+
 process.exit(await dispatchCommand(head, {
   args,
   command,
@@ -1754,6 +1892,7 @@ process.exit(await dispatchCommand(head, {
   },
   handleStart,
   handleStop,
+  handleResolve,
   handleEnsure,
   handleTrayProxyStart,
   handleTrayProxyRestart,
diff --git a/src/cli/init.ts b/src/cli/init.ts
index f310b7f7966..e53b203415a 100644
--- a/src/cli/init.ts
+++ b/src/cli/init.ts
@@ -253,6 +253,14 @@ export async function runInit(): Promise<void> {
     }
 
     console.log(`\n🚀 Setup complete! Run 'ocx start' to start the proxy.`);
+    // Said after the autostart choice, because the choice is what decides whether it applies.
+    // Setup otherwise ends on a success line while leaving a restart dependency unmentioned.
+    try {
+      const { collectStartupHealth, injectedRoutingRestartWarningLines } = await import("../codex/autostart-health");
+      for (const line of injectedRoutingRestartWarningLines(collectStartupHealth(config))) console.log(line);
+    } catch {
+      // A diagnostic that cannot be computed must not fail a completed setup.
+    }
     for (const line of modelSelectionGuidance(providerName)) console.log(line);
   } catch (error) {
     if (error instanceof InitCancelledError) {
diff --git a/src/cli/integrations.ts b/src/cli/integrations.ts
index 5b690a6c8b5..acfda37b4fa 100644
--- a/src/cli/integrations.ts
+++ b/src/cli/integrations.ts
@@ -229,7 +229,13 @@ export async function handleClientIntegrationCommand(
           ? profiles.map(row => `${String(row.profileId)}  ${String(row.name ?? "Aside")}: ${row.enabled ? "on" : "off"} (${String(row.state)})${row.current ? " [current]" : ""}`)
           : [String((result as { error?: string }).error ?? "No Aside profiles found.")]
         : rows
-        ? rows.map(row => `${String(row.clientId)}: ${String(row.state)}${row.installed ? "" : " (not installed)"}`)
+        /*
+         * `supersededBy` is named here and not only in the single-client view
+         * because this list is where a user looks to see that everything is
+         * connected, and "current" alone is exactly the reassurance that hid a
+         * client reading a file opencodex does not write.
+         */
+        ? rows.map(row => `${String(row.clientId)}: ${String(row.state)}${row.installed ? "" : " (not installed)"}${row.supersededBy ? " (client reads another file)" : ""}`)
         : singleClientStatusLines(result));
       return;
     }
diff --git a/src/cli/registry.ts b/src/cli/registry.ts
index f9b9d95d969..6e4756c1664 100644
--- a/src/cli/registry.ts
+++ b/src/cli/registry.ts
@@ -29,18 +29,32 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "--socks5-off          Clear a saved SOCKS5 outbound proxy from config.proxy.",
     ],
   },
-  { name: "stop", usage: "ocx stop", summary: "Stop the proxy and restore native Codex config." },
+  {
+    name: "stop",
+    usage: "ocx stop [--json]",
+    summary: "Stop the proxy and restore native Codex config.",
+    details: [
+      "--json keeps the stop path unchanged and prints one structured summary document on stdout; human output moves to stderr.",
+      "Exit codes are identical with and without --json: 0, 1, 79 (history cleanup incomplete), 80 (teardown deferred).",
+    ],
+  },
   {
     name: "restore",
     aliases: ["eject"],
     usage: "ocx restore [back]",
     summary: "Restore native Codex config without stopping the proxy; `restore back` re-points codex at the running proxy.",
+    details: [
+      "--remove-codex-provider-table  Also remove [model_providers.opencodex] when a paginated home made restore keep it. Conversations tagged opencodex stop opening.",
+    ],
   },
   {
     name: "eject",
     aliases: [],
     usage: "ocx eject [back]",
     summary: "Restore native Codex config without stopping the proxy; `eject back` re-points codex at the running proxy.",
+    details: [
+      "--remove-codex-provider-table  Also remove [model_providers.opencodex] when a paginated home made restore keep it. Conversations tagged opencodex stop opening.",
+    ],
   },
   {
     name: "recover-history",
@@ -94,9 +108,10 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   {
     name: "tray",
     usage: "ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]",
-    summary: "Install and control the Windows status tray icon.",
+    summary: "Install and control the Windows status tray icon (deprecated in favor of the desktop app).",
     details: [
       "The tray starts at Windows login and provides one-click proxy controls.",
+      "Deprecated: the OpenCodex desktop app provides the tray on Windows, macOS, and Linux; `ocx tray` remains for installs without the desktop app.",
       "Tray start/stop controls the icon only; use its menu to start or stop the proxy.",
       "--no-start (install only) installs the tray without launching it immediately.",
     ],
@@ -298,6 +313,16 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx model <subcommand>",
     summary: "Alias of ocx models.",
   },
+  {
+    name: "companion",
+    usage: "ocx companion <show|set|reset> ...",
+    summary: "Inspect and configure menu-bar and widget companion usage settings.",
+    details: [
+      "ocx companion and ocx companion show read settings; use --json for machine-readable output.",
+      "ocx companion set accepts one or more key=value assignments; values are parsed as JSON when possible.",
+      "ocx companion reset restores the default settings.",
+    ],
+  },
   {
     name: "combo",
     usage: "ocx combo <list|show|set|remove> ...",
@@ -480,6 +505,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     details: [
       "Alias of ocx integration client <sub> --client zcode.",
       "enable writes the managed provider.opencodex block into ~/.zcode/v2/config.json; disable removes only that block.",
+      "ZCode 3.14 moved its providers to ~/.zcode/v2/provider_config.json; where that file exists, enable is refused because the write cannot reach the client.",
       "ZCode reads its config at startup — restart ZCode after enable/disable.",
       "Select OpenCodex Proxy/<provider>/<model> from ZCode's model picker.",
     ],
@@ -531,6 +557,19 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Invalid or unknown arguments exit 64. Not-ready, pending, failed, timeout, and unreachable exit 1.",
     ],
   },
+  {
+    name: "resolve",
+    usage: "ocx resolve [--json]",
+    summary: "Emit the resolved config home, effective port, and identity-checked proxy liveness as one JSON document.",
+    details: [
+      "Machine surface for embedding shells: it replaces a second home/port/liveness implementation beside the CLI.",
+      "The port is the live listener's port when an opencodex proxy answers, otherwise the configured port (default 10100).",
+      "Liveness is three-valued: live, absent-proven (every recorded and configured endpoint definitively dead), or unknown — unknown exits 1 and never reads as absent.",
+      "--json emits one versioned document (schema ocx-resolve/1); the default prints two human lines.",
+      "Exit 0 carries a trustworthy verdict; exit 1 means the CLI could not resolve (invalid config or undecidable liveness) and callers must refuse to guess.",
+      "Any unknown argument exits 64 before preflight side effects.",
+    ],
+  },
   {
     name: "lab",
     usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog> [options] [--json]",
diff --git a/src/cli/resolve.ts b/src/cli/resolve.ts
new file mode 100644
index 00000000000..87c3fa69174
--- /dev/null
+++ b/src/cli/resolve.ts
@@ -0,0 +1,230 @@
+/**
+ * `ocx resolve` — the machine-readable runtime resolution surface for an embedding shell.
+ *
+ * D5 of devlog/_plan/260921_app_runtime_ownership/: the desktop shell must stop resolving
+ * the config home, the port and liveness itself. The tuned probe budgets in
+ * src/server/proxy-liveness.ts exist because a shell-side reimplementation answered
+ * "nobody listening" twice and started duplicate proxies; this verb exposes that module's
+ * verdict instead of copying it, alongside src/config/paths.ts (the home) and the CLI's
+ * own preferred-port selection (`config.port ?? 10100` — resolve takes no --port).
+ *
+ * Contract:
+ *  - `--json` puts exactly ONE JSON document on stdout, versioned by `schema`; the
+ *    default prints two human lines, the same opt-in split as `ocx ready --json`.
+ *  - liveness has three answers, not two: "live", "absent-proven" (every recorded and
+ *    configured endpoint definitively refused or answered non-opencodex), and unknown.
+ *    Unknown NEVER reaches the wire as absent — a probe that timed out, a listener that
+ *    withheld /healthz, or an identity mismatch exits 1 instead. Only "absent-proven"
+ *    may authorise starting a new runtime.
+ *  - exit 0 whenever a trustworthy verdict exists — live, or proven absent. A MISSING
+ *    config.json is defaults, not an error.
+ *  - exit 1 when the CLI cannot resolve: an invalid config.json must NOT be answered
+ *    with `loadConfig`'s repair-to-defaults behaviour, because that hands the caller
+ *    a guessed port; and unknown liveness must not be answered as absence.
+ *  - exit 64 for any argument, pre-parsed in src/cli/root.ts before preflight side
+ *    effects, mirroring `ocx ready`. The verb is read-only and listed in
+ *    skipsCodexShimAutoRestore, so a lookup made to populate a consent surface never
+ *    triggers a shim repair side effect.
+ *
+ * Discovery uses the START_OWNERSHIP_LIVENESS budget, not the 750ms single-shot default:
+ * the shell's launch decision keys on this verdict, and answering "nobody" for a slow
+ * live proxy is the duplicate-proxy decision the start path tunes against (#5004).
+ *
+ * Lives outside cli/index.ts (which dispatches argv at module top level) so tests can
+ * import it, the same split as ready.ts.
+ */
+import { readConfigDiagnostics, type ConfigDiagnostics } from "../config";
+import { getConfigDir } from "../config/paths";
+import { readRuntimePort } from "../config/process-state";
+import { packageVersion } from "../lib/package-version";
+import {
+  findLiveProxy,
+  probeEndpointLiveness,
+  START_OWNERSHIP_LIVENESS,
+  type EndpointLiveness,
+  type LiveProxy,
+} from "../server/proxy-liveness";
+import { endpointsToProve, everyEndpointProvenDownAsync, type ProbeEndpoint } from "./uninstall-plan";
+
+/** Wire version of the resolve document. Bump only on an incompatible shape change. */
+export const RESOLVE_SCHEMA = "ocx-resolve/1";
+
+/** The port every preferred-port selection in the CLI falls back to. */
+export const RESOLVE_DEFAULT_PORT = 10100;
+
+export interface ResolveLivenessJson {
+  /**
+   * "live" when the identity-checked probe found our proxy; "absent-proven" when every
+   * recorded and configured endpoint is definitively dead. The third state — unknown —
+   * exits 1 before this document is printed, so it never appears on the wire as absence.
+   */
+  status: "live" | "absent-proven";
+  pid: number | null;
+  port: number | null;
+  /** Raw bind hostname that answered; compose probe URLs via probeHostname semantics. */
+  hostname?: string;
+  /** Where the verdict came from: the runtime record, or the configured listen port. */
+  source: LiveProxy["source"] | null;
+  /** Version the live proxy reported on /healthz, when it reported one. */
+  version?: string;
+  /** Listener role the live proxy reported, when it reported one ("client" = connected client). */
+  role?: string;
+}
+
+export interface ResolveJson {
+  schema: typeof RESOLVE_SCHEMA;
+  /** Version of this CLI binary, so a shell can compare its engine against the live proxy. */
+  cliVersion: string;
+  /** Resolved opencodex home (OPENCODEX_HOME or ~/.opencodex), from src/config/paths.ts. */
+  configHome: string;
+  port: {
+    /** The port a client should use: the live listener's port when one answers, else the configured one. */
+    effective: number;
+    /** The configured listen port (config.port ?? 10100); what a start would prefer. */
+    configured: number;
+    /** Whether `effective` came from a live proxy or from configuration. */
+    source: LiveProxy["source"];
+  };
+  liveness: ResolveLivenessJson;
+}
+
+export interface ResolveArgs {
+  json: boolean;
+}
+
+export type ResolveParseResult = { ok: true; args: ResolveArgs } | { ok: false; code: 64 };
+
+/** Pure argument parser: the only flag is `--json`. */
+export function parseResolveArgs(argv: string[]): ResolveParseResult {
+  for (const flag of argv) {
+    if (flag !== "--json") return { ok: false, code: 64 };
+  }
+  return { ok: true, args: { json: argv.includes("--json") } };
+}
+
+export interface ResolveIo {
+  configDir?: () => string;
+  readDiagnostics?: () => ConfigDiagnostics;
+  findLive?: () => Promise<LiveProxy | null>;
+  /** Runtime-port record reader; production default is readRuntimePort. */
+  readRuntime?: () => { port?: number; hostname?: string } | null;
+  /** Tri-state endpoint probe; production default runs in-process for compiled standalone binaries. */
+  probeEndpoint?: (endpoint: ProbeEndpoint) => EndpointLiveness | Promise<EndpointLiveness>;
+  cliVersion?: () => string;
+  stdout?: { log: (s: string) => void };
+  stderr?: { error: (s: string) => void };
+}
+
+function livenessJson(live: LiveProxy | null): ResolveLivenessJson {
+  // Reaching here with null means absence was PROVEN by the caller (unknown exits 1
+  // before this document is built).
+  if (!live) return { status: "absent-proven", pid: null, port: null, source: null };
+  return {
+    status: "live",
+    pid: live.pid,
+    port: live.port,
+    source: live.source,
+    ...(live.hostname === undefined ? {} : { hostname: live.hostname }),
+    ...(live.version === undefined ? {} : { version: live.version }),
+    ...(live.role === undefined ? {} : { role: live.role }),
+  };
+}
+
+/** Pure shaper: one live verdict plus configuration becomes the wire document. */
+export function buildResolveJson(
+  config: { port?: number },
+  live: LiveProxy | null,
+  configHome: string,
+  cliVersion: string,
+): ResolveJson {
+  const configured = config.port ?? RESOLVE_DEFAULT_PORT;
+  return {
+    schema: RESOLVE_SCHEMA,
+    cliVersion,
+    configHome,
+    port: {
+      effective: live ? live.port : configured,
+      configured,
+      source: live ? live.source : "config",
+    },
+    liveness: livenessJson(live),
+  };
+}
+
+/**
+ * Human form: two lines, no prose flourish — an operator skims it, a shell uses --json.
+ */
+function reportHuman(json: ResolveJson, stdout: { log: (s: string) => void }): void {
+  stdout.log(`Config home: ${json.configHome}`);
+  const live = json.liveness;
+  if (live.status === "live") {
+    const pidText = live.pid === null ? "unknown" : String(live.pid);
+    const versionText = live.version ?? "unknown version";
+    stdout.log(`Proxy live on port ${json.port.effective} (PID ${pidText}, ${versionText}); effective port ${json.port.effective}.`);
+  } else {
+    stdout.log(`No live proxy (absence proven); effective port ${json.port.effective} (configured).`);
+  }
+}
+
+/**
+ * Run `ocx resolve` over injected I/O. Returns the exit code. The production defaults
+ * read config through the diagnostics surface (which distinguishes missing, valid and
+ * invalid instead of repairing to defaults) and perform one identity-checked discovery
+ * at the ownership-safe budget — resolve adds no probing policy of its own.
+ */
+export async function runResolve(args: ResolveArgs, io: ResolveIo = {}): Promise<number> {
+  const stdout = io.stdout ?? console;
+  const stderr = io.stderr ?? console;
+  const configDir = io.configDir ?? getConfigDir;
+  const readDiagnostics = io.readDiagnostics ?? readConfigDiagnostics;
+  const findLive = io.findLive ?? (() => findLiveProxy(START_OWNERSHIP_LIVENESS));
+  const readRuntime = io.readRuntime ?? readRuntimePort;
+  const probeEndpoint = io.probeEndpoint ?? probeEndpointLiveness;
+  const cliVersion = io.cliVersion ?? packageVersion;
+  const configHome = configDir();
+  let diagnostics: ConfigDiagnostics;
+  try {
+    diagnostics = readDiagnostics();
+  } catch (error) {
+    // A resolution that could not run must not read as "no proxy": the caller has to
+    // refuse to guess (D5) rather than treat this as a proven-absent verdict.
+    stderr.error(`resolve failed: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  if (diagnostics.source === "fallback") {
+    // An invalid config must not resolve to defaults: the effective port would be a
+    // guess at 10100 while the operator's config.port is unread. The repair-to-defaults
+    // policy in loadConfig is for interactive recovery, not for a shell contract.
+    stderr.error(`resolve failed: the config in ${configHome} is invalid (${diagnostics.error ?? "unknown error"}); refusing to guess.`);
+    return 1;
+  }
+  let live: LiveProxy | null;
+  try {
+    live = await findLive();
+  } catch (error) {
+    stderr.error(`resolve failed: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  if (!live) {
+    // findLiveProxy collapses "definitely nothing" and "could not tell" into the same
+    // null. The launch decision keys on this verdict, so resolve owes the caller the
+    // tri-state answer the updater already enforces: only EVERY candidate definitively
+    // dead is absence. Anything else is unknown, and unknown exits 1 — it must never
+    // authorise starting a second runtime.
+    let provenDown = false;
+    try {
+      provenDown = await everyEndpointProvenDownAsync(endpointsToProve(readRuntime(), diagnostics.config), probeEndpoint);
+    } catch {
+      // A probe that cannot run is not evidence of absence.
+      provenDown = false;
+    }
+    if (!provenDown) {
+      stderr.error("resolve: liveness is unknown (a probe timed out or a listener withheld /healthz); refusing to treat unknown as absent.");
+      return 1;
+    }
+  }
+  const json = buildResolveJson(diagnostics.config, live, configHome, cliVersion());
+  if (args.json) stdout.log(JSON.stringify(json));
+  else reportHuman(json, stdout);
+  return 0;
+}
diff --git a/src/cli/root.ts b/src/cli/root.ts
index 65eaf21cda0..9ff8d63353c 100644
--- a/src/cli/root.ts
+++ b/src/cli/root.ts
@@ -10,16 +10,19 @@
  */
 import { hasHelpFlag, printSubcommandUsage, printUsage, printVersion } from "./help";
 import { parseReadyArgs, type ReadyArgs } from "./ready";
+import { parseResolveArgs, type ResolveArgs } from "./resolve";
 import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
 
 export interface CliHead {
-  kind: "version" | "help" | "ready" | "command";
+  kind: "version" | "help" | "ready" | "resolve" | "command";
   command: string | undefined;
   args: string[];
   /** For kind "help": the subcommand whose usage should print, if any. */
   helpTarget?: string;
   /** Present only for `ready`; undefined when the ready args failed to parse. */
   readyArgs?: ReadyArgs;
+  /** Present only for `resolve`; undefined when the resolve args failed to parse. */
+  resolveArgs?: ResolveArgs;
 }
 
 export function parseCliHead(argv: string[]): CliHead {
@@ -51,6 +54,13 @@ export function parseCliHead(argv: string[]): CliHead {
     if (!parsed.ok) return { kind: "ready", command, args, readyArgs: undefined };
     return { kind: "ready", command, args, readyArgs: parsed.args };
   }
+  // Same ordering contract as `ready`: `ocx resolve` rejects any argument with exit
+  // 64 BEFORE maybeAutoRestoreCodexShim (or any other preflight with side effects) runs.
+  if (command === "resolve") {
+    const parsed = parseResolveArgs(args.slice(1));
+    if (!parsed.ok) return { kind: "resolve", command, args, resolveArgs: undefined };
+    return { kind: "resolve", command, args, resolveArgs: parsed.args };
+  }
   return { kind: "command", command, args };
 }
 
@@ -79,6 +89,19 @@ export async function runCli(argv: string[]): Promise<CliHead> {
       maybeAutoRestoreCodexShim(head.command, head.args);
       return head;
     }
+    case "resolve": {
+      // Fail-closed impossible-state guard, mirroring ready: the pre-parse above already
+      // rejected invalid arguments before any preflight, so a missing resolveArgs means
+      // dispatch diverged. Refuse with code 64 and perform NO I/O.
+      if (!head.resolveArgs) {
+        console.error("Usage: ocx resolve [--json]");
+        console.error("  --json prints one JSON document: the config home, the effective port,");
+        console.error("  and the identity-checked liveness verdict.");
+        process.exit(64);
+      }
+      maybeAutoRestoreCodexShim(head.command, head.args);
+      return head;
+    }
     case "command":
       maybeAutoRestoreCodexShim(head.command, head.args);
       return head;
diff --git a/src/cli/start-ownership-publication.ts b/src/cli/start-ownership-publication.ts
new file mode 100644
index 00000000000..33cdb428655
--- /dev/null
+++ b/src/cli/start-ownership-publication.ts
@@ -0,0 +1,56 @@
+export interface StartOwnershipLease {
+  release(): void;
+}
+
+export class StartOwnershipRollbackUncertainError extends AggregateError {
+  constructor(errors: Iterable<unknown>) {
+    super(errors, "start listener rollback could not be proven complete");
+    this.name = "StartOwnershipRollbackUncertainError";
+  }
+}
+
+export interface StartOwnershipPublicationDeps<TBound> {
+  acquireLease(): StartOwnershipLease;
+  bind(): Promise<TBound>;
+  writePid(bound: TBound): void;
+  writeRuntime(bound: TBound): void;
+  stopBound(bound: TBound): void | Promise<void>;
+  removeRuntime(): void;
+  removePid(): void;
+}
+
+/** Bind and publish PID/runtime ownership as one lease-protected transaction. */
+export async function bindAndPublishStartOwnership<TBound>(
+  deps: StartOwnershipPublicationDeps<TBound>,
+): Promise<TBound> {
+  const lease = deps.acquireLease();
+  let bound: TBound;
+  let releaseLease = true;
+  try {
+    try { bound = await deps.bind(); }
+    catch (error) {
+      if (error instanceof StartOwnershipRollbackUncertainError) releaseLease = false;
+      throw error;
+    }
+    try {
+      deps.writePid(bound);
+      deps.writeRuntime(bound);
+    } catch (error) {
+      const failures: unknown[] = [error];
+      let stopFailed = false;
+      try { await deps.stopBound(bound); }
+      catch (failure) { stopFailed = true; failures.push(failure); }
+      try { deps.removeRuntime(); } catch (failure) { failures.push(failure); }
+      try { deps.removePid(); } catch (failure) { failures.push(failure); }
+      if (stopFailed) {
+        releaseLease = false;
+        throw new StartOwnershipRollbackUncertainError(failures);
+      }
+      if (failures.length > 1) throw new AggregateError(failures, "start ownership publication rollback failed");
+      throw error;
+    }
+    return bound;
+  } finally {
+    if (releaseLease) lease.release();
+  }
+}
diff --git a/src/cli/status-probes.ts b/src/cli/status-probes.ts
index d3848c95366..d4196ba5cff 100644
--- a/src/cli/status-probes.ts
+++ b/src/cli/status-probes.ts
@@ -1,5 +1,5 @@
 import { readPidFileValue, readRuntimePort } from "../config/process-state";
-import { isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
+import { isConnectionRefused, isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
 import { isProcessAlive } from "../lib/process-control";
 
@@ -26,23 +26,7 @@ export function proxyHealthFailureReason(error: unknown, signal: AbortSignal): "
     : "unreachable";
 }
 
-/**
- * "Nothing is listening" is narrower than "the probe failed". `unreachable` covers every
- * non-abort failure, including a socket that was ACCEPTED and then reset — which is what
- * an in-flight start looks like mid-bind. Only a connect-phase refusal proves the port is
- * free, so this reads the underlying errno instead of the display string.
- */
-export function isConnectionRefused(error: unknown): boolean {
-  for (let current: unknown = error, depth = 0; current instanceof Error && depth < 4; depth++) {
-    const code = (current as { code?: unknown }).code;
-    if (code === "ECONNREFUSED" || code === "ConnectionRefused") return true;
-    // Bun surfaces the refusal as a plain message on some platforms; the errno name is
-    // still the discriminator, not a substring of arbitrary prose.
-    if (typeof code === "string" && code.endsWith("ECONNREFUSED")) return true;
-    current = (current as { cause?: unknown }).cause;
-  }
-  return false;
-}
+export { isConnectionRefused } from "../server/proxy-liveness";
 
 /**
  * A proxy killed by a native trap or SIGKILL never runs the exit cleanup that removes
diff --git a/src/cli/status.ts b/src/cli/status.ts
index b77f494082c..9079a2b5f90 100644
--- a/src/cli/status.ts
+++ b/src/cli/status.ts
@@ -1,4 +1,5 @@
 import { durableBunRuntime } from "../lib/bun-runtime";
+import { existsSync, readFileSync } from "node:fs";
 import { codexAutoStartEnabled, getConfigPath, readConfigDiagnostics } from "../config";
 import { getPidPath, readPid, readRuntimePort, type RuntimePortState } from "../config/process-state";
 import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor";
@@ -7,6 +8,8 @@ import type { OcxConfig } from "../types";
 import { diagnoseService, serviceLogPath } from "../service";
 import { collectStartupHealth, type StartupHealth } from "../codex/autostart-health";
 import { getCodexRoutingKind } from "../codex/inject";
+import { missingOwnedCatalogPath } from "../codex/inject/config-toml";
+import { CODEX_CONFIG_PATH } from "../codex/paths";
 import { diagnoseCodexShim } from "../codex/shim";
 import { displayCodexRuntimePath, effortClampAppliesToRuntime, liveRemovedEfforts, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime";
 import { packageVersion } from "./help";
@@ -502,6 +505,65 @@ export function unusedProxyWarningLines(input: {
   ];
 }
 
+/**
+ * The mirror case: routing is ours and nothing is answering it.
+ *
+ * #5261: this state does not merely fail model calls. The root `openai_base_url` we inject
+ * is the base URL of Codex's own built-in openai provider, so with the proxy down a user can
+ * be stopped at Codex sign-in with no mention of opencodex anywhere on the screen. The
+ * injection is on disk and survives reboot, so it does not clear itself.
+ *
+ * The rest of the not-running report offers only ways to bring the proxy BACK, which is the
+ * wrong half of the choice for someone who wants their editor working again now. `ocx restore`
+ * needs no proxy, no management API and no network, so name it here — this report is the
+ * surface such a user is most likely to reach before the config file itself.
+ *
+ * Restricted to routing opencodex owns. `custom-local` is somebody else's gateway, and
+ * `ocx restore` would not remove it.
+ */
+export function deadProxyRoutingAdviceLines(input: {
+  proxyUp: boolean;
+  routingKind: StartupHealth["routingKind"];
+}): string[] {
+  if (input.proxyUp || input.routingKind !== "opencodex-local") return [];
+  return [
+    "Codex is still pointed at this proxy, so sign-in and model requests both fail while it is down.",
+    "To hand Codex back to its own account and endpoints without starting anything: ocx restore",
+  ];
+}
+
+/**
+ * Read the live Codex config and report an opencodex catalog pointer whose file is gone.
+ *
+ * Unreadable or absent config is reported as no finding rather than as a problem: this is a
+ * diagnostic line, and inventing one from missing evidence is worse than staying quiet.
+ */
+export function detectMissingCodexCatalogPath(): string | null {
+  try {
+    if (!existsSync(CODEX_CONFIG_PATH)) return null;
+    return missingOwnedCatalogPath(readFileSync(CODEX_CONFIG_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The one state in this report where Codex is broken independently of the proxy (#5261).
+ *
+ * A `model_catalog_json` naming a file that is gone stops Codex loading its configuration at
+ * all, so it presents as the same blank wall as dead routing while having a different cause and
+ * a different fix. Both are named, because restarting the proxy rewrites the catalog and
+ * restoring removes the pointer, and which one the user wants is their choice, not ours.
+ */
+export function missingCodexCatalogLines(missingCatalogPath: string | null): string[] {
+  if (!missingCatalogPath) return [];
+  return [
+    "⚠️  Codex is pointed at a model catalog that is no longer on disk, so Codex cannot load its config:",
+    `   ${missingCatalogPath}`,
+    "   Regenerate it with 'ocx start', or remove opencodex from Codex with 'ocx restore'.",
+  ];
+}
+
 export async function collectStatus(): Promise<CliStatusView> {
   const configDiagnostics = readConfigDiagnostics();
   const config = configDiagnostics.config;
diff --git a/src/cli/stop-report.ts b/src/cli/stop-report.ts
new file mode 100644
index 00000000000..63d192f6f6c
--- /dev/null
+++ b/src/cli/stop-report.ts
@@ -0,0 +1,143 @@
+/**
+ * Structured summary for `ocx stop --json` (D4 of the app runtime ownership unit).
+ *
+ * The desktop shell drives the real `ocx stop` as a child process so the receipt-backed
+ * teardown, the drain, the Windows respawn verification and the client-config restore run
+ * exactly as they do from a terminal. This module makes that run's RESULT readable from
+ * outside: a StopRunRecord is threaded through the existing stop path in
+ * src/cli/index.ts (the same booleans that already decide the exit code), and
+ * summarizeStopRun turns it into one versioned JSON document.
+ *
+ * Nothing here re-decides anything. If a field of the record is wrong, the fix belongs
+ * in the stop path, not in the summarizer.
+ */
+import { STOP_HISTORY_DEFERRED_EXIT_CODE } from "../update/stop-contract.mjs";
+
+/** Wire version of the stop summary document. */
+export const STOP_SUMMARY_SCHEMA = "ocx-stop/1";
+
+export type StopServiceOutcome =
+  | "absent"
+  | "stopped"
+  | "stopped-respawnable"
+  | "failed"
+  | "state-unknown"
+  | "error";
+
+export type StopProxyOutcome =
+  | "stopped"
+  | "stopped-orphan"
+  | "not-running"
+  | "stop-failed"
+  | "ownership-refused"
+  | "unresolvable-pid"
+  | "respawned"
+  | "unknown";
+
+export type StopSharedTeardownOutcome =
+  | "restored"
+  | "performed-by-proxy"
+  | "refused"
+  | "failed"
+  | "skipped";
+
+/** Facts recorded where the stop path already decides them. */
+export interface StopRunRecord {
+  /** What stopServiceIfInstalledDetailed returned, or "error" when it threw. */
+  service: StopServiceOutcome;
+  /** Which proxy path ran and how it ended. */
+  proxy: StopProxyOutcome;
+  /** Who ended up restoring shared client config (native Codex + Grok). */
+  sharedTeardown: StopSharedTeardownOutcome;
+  /** An inherited pending-teardown receipt blocked the restore. */
+  inheritedTeardownBlocks: boolean;
+  /** A discharged receipt could not be removed from disk. */
+  receiptClearFailed: boolean;
+}
+
+/** The internal booleans that already pick the process exit code. */
+export interface StopRunSignals {
+  failed: boolean;
+  historyOnly: boolean;
+  historyDeferred: boolean;
+  exitCode: number;
+}
+
+export interface StopSummaryJson {
+  schema: typeof STOP_SUMMARY_SCHEMA;
+  /** Strict exit-code view: true only for exit 0. */
+  ok: boolean;
+  outcome: "stopped" | "not-running" | "history-incomplete" | "history-deferred" | "failed";
+  exitCode: number;
+  /** True when this stop left no proxy of this home running by its own paths. */
+  runtimeDown: boolean;
+  service: StopServiceOutcome;
+  proxy: StopProxyOutcome;
+  sharedTeardown: StopSharedTeardownOutcome;
+  /** One stable human-readable line for a caller's UI. */
+  message: string;
+}
+
+/** What handleStop returns: the pre-existing boolean plus the structured twin. */
+export interface StopOutcome {
+  /**
+   * The exact boolean the stop path returned before summaries existed (!stopFailed).
+   * It is NOT the same as summary.ok: 79/80 stops return true here, because the
+   * downtime warning that keys on it applies whenever the runtime went down.
+   */
+  ok: boolean;
+  summary: StopSummaryJson;
+}
+
+function stopOutcome(record: StopRunRecord, signals: StopRunSignals): StopSummaryJson["outcome"] {
+  if (signals.failed) return "failed";
+  if (signals.historyOnly) return "history-incomplete";
+  if (signals.historyDeferred) {
+    // The deferred exit code is a proven claim; anything else means another obligation
+    // was sitting in the home, which the exit-code logic already reports as failure.
+    return signals.exitCode === STOP_HISTORY_DEFERRED_EXIT_CODE ? "history-deferred" : "failed";
+  }
+  if (record.proxy === "not-running") return "not-running";
+  if (record.proxy === "stopped" || record.proxy === "stopped-orphan") return "stopped";
+  return "failed";
+}
+
+function stopMessage(record: StopRunRecord, signals: StopRunSignals, outcome: StopSummaryJson["outcome"]): string {
+  if (record.proxy === "respawned") return "The proxy was respawned after the stop; it is still running.";
+  if (record.proxy === "ownership-refused") return "The proxy refused the stop; it belongs to a different opencodex home.";
+  if (record.proxy === "unresolvable-pid") return "A proxy is answering, but its process id could not be resolved, so it was not stopped.";
+  if (record.proxy === "stop-failed") return "The proxy process could not be stopped.";
+  if (record.service === "failed") return "The installed service manager did not stop and may respawn the proxy.";
+  if (record.service === "state-unknown") return "The service manager state could not be read.";
+  if (record.service === "error") return "Stopping the installed service failed.";
+  if (record.inheritedTeardownBlocks) return "An earlier stop left an outstanding shared teardown that could not be confirmed.";
+  if (record.sharedTeardown === "failed") return "The shared teardown failed; client configuration may still point at the stopped proxy.";
+  if (record.receiptClearFailed) return "The shared teardown finished, but its receipt could not be removed.";
+  if (record.sharedTeardown === "refused") return "The shared teardown was refused before it changed anything; it is still owed.";
+  if (signals.historyOnly) return "The proxy stopped; Codex history cleanup did not complete.";
+  if (outcome === "history-deferred") return "The proxy stopped; the shared teardown was deferred and is still owed.";
+  if (outcome === "not-running") return "No proxy was running.";
+  if (outcome === "stopped") return "The proxy stopped.";
+  return "The stop failed.";
+}
+
+/** Pure mapper from the recorded run to the wire document. */
+export function summarizeStopRun(record: StopRunRecord, signals: StopRunSignals): StopSummaryJson {
+  const outcome = stopOutcome(record, signals);
+  return {
+    schema: STOP_SUMMARY_SCHEMA,
+    ok: signals.exitCode === 0,
+    outcome,
+    exitCode: signals.exitCode,
+    runtimeDown: record.proxy === "stopped" || record.proxy === "stopped-orphan" || record.proxy === "not-running",
+    service: record.service,
+    proxy: record.proxy,
+    sharedTeardown: record.sharedTeardown,
+    message: stopMessage(record, signals, outcome),
+  };
+}
+
+/** Emit the summary as exactly one JSON document on stdout. */
+export function printStopSummary(summary: StopSummaryJson, stdout: { log: (s: string) => void } = console): void {
+  stdout.log(JSON.stringify(summary));
+}
diff --git a/src/cli/uninstall-plan.ts b/src/cli/uninstall-plan.ts
index 0e1df1cd2df..4bfb9d4a7a6 100644
--- a/src/cli/uninstall-plan.ts
+++ b/src/cli/uninstall-plan.ts
@@ -84,3 +84,12 @@ export function everyEndpointProvenDown(
   if (endpoints.length === 0) return false;
   return endpoints.every(e => probe(e) === "dead");
 }
+
+export async function everyEndpointProvenDownAsync(
+  endpoints: readonly ProbeEndpoint[],
+  probe: (e: ProbeEndpoint) => Promise<"live" | "dead" | "unknown"> | "live" | "dead" | "unknown",
+): Promise<boolean> {
+  if (endpoints.length === 0) return false;
+  const results = await Promise.all(endpoints.map(e => probe(e)));
+  return results.every(result => result === "dead");
+}
diff --git a/src/client/machine-listener.ts b/src/client/machine-listener.ts
index f0dd56b7656..ef8c4f43fae 100644
--- a/src/client/machine-listener.ts
+++ b/src/client/machine-listener.ts
@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 import type { Server } from "bun";
 import { loadConfig } from "../config";
 import { browserSecurityHeaders } from "../server/auth-cors";
@@ -16,11 +15,9 @@ import { readClientConnectionState } from "./state";
 import { handleMachineApi, type HubReachability, type MachineApiDeps } from "./machine-api";
 import { MACHINE_GUI_ORIGIN_HEADER, requireMachineAuth } from "./machine-auth";
 import { relayHubManagementRequest } from "./hub-relay";
+import { packageVersion } from "../lib/package-version";
 
-const VERSION = (() => {
-  try { return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version as string; }
-  catch { return "0.0.0"; }
-})();
+const VERSION = packageVersion("0.0.0");
 const GUI_SPA_PATHS = new Set([
   "/dashboard", "/startup", "/providers", "/models", "/subagents",
   "/logs", "/usage", "/storage", "/codex-set", "/integrations",
diff --git a/src/clients/aside-profiles.ts b/src/clients/aside-profiles.ts
index 770857611af..612e281ff0a 100644
--- a/src/clients/aside-profiles.ts
+++ b/src/clients/aside-profiles.ts
@@ -201,6 +201,7 @@ export function guardAsideProfileIO(profile: AsideProfile, io: IntegrationIO, pr
   const selected = { ...profile };
   const registered = registeredProfiles(selected, profiles).map(peer => ({ ...peer }));
   const captured = boundary(selected, registered, false);
+  const lstatProbe = io.lstatKind;
   function check(path: string, directory: boolean, mutation: boolean): void {
     if (path !== (directory ? selected.detectDir : selected.configPath)) {
       refuse("IO attempted to access a different account path.");
@@ -214,6 +215,9 @@ export function guardAsideProfileIO(profile: AsideProfile, io: IntegrationIO, pr
   return {
     readText: path => { check(path, false, false); return io.readText(path); },
     statKind: path => { check(path, path === selected.detectDir, false); return io.statKind(path); },
+    ...(lstatProbe
+      ? { lstatKind: (path: string) => { check(path, path === selected.detectDir, false); return lstatProbe(path); } }
+      : {}),
     writeText: (path, text) => { check(path, false, true); io.writeText(path, text); },
     removeFile: path => { check(path, false, true); io.removeFile(path); },
     mkdirp: path => { check(path, true, true); io.mkdirp(path); },
diff --git a/src/clients/config-export.ts b/src/clients/config-export.ts
index 13dc2c2964a..90fe5030563 100644
--- a/src/clients/config-export.ts
+++ b/src/clients/config-export.ts
@@ -35,6 +35,18 @@ export { OPENCODE_PROVIDER_ID, OPENCODE_CONFIG_SCHEMA, OPENCODE_API_KEY_ENV, OPE
 export { normalizeExportModels } from "./config-export/model-metadata";
 export type { OmpModelEntry, OmpProviderBlock, OmpGeneratedConfig } from "./config-export/omp";
 export type { ZcodeModelEntry, ZcodeProviderBlock, ZcodeGeneratedConfig } from "./config-export/zcode";
+export type { ZcodeStoreProviderRule, ZcodeStoreModelRule } from "./config-export/zcode-store";
+export {
+  ZCODE_STORE_SCHEMA_VERSION,
+  ZCODE_STORE_PROVIDER_GROUP,
+  ZCODE_STORE_API_TYPE,
+  ZCODE_STORE_PROVIDER_NAME,
+  ZCODE_STORE_PROVIDER_RULES_PATH,
+  ZCODE_STORE_MODEL_RULES_PATH,
+  buildZcodeStoreProviderRule,
+  buildZcodeStoreContribution,
+  zcodeStoreSchemaEstablished,
+} from "./config-export/zcode-store";
 export type { DshReasoningEffort, DshWireReasoningEffort, DshModelEntry, DshProviderBlock, DshGeneratedConfig } from "./config-export/dsh";
 export type { McodeProviderBlock, McodeModelEntry, McodeGeneratedConfig } from "./config-export/mcode";
 export type { RaycastAbility, RaycastAbilityName, RaycastModelEntry, RaycastProviderEntry, RaycastGeneratedConfig } from "./config-export/raycast";
@@ -447,6 +459,30 @@ export function zcodeConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(zcodeHomeDir(env, home), "v2", "config.json");
 }
 
+/**
+ * The provider store a current ZCode reads, which is NOT the file above.
+ *
+ * ZCode 3.14 moved custom providers to `v2/provider_config.json` and left
+ * `v2/config.json` reachable only through a one-shot import that runs when the
+ * new file is missing. The client creates the new file on first launch, so on
+ * an install that has ever run, the import has already happened and never runs
+ * again — every later write to `v2/config.json` is read by nobody (#5348).
+ *
+ * This project does not write this file; it names it so the integration can
+ * tell whether its own write can still reach the client. The env override is
+ * ZCode's own (`ZCODE_PERSONAL_PROVIDER_CONFIG_FILE`), so an operator who
+ * relocated the store is measured against the file their client actually opens
+ * rather than the default location. A relative override is refused for the same
+ * reason `ZCODE_DATA_DIR` refuses one: we and the client would disagree about
+ * which file it names, and here that disagreement decides whether an apply is
+ * reported as effective.
+ */
+export function zcodeProviderStorePath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const override = env.ZCODE_PERSONAL_PROVIDER_CONFIG_FILE?.trim();
+  if (override) return absoluteClientPath(override, home, "ZCODE_PERSONAL_PROVIDER_CONFIG_FILE");
+  return join(zcodeHomeDir(env, home), "v2", "provider_config.json");
+}
+
 /**
  * Prime Agent resolves its agent directory from `PRIME_AGENT_CODING_AGENT_DIR`
  * — the brand-derived spelling of the `PI_CODING_AGENT_DIR` that `ompAgentDir`
diff --git a/src/clients/config-export/zcode-store.ts b/src/clients/config-export/zcode-store.ts
new file mode 100644
index 00000000000..5ba585e0193
--- /dev/null
+++ b/src/clients/config-export/zcode-store.ts
@@ -0,0 +1,157 @@
+// ZCode personal provider store export.
+import type { ExportContext, ManagedContribution, ManagedFragment } from "./contracts";
+import { authoritativeContextWindow, inputModalitiesForClient, normalizeExportModels } from "./model-metadata";
+import { OPENCODE_PROVIDER_ID, LOOPBACK_API_KEY_PLACEHOLDER } from "./constants";
+import { formatSelectorConjunction } from "../../integrations/merge";
+
+/**
+ * The file ZCode 3.14 and later actually read their custom providers from.
+ *
+ * `v2/config.json` — the file {@link buildZcodeContribution} writes — is still
+ * parsed by this client, but only by a one-shot `importLegacy` hook that runs
+ * when this store is missing. The client creates the store on first launch, so
+ * on any install that has ever run the import is already spent and a later
+ * write to the old file is read by nobody (#5348).
+ *
+ * The shape below is the client's own, quoted from the report that opened
+ * #5348: it is what the client's `importLegacyPersonalProviderConfig` produced
+ * when it migrated this project's block, so it is observed output rather than a
+ * schema this project invented. Everything the client persists that we have not
+ * seen it derive from our block is deliberately absent — an omitted field is a
+ * field the client still owns.
+ */
+export const ZCODE_STORE_SCHEMA_VERSION = 1;
+
+/**
+ * `group` places the provider among the user's own personal providers rather
+ * than the builtin list the client ships and rewrites. `api.type` is the same
+ * choice `kind: "openai"` makes in the legacy block: the OpenAI Responses
+ * protocol, which is the only surface this proxy speaks natively.
+ */
+export const ZCODE_STORE_PROVIDER_GROUP = "standard-personal";
+export const ZCODE_STORE_API_TYPE = "openai-responses";
+export const ZCODE_STORE_PROVIDER_NAME = "OpenCodex";
+
+/** Where the store keeps one rule per provider, and one per (provider, model). */
+export const ZCODE_STORE_PROVIDER_RULES_PATH = ["config", "providerConfigRules", "providerRules"] as const;
+export const ZCODE_STORE_MODEL_RULES_PATH = ["config", "modelConfigRules", "providerModelRules"] as const;
+
+export interface ZcodeStoreProviderRule {
+  providerId: string;
+  enabled: true;
+  providerName: string;
+  config: {
+    group: string;
+    access: { apiKey: string };
+    api: { type: string; baseUrl: string };
+    personalModelIds: string[];
+    modelOrder: string[];
+  };
+}
+
+export interface ZcodeStoreModelRule {
+  providerId: string;
+  modelId: string;
+  config: { properties: { contextWindow: number } };
+}
+
+/**
+ * Is this document a store whose schema we can write?
+ *
+ * Only the one version whose shape has been observed. A store carrying any
+ * other `schemaVersion` — or none, or a document that is not an object — is a
+ * file we cannot merge into without asserting a nesting we have never seen,
+ * and a wrong assertion there does not fail loudly: it replaces the provider
+ * list the user keeps in the same file. The integration reports the write as
+ * ineffective in that case instead of guessing.
+ */
+export function zcodeStoreSchemaEstablished(parsed: unknown): boolean {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
+  return (parsed as Record<string, unknown>).schemaVersion === ZCODE_STORE_SCHEMA_VERSION;
+}
+
+/**
+ * The selector addressing one model rule, or null when the id cannot be spelled.
+ *
+ * A rule is identified by the PAIR, so both fields are named: a selector
+ * carrying only the model would match another provider's rule for the same
+ * model. The conjunction grammar reserves `,` and `]`, and a model id holding
+ * either cannot be addressed unambiguously — that row ships without its
+ * context window rather than with a selector that points somewhere else.
+ */
+function modelRuleSelector(modelId: string): string | null {
+  return formatSelectorConjunction([
+    { field: "providerId", value: OPENCODE_PROVIDER_ID },
+    { field: "modelId", value: modelId },
+  ]);
+}
+
+/** The rows this export publishes, filtered exactly as the legacy block filters them. */
+function storeModels(ctx: ExportContext): string[] {
+  const ids: string[] = [];
+  for (const model of normalizeExportModels(ctx.models)) {
+    if (inputModalitiesForClient("pi", model.inputModalities) === null) continue;
+    ids.push(model.namespaced);
+  }
+  return ids;
+}
+
+/**
+ * The provider rule the client reads, built from the same context the legacy
+ * block is built from.
+ *
+ * `baseUrl` carries the `/v1` root for the same reason the legacy block does:
+ * this client appends `/responses` for the Responses protocol, so requests land
+ * on `/v1/responses`. The serialized credential is always the non-secret
+ * loopback placeholder.
+ */
+export function buildZcodeStoreProviderRule(ctx: ExportContext): ZcodeStoreProviderRule {
+  const ids = storeModels(ctx);
+  return {
+    providerId: OPENCODE_PROVIDER_ID,
+    enabled: true,
+    providerName: ZCODE_STORE_PROVIDER_NAME,
+    config: {
+      group: ZCODE_STORE_PROVIDER_GROUP,
+      access: { apiKey: LOOPBACK_API_KEY_PLACEHOLDER },
+      api: { type: ZCODE_STORE_API_TYPE, baseUrl: `${ctx.baseUrl.replace(/\/v1\/?$/, "")}/v1` },
+      personalModelIds: ids,
+      /*
+       * The client persists the picker order separately from membership. Ours is
+       * the catalog order the rest of this export already sorts by, so a refresh
+       * that adds a model puts it where every other surface puts it.
+       */
+      modelOrder: [...ids],
+    },
+  };
+}
+
+/**
+ * Everything this project owns inside the store: one provider rule, plus one
+ * model rule per row that has an authoritative context window.
+ *
+ * A row without one ships no model rule at all, which is the same
+ * authoritative-window rule the legacy block follows — an emitted stand-in
+ * would be a guessed capability. Reasoning ladders have no counterpart here
+ * that this project has observed the client produce, so none is written.
+ */
+export function buildZcodeStoreContribution(ctx: ExportContext): ManagedContribution {
+  const fragments: ManagedFragment[] = [{
+    path: [...ZCODE_STORE_PROVIDER_RULES_PATH, `[providerId=${OPENCODE_PROVIDER_ID}]`],
+    value: buildZcodeStoreProviderRule(ctx),
+  }];
+  for (const model of normalizeExportModels(ctx.models)) {
+    if (inputModalitiesForClient("pi", model.inputModalities) === null) continue;
+    const contextWindow = authoritativeContextWindow(model.contextWindow);
+    if (contextWindow === undefined) continue;
+    const selector = modelRuleSelector(model.namespaced);
+    if (selector === null) continue;
+    const rule: ZcodeStoreModelRule = {
+      providerId: OPENCODE_PROVIDER_ID,
+      modelId: model.namespaced,
+      config: { properties: { contextWindow } },
+    };
+    fragments.push({ path: [...ZCODE_STORE_MODEL_RULES_PATH, selector], value: rule });
+  }
+  return { clientId: "zcode", fragments };
+}
diff --git a/src/codex/app-server-processes.ts b/src/codex/app-server-processes.ts
index 355beaa9e50..a33a1091fd6 100644
--- a/src/codex/app-server-processes.ts
+++ b/src/codex/app-server-processes.ts
@@ -786,6 +786,58 @@ function catalogStatusFromProcesses(
   return { state: stale ? "stale" : "fresh", processes: withStarts, catalogMtimeMs };
 }
 
+interface ComputedCodexAppServerCatalogStatus {
+  status: CodexAppServerCatalogStatus;
+  processes: CodexAppServerProcess[];
+}
+
+/**
+ * Compute one catalog-state observation while retaining the command lines from the
+ * same process enumeration. The public collector deliberately exposes only the
+ * identity and timestamp projection; post-write warning code also needs the matched
+ * process records, and re-enumerating there creates a race between classification and
+ * reporting (as well as a second expensive Windows CIM walk).
+ */
+function computeCodexAppServerCatalogStatus(
+  io: CodexAppServerProcessIo,
+): ComputedCodexAppServerCatalogStatus {
+  const platform = io.platform ?? process.platform;
+  const getuid = io.getuid ?? (() => {
+    try {
+      return typeof process.getuid === "function" ? process.getuid() : undefined;
+    } catch {
+      return undefined;
+    }
+  });
+  let snapshots: ProcessSnapshot[];
+  let enumerationFailed = false;
+  const enumerate = io.listSnapshots ?? (() => defaultListSnapshots(platform, getuid));
+  try {
+    snapshots = enumerate();
+  } catch {
+    // A failed process read is unknown, never proof that nothing is running.
+    snapshots = [];
+    enumerationFailed = true;
+  }
+  const processes = codexAppServerProcessesFromSnapshots(snapshots);
+  if (processes.length === 0) {
+    return {
+      processes,
+      status: enumerationFailed
+        ? { state: "unknown", processes: [], catalogMtimeMs: null }
+        : { state: "not_running", processes: [], catalogMtimeMs: null },
+    };
+  }
+  const catalogMtimeMs = (io.catalogMtimeMs ?? defaultCatalogMtimeMs)();
+  const starts = io.readStartMs
+    ? new Map(processes.map(proc => [proc.pid, io.readStartMs!(proc.pid)] as const))
+    : readProcessStartMsBatch(processes.map(proc => proc.pid), platform);
+  return {
+    processes,
+    status: catalogStatusFromProcesses(processes, catalogMtimeMs, starts),
+  };
+}
+
 // Short TTL: process listing + stat run once per window even under per-turn
 // guidance calls (#857).
 let catalogStateCache: { atMs: number; status: CodexAppServerCatalogStatus } | null = null;
@@ -889,41 +941,7 @@ export function collectCodexAppServerCatalogState(
     && now - catalogStateCache.atMs < catalogStateTtlMs(catalogStateCache.status.state)) {
     return catalogStateCache.status;
   }
-  const compute = (): CodexAppServerCatalogStatus => {
-    const platform = io.platform ?? process.platform;
-    const getuid = io.getuid ?? (() => {
-      try {
-        return typeof process.getuid === "function" ? process.getuid() : undefined;
-      } catch {
-        return undefined;
-      }
-    });
-    let snapshots: ProcessSnapshot[];
-    let enumerationFailed = false;
-    const enumerate = io.listSnapshots ?? (() => defaultListSnapshots(platform, getuid));
-    try {
-      snapshots = enumerate();
-    } catch {
-      // Enumeration failure must never read as "nothing running" — that would let
-      // positive model guidance through on guesswork (#857). The injected seam gets
-      // the same contract as the default path: whoever enumerates, a failure to read
-      // the process list is unknown, not an empty machine.
-      snapshots = [];
-      enumerationFailed = true;
-    }
-    const processes = codexAppServerProcessesFromSnapshots(snapshots);
-    if (processes.length === 0) {
-      return enumerationFailed
-        ? { state: "unknown", processes: [], catalogMtimeMs: null }
-        : { state: "not_running", processes: [], catalogMtimeMs: null };
-    }
-    const catalogMtimeMs = (io.catalogMtimeMs ?? defaultCatalogMtimeMs)();
-    const starts = io.readStartMs
-      ? new Map(processes.map(proc => [proc.pid, io.readStartMs!(proc.pid)] as const))
-      : readProcessStartMsBatch(processes.map(proc => proc.pid), platform);
-    return catalogStatusFromProcesses(processes, catalogMtimeMs, starts);
-  };
-  const status = compute();
+  const status = computeCodexAppServerCatalogStatus(io).status;
   if (fullyDefault) {
     catalogStateCache = { atMs: now, status };
   }
@@ -1228,16 +1246,30 @@ export function afterCatalogWriteHandleAppServers(
   options: AfterCatalogWriteAppServerOptions,
 ): AfterCatalogWriteAppServerResult {
   const excluded = new Set(options.excludePids ?? []);
+  const hint = STALE_CODEX_APP_SERVER_HINT;
+  if (!options.restart) {
+    // A running process is not necessarily stale. Classify the exact process
+    // enumeration that supplies the warning, and stay quiet when freshness cannot be
+    // established rather than presenting an unknown observation as a known mismatch.
+    const observed = computeCodexAppServerCatalogStatus(options.io ?? {});
+    const starts = new Map(observed.status.processes.map(process => [process.pid, process.startedAtMs]));
+    const catalogMtimeMs = observed.status.catalogMtimeMs;
+    const processes = observed.processes.filter(process => !excluded.has(process.pid));
+    const staleProcesses = catalogMtimeMs === null
+      ? []
+      : processes.filter(process => {
+        const startedAtMs = starts.get(process.pid);
+        return startedAtMs !== null && startedAtMs !== undefined && startedAtMs <= catalogMtimeMs;
+      });
+    if (staleProcesses.length === 0) return { processes, warned: false, hint };
+    options.log?.error(formatStaleCodexAppServerWarning(staleProcesses));
+    return { processes: staleProcesses, warned: true, hint };
+  }
   const processes = listCodexAppServerProcesses(options.io)
     .filter(process => !excluded.has(process.pid));
-  const hint = STALE_CODEX_APP_SERVER_HINT;
   if (processes.length === 0) {
     return { processes, warned: false, hint };
   }
-  if (!options.restart) {
-    options.log?.error(formatStaleCodexAppServerWarning(processes));
-    return { processes, warned: true, hint };
-  }
   options.log?.log(
     `Stopping Codex app-server process(es): ${processes.map(process => process.pid).join(", ")} `
     + "(active turns may be interrupted).",
diff --git a/src/codex/auth-api/login-flow.ts b/src/codex/auth-api/login-flow.ts
index fa6d1c6fbf7..3a9111e2a4d 100644
--- a/src/codex/auth-api/login-flow.ts
+++ b/src/codex/auth-api/login-flow.ts
@@ -226,9 +226,12 @@ export async function handleCodexAuthLoginStart(req: Request, config: OcxConfig,
     // machine. Opening it on the hub host is useless at best, and on a
     // headless host it fails. `deviceCode` is the same signal the generic
     // OAuth login route uses to make this decision.
+    // Reported to the caller rather than discarded (#5261): a login whose browser never opened
+    // is indistinguishable from one that did, so it reads as success while nothing happens.
+    let browserLaunch: "started" | "failed" | "skipped" = "skipped";
     if (result.url && !result.deviceCode && shouldOpenBrowserForLogin(body.openBrowser, runtimeConfig)) {
       const { openUrl } = await import("../../lib/open-url");
-      openUrl(result.url);
+      browserLaunch = (await openUrl(result.url)).status === "started" ? "started" : "failed";
     }
 
     (async () => {
@@ -488,6 +491,8 @@ export async function handleCodexAuthLoginStart(req: Request, config: OcxConfig,
       flowId,
       url: result.url,
       instructions: result.instructions,
+      // Never fatal: the URL is still a valid thing to open by hand, and the flow stays live.
+      browserLaunch,
       // Dropped before #3366: every device-code surface renders this field,
       // so withholding it left the GUI and CLI with no code to show.
       ...(result.deviceCode ? { deviceCode: result.deviceCode } : {}),
diff --git a/src/codex/autostart-health.ts b/src/codex/autostart-health.ts
index 5fc990a5f6c..83b330ca3db 100644
--- a/src/codex/autostart-health.ts
+++ b/src/codex/autostart-health.ts
@@ -154,6 +154,34 @@ export function startupHealthSummary(health: StartupHealth): string {
   return action ? `${summary}; ${action}` : summary;
 }
 
+/**
+ * What to say at the end of setup, once routing is on disk and the autostart choice is made.
+ *
+ * #5261: applying the Codex integration does not install a background service, and on Windows
+ * the scheduled task that a separate install would create is logon-triggered rather than
+ * boot-triggered. So "routing written, nothing listening" is an ordinary state after a restart
+ * rather than a corruption — and the user is never told, because setup ends on a success line.
+ *
+ * A boot trigger is not the missing piece and would be a false reassurance. The task runs as
+ * the interactive user, so before logon there is no session for it to run in; making it truly
+ * pre-logon means a different principal and a different service backend, not another trigger.
+ * What is actually missing is that nobody says the dependency exists, which is cheap to fix and
+ * true on every platform.
+ *
+ * Reuses the existing health model rather than re-deriving the condition, so this cannot drift
+ * from what `ocx status` and `ocx doctor` report about the same install.
+ */
+export function injectedRoutingRestartWarningLines(health: StartupHealth): string[] {
+  if (health.status !== "at-risk") return [];
+  return [
+    // Deliberately not "nothing will restart the proxy": a healthy launcher shim does restart it,
+    // for CLI launches only, and is still at-risk. The summary line below says which case this is.
+    "⚠️  Codex routing is written to disk and survives a restart; keeping the proxy running is a separate matter.",
+    `   ${startupHealthSummary(health)}`,
+    "   While the proxy is down Codex cannot sign in or reach a model. 'ocx restore' undoes the routing without needing it.",
+  ];
+}
+
 function classifyStartupHealthSummary(health: StartupHealth): string {
   if (health.status === "native") return health.routingKind === "custom-remote"
     ? "custom remote Codex routing (no local restart dependency)"
diff --git a/src/codex/catalog/build-entries.ts b/src/codex/catalog/build-entries.ts
index c9ca8e1ec7b..0593a3fee03 100644
--- a/src/codex/catalog/build-entries.ts
+++ b/src/codex/catalog/build-entries.ts
@@ -1,4 +1,4 @@
-import { CODEX_REASONING_LEVELS } from "../../reasoning-effort";
+import { CODEX_REASONING_LEVELS, type CodexReasoningLevel } from "../../reasoning-effort";
 import { clearModelCache } from "../model-cache";
 import { routedSlug, slugEquivalenceKey } from "../../providers/slug-codec";
 import { COMBO_NAMESPACE } from "../../combos";
@@ -872,7 +872,7 @@ export function mergeCatalogEntriesFromObservedState({
     // (luna: no ultra) stay intact.
     if (!freshCustomEntries.has(m) && !exactCombo && !reserveProjection && !String(e.slug ?? "").startsWith("opencode-go/")) {
       const levels = Array.isArray(e.supported_reasoning_levels)
-        ? e.supported_reasoning_levels as Array<{ effort?: string }>
+        ? e.supported_reasoning_levels as Array<Partial<CodexReasoningLevel>>
         : [];
       if (levels.length > 0
         && !suppressedSyntheticMaxSlugs.has(String(e.slug ?? ""))
diff --git a/src/codex/catalog/effort.ts b/src/codex/catalog/effort.ts
index 4206983183b..96f8c0270e5 100644
--- a/src/codex/catalog/effort.ts
+++ b/src/codex/catalog/effort.ts
@@ -8,7 +8,7 @@ import { clearModelCache, DEFAULT_MODEL_CACHE_TTL_MS, getFreshCached, getStaleCa
 import { buildModelsRequest, resolveModelsAuthToken } from "../../oauth";
 import type { OcxConfig, OcxProviderConfig } from "../../types";
 import { modelInList } from "../../types";
-import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
+import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts, type CodexReasoningLevel } from "../../reasoning-effort";
 import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
 import { getProviderRegistryEntry } from "../../providers/registry";
@@ -286,7 +286,7 @@ export function isGpt56NativeSlug(slug: string): boolean {
 
 export function ensureGpt56ReasoningLevels(entry: RawEntry): void {
   const levels = Array.isArray(entry.supported_reasoning_levels)
-    ? entry.supported_reasoning_levels as Array<{ effort?: string }>
+    ? entry.supported_reasoning_levels as Array<Partial<CodexReasoningLevel>>
     : [];
   const out = [...levels];
   // max is a real native rung on the 5.6 family — always restored; ultra always advertised.
@@ -300,7 +300,7 @@ export function ensureGpt56ReasoningLevels(entry: RawEntry): void {
 
 export function ensureUltraReasoningLevel(entry: RawEntry): void {
   const levels = Array.isArray(entry.supported_reasoning_levels)
-    ? entry.supported_reasoning_levels as Array<{ effort?: string }>
+    ? entry.supported_reasoning_levels as Array<Partial<CodexReasoningLevel>>
     : [];
   if (levels.length === 0) return;
   const wanted = ["max", "ultra"];
diff --git a/src/codex/catalog/provider-models.ts b/src/codex/catalog/provider-models.ts
index d2641eba78d..3ff7f9abe5b 100644
--- a/src/codex/catalog/provider-models.ts
+++ b/src/codex/catalog/provider-models.ts
@@ -52,7 +52,7 @@ import { routedSlug, slugEquals, slugEquivalenceKey, slugsEquivalent } from "../
 import { CODEX_GPT5_IDENTITY_LINE } from "../../adapters/identity";
 import { filterCursorConfiguredModelsByLiveDiscovery } from "../../adapters/cursor/discovery";
 import { fetchCursorUsableModels } from "../../adapters/cursor/live-models";
-import { recordLiveCursorClaudeModels, recordLiveCursorMaxModeModels } from "../../adapters/cursor/catalog";
+import { cursorLiveRosterScope, recordLiveCursorClaudeModels, recordLiveCursorMaxModeModels } from "../../adapters/cursor/catalog";
 import { fetchQoderModels } from "../../adapters/qoder/live-models";
 import { resolveQoderProfile } from "../../adapters/qoder/profiles";
 import { fetchDevinUsableModels } from "../../adapters/devin/live-models";
@@ -289,15 +289,19 @@ export async function fetchProviderModelsWithAuth(
   }
   if (prov.adapter === "devin") {
     if (!apiKey) return observed(configured, "degraded");
-    const cachedDevin = getFreshCached(name, ttlMs);
+    // Devin's usable-model list is entitlement-specific. Bind cache reads/writes to an
+    // irreversible credential fingerprint so a credential switch cannot observe another
+    // account's roster or stale fallback (the Qoder precedent above).
+    const authorityIdentity = createHash("sha256").update(apiKey).digest("hex");
+    const cachedDevin = getFreshCached(name, ttlMs, Date.now(), authorityIdentity);
     if (cachedDevin) {
       return observed(
         withConfiguredRetention(applyConfigHintsToCachedModels(name, prov, cachedDevin)),
         "authoritative",
       );
     }
-    if (isModelsFetchCoolingDown(name)) {
-      const cooling = getStaleCached(name);
+    if (isModelsFetchCoolingDown(name, undefined, undefined, authorityIdentity)) {
+      const cooling = getStaleCached(name, authorityIdentity);
       return observed(
         withConfiguredRetention(
           cooling ? applyConfigHintsToCachedModels(name, prov, cooling) : configured,
@@ -339,17 +343,17 @@ export async function fetchProviderModelsWithAuth(
         } as CatalogModel;
       });
       const forCache = withConfiguredRetention(result, { retainComboTargets: false });
-      if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
+      if (!setCached(name, forCache, Date.now(), cacheGeneration, authorityIdentity)) {
         return observed(withConfiguredRetention(configured), "degraded");
       }
       markProviderDiscoveryOk(name, liveResult.models.length);
       return observed(withConfiguredRetention(forCache), "authoritative");
     }
     if (isCurrentCacheGeneration()) {
-      markModelsFetchFailure(name);
+      markModelsFetchFailure(name, undefined, authorityIdentity);
       markProviderDiscoveryFailed(name, { reason: liveResult.error === "auth" ? "provider" : "invalid_response" });
     }
-    const stale = getStaleCached(name);
+    const stale = getStaleCached(name, authorityIdentity);
     return observed(
       withConfiguredRetention(stale ? applyConfigHintsToCachedModels(name, prov, stale) : configured),
       "degraded",
@@ -361,15 +365,19 @@ export async function fetchProviderModelsWithAuth(
     // variants this PLAN can use. Keep the base-model UX (the request builder appends the effort
     // suffix) but filter the static seed to the bases the account actually has — so models not on the
     // plan (e.g. claude-fable-5) drop out instead of failing ERROR_BAD_MODEL_NAME. Fall back to the seed.
-    const cachedCursor = getFreshCached(name, ttlMs);
+    // The roster is entitlement-specific, so the cache entry is bound to an irreversible
+    // credential fingerprint: a credential switch must not observe the previous account's
+    // plan roster, its stale fallback, or its failure cooldown suppression.
+    const authorityIdentity = createHash("sha256").update(apiKey).digest("hex");
+    const cachedCursor = getFreshCached(name, ttlMs, Date.now(), authorityIdentity);
     if (cachedCursor) {
       return observed(
         withConfiguredRetention(applyConfigHintsToCachedModels(name, prov, cachedCursor, undefined, metadataModelIdCaseFold, captured.effectiveAlias)),
         "authoritative",
       );
     }
-    if (isModelsFetchCoolingDown(name)) {
-      const cooling = getStaleCached(name);
+    if (isModelsFetchCoolingDown(name, undefined, undefined, authorityIdentity)) {
+      const cooling = getStaleCached(name, authorityIdentity);
       return observed(
         withConfiguredRetention(
           cooling ? applyConfigHintsToCachedModels(name, prov, cooling, undefined, metadataModelIdCaseFold, captured.effectiveAlias) : configured,
@@ -394,27 +402,28 @@ export async function fetchProviderModelsWithAuth(
       // Cache the discovery-filtered roster without combo retention so a later
       // gather can re-apply the current capture's retain set on read.
       const forCache = withConfiguredRetention(result, { retainComboTargets: false });
-      if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
+      if (!setCached(name, forCache, Date.now(), cacheGeneration, authorityIdentity)) {
         return observed(withConfiguredRetention(configured), "degraded");
       }
       // Publish roster-derived state only for a discovery the cache accepted: a stale
       // in-flight capture (generation revoked by a credential/config change) must not
       // overwrite the spelling or Max-Mode evidence of the newer one.
-      recordLiveCursorClaudeModels(liveResult.models);
+      const liveRosterScope = { provider: name, key: cursorLiveRosterScope(prov.baseUrl, apiKey) };
+      recordLiveCursorClaudeModels(liveResult.models, liveRosterScope);
       // Live Max-Mode evidence feeds the umbrella resolver's ultra gate
       // (devlog 260828_cursor_umbrella_catalog; union with static evidence).
-      recordLiveCursorMaxModeModels(liveResult.maxModeModels ?? []);
+      recordLiveCursorMaxModeModels(liveResult.maxModeModels ?? [], liveRosterScope);
       markProviderDiscoveryOk(name, liveResult.models.length);
       return observed(withConfiguredRetention(forCache, { warnDrops: true }), "authoritative");
     }
     if (isCurrentCacheGeneration()) {
-      markModelsFetchFailure(name);
+      markModelsFetchFailure(name, undefined, authorityIdentity);
       markProviderDiscoveryFailed(name, { reason: "provider" });
       console.warn(
         `[opencodex] Cursor model discovery for "${name}" failed [${liveResult.error}]${liveResult.detail ? `: ${liveResult.detail}` : ""}; using stale/static catalog degradation.`,
       );
     }
-    const staleCursor = getStaleCached(name);
+    const staleCursor = getStaleCached(name, authorityIdentity);
     return observed(
       withConfiguredRetention(
         staleCursor ? applyConfigHintsToCachedModels(name, prov, staleCursor, undefined, metadataModelIdCaseFold, captured.effectiveAlias) : configured,
diff --git a/src/codex/catalog/retained-sync.ts b/src/codex/catalog/retained-sync.ts
index 66e15186f29..efd3a63413e 100644
--- a/src/codex/catalog/retained-sync.ts
+++ b/src/codex/catalog/retained-sync.ts
@@ -15,9 +15,9 @@ import {
   availableAccountGatedNativeModels,
   codexModelEntitlementStateForAccount,
   isCodexModelEntitlementSnapshotCurrent,
-  resolveCodexModelEntitlements,
   type CodexModelEntitlementSnapshot,
 } from "../model-entitlements";
+import { resolveAdmittedCodexModelEntitlements } from "../model-entitlement-admission";
 import { isAccountNeedsReauth } from "../account-runtime-state";
 import { codexRuntimeStatePath } from "../runtime";
 import {
@@ -601,7 +601,7 @@ export async function syncCatalogModels(
       comboOmissions,
       providerModelOutcomes,
     }),
-    resolveCodexModelEntitlements(config),
+    resolveAdmittedCodexModelEntitlements(config),
   ]);
   const committed = withCatalogWriteSerialization(owningCodexHome, permit => {
     // Desired state can flip OFF during the provider await above. The catalog
diff --git a/src/codex/convergence.ts b/src/codex/convergence.ts
index c7f31ced057..212f4759593 100644
--- a/src/codex/convergence.ts
+++ b/src/codex/convergence.ts
@@ -78,9 +78,9 @@ import {
   availableAccountGatedNativeModels,
   codexModelEntitlementStateForAccount,
   isCodexModelEntitlementSnapshotCurrent,
-  resolveCodexModelEntitlements,
   type CodexModelEntitlementSnapshot,
 } from "./model-entitlements";
+import { resolveAdmittedCodexModelEntitlements } from "./model-entitlement-admission";
 import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./catalog/native-models";
 import { providerCodexAccountMode } from "../providers/registry";
 import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
@@ -434,7 +434,7 @@ export async function gatherCodexCatalogCandidate(
         providerModelOutcomes,
         discoveryPolicySnapshots: discoveryPolicies,
       }),
-      resolveCodexModelEntitlements(snapshot.config),
+      resolveAdmittedCodexModelEntitlements(snapshot.config),
     ]);
     const processLocal = processEvidence(source);
     const sourceEvidence = sealCatalogGatherEvidenceSession(session);
diff --git a/src/codex/history-provider.ts b/src/codex/history-provider.ts
index 15a7e3b8344..426e70624c2 100644
--- a/src/codex/history-provider.ts
+++ b/src/codex/history-provider.ts
@@ -335,6 +335,17 @@ class CodexHistoryIntegrityError extends Error {
  */
 export const HISTORY_RELABEL_STANDS_DOWN = "history_paginated_requires_native_writer";
 
+/**
+ * The narrower reason: a provider-table transition found an `openai`-tagged row Codex has
+ * already paginated. It is not a plain stand-down, because the transition also takes the root
+ * `openai_base_url` out, and that combination would send the conversation to Codex's built-in
+ * OpenAI endpoint rather than this proxy.
+ *
+ * A constant for the same reason as the one above: `src/codex/inject/paginated-openai-compat.ts`
+ * decides what to do about it, and a literal repeated in two files is how the pair drifts apart.
+ */
+export const HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE = "history_paginated_openai_requires_native_writer";
+
 function assertLegacyHistoryRecord(line: string): void {
   let value: unknown;
   try { value = JSON.parse(line); } catch { throw new CodexHistoryIntegrityError("history_rollout_record_invalid"); }
@@ -459,7 +470,7 @@ export function preflightCodexHistoryInjection(
       }
       assertLegacyHistoryWritable(row.rollout_path);
     }
-    if (foundPaginatedOpenaiRow) return "history_paginated_openai_requires_native_writer";
+    if (foundPaginatedOpenaiRow) return HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE;
     return foundPaginatedRow ? HISTORY_RELABEL_STANDS_DOWN : null;
   } catch (error) {
     return error instanceof CodexHistoryIntegrityError
diff --git a/src/codex/inject.ts b/src/codex/inject.ts
index 54c83105898..f88edfe67b0 100644
--- a/src/codex/inject.ts
+++ b/src/codex/inject.ts
@@ -41,6 +41,7 @@ import {
   writeJournal,
 } from "./journal";
 import { HISTORY_RELABEL_STANDS_DOWN, preflightCodexHistoryInjection } from "./history-provider";
+import { applyPaginatedOpenaiCompat } from "./inject/paginated-openai-compat";
 import {
   describeHistoryJobFailure,
   deriveCodexHistoryOperation,
@@ -347,12 +348,13 @@ async function injectCodexConfigImpl(
   // first-line repair cannot grow "openai" into "opencodex" without pre-existing padding, and
   // codex re-appends that stale first line whenever it writes git or memory-mode metadata.
   //
-  // Authless is excluded on purpose: its whole point is a provider that carries
-  // requires_openai_auth = false, and admission-token forms cannot use the root key at all.
-  // Those two forms therefore keep their existing behaviour, forward-tagging resume history with
-  // originals backed up, and that includes the case where a user enables authless and client
-  // compaction together. Only the compaction-only form skips the history unit.
-  const keepRootOverrideAlongsideTable = providerTableMode
+  // Authless is excluded here on purpose: its whole point is a provider that carries
+  // requires_openai_auth = false, so it forward-tags resume history with originals backed up
+  // instead, and that includes the case where a user enables authless and client compaction
+  // together. Only the compaction-only form skips the history unit up front. When forward
+  // tagging turns out to be impossible because Codex already paginated those rows, the same
+  // retention is selected below from the preflight verdict rather than from the routing form.
+  let keepRootOverrideAlongsideTable = providerTableMode
     && routingTarget.clientCompaction === true
     && routingTarget.desktopAuthless !== true
     && routingTarget.requiresAdmissionToken !== true;
@@ -472,14 +474,15 @@ async function injectCodexConfigImpl(
     if (observed && observed !== HISTORY_RELABEL_STANDS_DOWN) throw new CodexHistoryPreflightRefusal(observed);
     return observed;
   };
-  const observedHistoryRefusal = historyPreflight();
+  const compat = applyPaginatedOpenaiCompat(historyPreflight(), routingTarget, content, eol);
+  content = compat.content;
+  keepRootOverrideAlongsideTable ||= compat.retainedRootOverride;
+  const observedHistoryRefusal = compat.refusal;
   if (observedHistoryRefusal && observedHistoryRefusal !== HISTORY_RELABEL_STANDS_DOWN) {
     return {
       success: false,
       historyPreflightFailureReason: observedHistoryRefusal,
-      message: `Codex config injection refused: ${observedHistoryRefusal}. `
-        + "Existing provider definitions and conversation files were preserved. "
-        + "Paginated history requires native-writer coordination; do not run legacy recovery or retry this transition blindly.",
+      message: compat.message,
     };
   }
   let historyRelabelRefusal = observedHistoryRefusal;
@@ -607,11 +610,11 @@ async function injectCodexConfigImpl(
     atomicWriteFile(CODEX_PROFILE_PATH, profileContent);
     markJournalInjectedState(content, profileContent, {
       // A root override is ours whenever we wrote one and no user-owned value won. That is
-      // loopback Design B, and now also the client-compaction form, which keeps the same
-      // marker-owned root line beside its provider table. Journaling it matters because the
-      // marker comment is not durable: the Codex app can reserialize config.toml and drop
-      // comments, and restore then has only the journaled value to tell our line from a user's
-      // (#1798). The other table forms never write the key, so they still record null.
+      // loopback Design B, the client-compaction form, and any table form that retained the
+      // root line for a paginated openai row, all of which keep the marker-owned line beside
+      // the table. Journaling it matters because the marker comment is not durable: the Codex
+      // app can reserialize config.toml and drop comments, and restore then has only the
+      // journaled value to tell our line from a user's (#1798). Other table forms record null.
       injectedOpenaiBaseUrl: (providerTableMode && !keepRootOverrideAlongsideTable) || keptUserBaseUrl
         ? null
         : rootTomlString(content, "openai_base_url"),
diff --git a/src/codex/inject/config-toml.ts b/src/codex/inject/config-toml.ts
index 23a223d221d..1e552dbbef3 100644
--- a/src/codex/inject/config-toml.ts
+++ b/src/codex/inject/config-toml.ts
@@ -4,6 +4,7 @@ import { contextCompatibleBaseLine } from "../context-compat";
 import { resolveEffectiveProjectModelProvider } from "../project-config-warnings";
 import {
   OCX_SECTION_MARKER,
+  OCX_ROUTING_MARKER_LINE,
   REALTIME_WS_BASE_URL_KEY,
   isRootOpenaiBaseUrlLine,
   isRootRealtimeWsBaseUrlLine,
@@ -128,7 +129,7 @@ export function buildProviderTableBlockForTarget(
 ): string {
   const lines = [
     "",
-    OCX_SECTION_MARKER,
+    OCX_ROUTING_MARKER_LINE,
     "[model_providers.opencodex]",
     `name = ${tomlString(resolveCodexProviderDisplayName(displayName))}`,
     `base_url = ${tomlString(target.baseUrl)}`,
@@ -213,6 +214,9 @@ export function setRootOpenaiBaseUrl(
     if (!isRootOpenaiBaseUrlLine(lines[i])) continue;
     const markerOwned = i > 0 && lines[i - 1].includes(OCX_SECTION_MARKER);
     if (!markerOwned) return { content, keptUserBaseUrl: true };
+    // Refresh the marker too, so a config injected by a build that predates the recovery
+    // hint gains it on the next `ocx start` instead of keeping a bare marker forever.
+    lines[i - 1] = OCX_ROUTING_MARKER_LINE;
     lines[i] = key;
     return { content: lines.join("\n"), keptUserBaseUrl: false };
   }
@@ -222,7 +226,7 @@ export function setRootOpenaiBaseUrl(
       content:
         content.replace(/\n+$/, "") +
         "\n" +
-        OCX_SECTION_MARKER +
+        OCX_ROUTING_MARKER_LINE +
         "\n" +
         key +
         "\n",
@@ -231,7 +235,7 @@ export function setRootOpenaiBaseUrl(
   }
   let insertAt = firstTable;
   while (insertAt > 0 && lines[insertAt - 1].trim() === "") insertAt--;
-  lines.splice(insertAt, 0, OCX_SECTION_MARKER, key);
+  lines.splice(insertAt, 0, OCX_ROUTING_MARKER_LINE, key);
   return { content: lines.join("\n"), keptUserBaseUrl: false };
 }
 
@@ -247,18 +251,19 @@ export function setRootOpenaiBaseUrlForTarget(
     if (!isRootOpenaiBaseUrlLine(lines[index])) continue;
     const markerOwned = index > 0 && lines[index - 1].includes(OCX_SECTION_MARKER);
     if (!markerOwned) return { content, keptUserBaseUrl: true };
+    lines[index - 1] = OCX_ROUTING_MARKER_LINE;
     lines[index] = key;
     return { content: lines.join("\n"), keptUserBaseUrl: false };
   }
   if (firstTable === -1) {
     return {
-      content: `${content.replace(/\n+$/, "")}\n${OCX_SECTION_MARKER}\n${key}\n`,
+      content: `${content.replace(/\n+$/, "")}\n${OCX_ROUTING_MARKER_LINE}\n${key}\n`,
       keptUserBaseUrl: false,
     };
   }
   let insertAt = firstTable;
   while (insertAt > 0 && lines[insertAt - 1].trim() === "") insertAt -= 1;
-  lines.splice(insertAt, 0, OCX_SECTION_MARKER, key);
+  lines.splice(insertAt, 0, OCX_ROUTING_MARKER_LINE, key);
   return { content: lines.join("\n"), keptUserBaseUrl: false };
 }
 
@@ -284,13 +289,14 @@ export function setRootRealtimeWsBaseUrl(
     if (!isRootRealtimeWsBaseUrlLine(lines[index])) continue;
     const markerOwned = index > 0 && lines[index - 1].includes(OCX_SECTION_MARKER);
     if (!markerOwned) return { content, keptUserRealtimeWsBaseUrl: true };
+    lines[index - 1] = OCX_ROUTING_MARKER_LINE;
     lines[index] = key;
     return { content: lines.join("\n"), keptUserRealtimeWsBaseUrl: false };
   }
   for (let index = 0; index < rootEnd; index += 1) {
     if (!isRootOpenaiBaseUrlLine(lines[index])) continue;
     if (!(index > 0 && lines[index - 1].includes(OCX_SECTION_MARKER))) continue;
-    lines.splice(index + 1, 0, OCX_SECTION_MARKER, key);
+    lines.splice(index + 1, 0, OCX_ROUTING_MARKER_LINE, key);
     return { content: lines.join("\n"), keptUserRealtimeWsBaseUrl: false };
   }
   // No marker-owned routing override to attach to: the override has no owner, so inject nothing.
@@ -603,3 +609,32 @@ export function chooseCatalogPathForInjection(
 
   return existsSync(DEFAULT_CATALOG_PATH) ? DEFAULT_CATALOG_PATH : null;
 }
+
+/**
+ * The effective `model_catalog_json` is one of ours and the file is gone.
+ *
+ * Codex does not degrade on this: a catalog path it cannot read stops it loading its
+ * configuration at all, which looks exactly like the routing lockout in #5261 and is what the
+ * reporter's machine was left in after the catalog file was deleted by hand.
+ *
+ * Injection already repairs it — the chooser refuses a missing owned path and the caller strips
+ * the stale line. That only helps someone who runs opencodex again, and the whole difficulty of
+ * this state is that Codex is the thing that stopped working, so nothing prompts them to. This
+ * predicate exists so the CLI can say it out loud.
+ *
+ * A user-owned catalog assignment wins here exactly as it does during injection: if they named
+ * the file, its absence is theirs to explain, and we do not claim it.
+ *
+ * Ownership is decided by basename, which is a weak test — a file the user happens to name
+ * `opencodex-catalog.json` is read as ours wherever it sits. That is deliberate rather than
+ * overlooked: it is the same test injection already applies, and a detector that drew the line
+ * somewhere else would report a state injection would then treat differently. Tightening it is a
+ * change to injection, not to this.
+ */
+export function missingOwnedCatalogPath(content: string): string | null {
+  const existing = readRootModelCatalogPath(content);
+  if (!existing) return null;
+  const resolved = resolveCodexConfigPath(existing);
+  if (!isOpencodexCatalogPath(resolved)) return null;
+  return existsSync(resolved) ? null : existing;
+}
diff --git a/src/codex/inject/paginated-openai-compat.ts b/src/codex/inject/paginated-openai-compat.ts
new file mode 100644
index 00000000000..eb4e3301f11
--- /dev/null
+++ b/src/codex/inject/paginated-openai-compat.ts
@@ -0,0 +1,90 @@
+/**
+ * The way forward for a provider-table transition that finds an `openai`-tagged row
+ * Codex has already migrated to paginated history.
+ *
+ * The refusal this resolves is correct about the danger and wrong about the remedy.
+ * A provider-table transition takes the root `openai_base_url` out, and a paginated row
+ * cannot be relabeled, so the transition as planned would send that conversation to
+ * Codex's built-in OpenAI endpoint. Refusing to relabel is right. Refusing the whole
+ * transition left #5321's reporter with 173 conversations and two unsupported exits:
+ * delete them, or downgrade.
+ *
+ * There is a third state, and the injector already builds it for the client-compaction
+ * form: keep the marker-owned root override beside the provider table. Codex merges the
+ * override onto its built-in `openai` entry when it builds the provider map, so the
+ * paginated row keeps reaching this proxy while never being rewritten. The transition
+ * completes, the relabel stands down, and no rollout byte or thread row is touched.
+ *
+ * Two cases cannot reach that state. An admission-token form cannot use the root key at
+ * all, because Codex's built-in `openai` entry carries no `x-opencodex-api-key` header;
+ * that one keeps the refusal and names what the operator can actually do. A root line the
+ * user owns is left alone, and the conversation follows their configuration rather than
+ * this proxy — the same guarantee the injector already makes everywhere else about a line
+ * it does not own.
+ */
+import { HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE, HISTORY_RELABEL_STANDS_DOWN } from "../history-provider";
+import { applyEol, setRootOpenaiBaseUrlForTarget, stripInjectedOpenaiBaseUrl } from "./config-toml";
+import type { CodexRoutingTarget } from "./routing-target";
+
+export interface PaginatedOpenaiCompatDecision {
+  /** The refusal that survives. `null` only when the preflight raised none. */
+  readonly refusal: string | null;
+  /** Candidate config bytes, carrying the retained root override when one was written. */
+  readonly content: string;
+  /** True only when OpenCodex wrote the retained line and must journal it as its own. */
+  readonly retainedRootOverride: boolean;
+  /** What the caller reports when `refusal` is not the stand-down reason. */
+  readonly message: string;
+}
+
+function genericRefusal(refusal: string): string {
+  return `Codex config injection refused: ${refusal}. `
+    + "Existing provider definitions and conversation files were preserved. "
+    + "Paginated history requires native-writer coordination; do not run legacy recovery or retry this transition blindly.";
+}
+
+/**
+ * Named next actions, because "do not retry" is what trapped the reporter. Both are
+ * configuration the operator already owns: the loopback listener is what makes the root
+ * override usable, and `syncResumeHistory` is the existing opt-out from history remapping.
+ */
+function admissionTokenRefusal(): string {
+  return `Codex config injection refused: ${HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE}. `
+    + "Existing provider definitions and conversation files were preserved. "
+    + "This home has conversations tagged openai whose history Codex has already migrated to its paginated "
+    + "format, and they cannot be relabeled. Keeping them on this proxy needs a root openai_base_url override, "
+    + "which this routing form cannot use: Codex's built-in openai provider carries no x-opencodex-api-key header. "
+    + "To complete the transition, either route Codex through the loopback listener "
+    + "(unauthenticatedLoopbackListener.enabled, or a loopback hostname) so the override can be retained, "
+    + "or set syncResumeHistory to false to accept that those conversations resume against Codex's own OpenAI endpoint.";
+}
+
+/**
+ * Resolve the transition, retaining the root override when this routing form can own one.
+ *
+ * `content` is the fully assembled provider-table candidate: OpenCodex's own root override
+ * has already been stripped and not re-added, so a root `openai_base_url` still present in it
+ * belongs to the user.
+ */
+export function applyPaginatedOpenaiCompat(
+  refusal: string | null,
+  target: CodexRoutingTarget,
+  content: string,
+  eol: "\r\n" | "\n",
+): PaginatedOpenaiCompatDecision {
+  if (refusal !== HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE) {
+    return { refusal, content, retainedRootOverride: false, message: refusal ? genericRefusal(refusal) : "" };
+  }
+  if (target.requiresAdmissionToken === true) {
+    return { refusal, content, retainedRootOverride: false, message: admissionTokenRefusal() };
+  }
+  const written = setRootOpenaiBaseUrlForTarget(stripInjectedOpenaiBaseUrl(applyEol(content, "\n")), target);
+  // The relabel still stands down either way: the row stays tagged openai and paginated, and
+  // the caller uses this reason to skip the history unit rather than let it start and refuse.
+  return {
+    refusal: HISTORY_RELABEL_STANDS_DOWN,
+    content: written.keptUserBaseUrl ? content : applyEol(written.content, eol),
+    retainedRootOverride: !written.keptUserBaseUrl,
+    message: "",
+  };
+}
diff --git a/src/codex/injected-marker.ts b/src/codex/injected-marker.ts
index 08033176488..bf27f8185aa 100644
--- a/src/codex/injected-marker.ts
+++ b/src/codex/injected-marker.ts
@@ -11,6 +11,24 @@ import { parseTomlString } from "./paths";
 
 export const OCX_SECTION_MARKER = "# Auto-injected by opencodex";
 
+/**
+ * The marker line actually written above ROUTING keys, carrying the command that undoes them.
+ *
+ * #5261: a Windows user whose proxy had stopped was locked out of Codex sign-in, because the
+ * root `openai_base_url` we write keeps pointing Codex's built-in openai provider at a port
+ * nothing is listening on. The only surface such a user can still read is `config.toml` itself,
+ * and it said nothing but "Auto-injected by opencodex" — so the recovery they found was to
+ * hand-delete lines and the catalog file, which is strictly worse than `ocx restore`.
+ *
+ * Every ownership predicate below matches on {@link OCX_SECTION_MARKER} as a SUBSTRING, never by
+ * equality, so this longer line is recognized by them and by any opencodex old enough to predate
+ * it. That is the whole reason the hint is appended to the marker instead of occupying a line of
+ * its own: a separate comment line would survive removal as orphaned text.
+ *
+ * Scope is routing only. Prompt layers keep the bare marker: `ocx restore` is not their undo.
+ */
+export const OCX_ROUTING_MARKER_LINE = `${OCX_SECTION_MARKER} (undo: ocx restore)`;
+
 export function isRootOpenaiBaseUrlLine(line: string): boolean {
   return /^\s*openai_base_url\s*=/.test(line);
 }
diff --git a/src/codex/main-account.ts b/src/codex/main-account.ts
index e232055db23..09a11eaa86a 100644
--- a/src/codex/main-account.ts
+++ b/src/codex/main-account.ts
@@ -404,6 +404,12 @@ async function resolveMainAccountToken(
             : "transient" as const;
           throw new MainAccountTokenRefreshError(reason, { cause });
         }
+        // The refresh may resolve after the caller went away (an implementation that does
+        // not observe the signal, or an abort landing in the window between resolution and
+        // commit). A cancelled request's late refresh must not rewrite auth.json on behalf
+        // of a request that no longer exists -- the same fence the reauth twin applies
+        // before its own commit above.
+        if (dependencies.signal?.aborted) throw dependencies.signal.reason;
         const result = persistRefreshedMainAuthJson(locked, refreshed);
         if (dependencies.preserveReauth !== true) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
         return result;
diff --git a/src/codex/model-cache.ts b/src/codex/model-cache.ts
index c69d15abc9e..2da07787ec3 100644
--- a/src/codex/model-cache.ts
+++ b/src/codex/model-cache.ts
@@ -10,6 +10,7 @@
 import type { CatalogModel } from "./catalog";
 import type { GenerationContext } from "../lib/state-store-sweeper";
 import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../lib/app-owned-memory";
+import { clearLiveCursorRosterState } from "../adapters/cursor/catalog";
 
 /** Default freshness window. Matches Codex's own 5-min models cache so the two stay in step. */
 export const DEFAULT_MODEL_CACHE_TTL_MS = 5 * 60 * 1000;
@@ -80,7 +81,17 @@ function deleteCachedProvider(provider: string): number {
  * the full fetch timeout on every catalog poll (issue #54: UI stalls behind corporate proxies). */
 export const MODELS_FETCH_FAILURE_COOLDOWN_MS = 30_000;
 
-const failureAt = new Map<string, number>();
+interface DiscoveryFailure {
+  at: number;
+  /**
+   * Credential the failure was observed under, for entitlement-specific rosters. Absent means
+   * the failure is credential-agnostic (a plain `/models` endpoint) and suppresses every
+   * caller, which is the original #54 behaviour.
+   */
+  authorityIdentity?: string;
+}
+
+const failureAt = new Map<string, DiscoveryFailure>();
 const discoveryStatus = new Map<string, ProviderModelDiscoveryStatus>();
 /**
  * How many models the last successful discovery actually returned, before any configured-alias
@@ -91,8 +102,12 @@ const discoveryStatus = new Map<string, ProviderModelDiscoveryStatus>();
 const liveModelCounts = new Map<string, number>();
 let lastReconciledGeneration = 0;
 
-export function markModelsFetchFailure(provider: string, now = Date.now()): void {
-  failureAt.set(provider, now);
+export function markModelsFetchFailure(
+  provider: string,
+  now = Date.now(),
+  authorityIdentity?: string,
+): void {
+  failureAt.set(provider, { at: now, ...(authorityIdentity ? { authorityIdentity } : {}) });
 }
 
 /** `liveModelCount` is required so a caller that forgets to pass it fails typecheck instead of
@@ -147,9 +162,25 @@ export function getProviderLiveModelCount(provider: string): number | undefined
   return liveModelCounts.get(provider);
 }
 
-export function isModelsFetchCoolingDown(provider: string, cooldownMs = MODELS_FETCH_FAILURE_COOLDOWN_MS, now = Date.now()): boolean {
-  const at = failureAt.get(provider);
-  return at !== undefined && now - at < cooldownMs;
+/**
+ * Whether a failed discovery still suppresses the next one.
+ *
+ * `authorityIdentity` scopes the suppression to the credential that actually observed the
+ * failure. A roster that upstream filters per account is evidence about that account, and
+ * one account's 401 or 404 must not decide that a different account has no catalog. A
+ * failure recorded without an identity stays credential-agnostic and suppresses everyone,
+ * so the plain-endpoint providers keep the timeout protection #54 added.
+ */
+export function isModelsFetchCoolingDown(
+  provider: string,
+  cooldownMs = MODELS_FETCH_FAILURE_COOLDOWN_MS,
+  now = Date.now(),
+  authorityIdentity?: string,
+): boolean {
+  const failure = failureAt.get(provider);
+  if (failure === undefined || now - failure.at >= cooldownMs) return false;
+  if (failure.authorityIdentity === undefined || authorityIdentity === undefined) return true;
+  return failure.authorityIdentity === authorityIdentity;
 }
 
 /** Fresh cached models for a provider, or null when absent/stale (caller should re-fetch). */
@@ -240,6 +271,7 @@ export function clearModelCache(
   provider?: string,
   reason: ModelCacheClearReason = "authority",
 ): void {
+  clearLiveCursorRosterState(provider);
   const revokesInFlightDiscovery = reason === "authority";
   if (provider) {
     if (revokesInFlightDiscovery) {
diff --git a/src/codex/model-entitlement-admission.ts b/src/codex/model-entitlement-admission.ts
new file mode 100644
index 00000000000..1b80fef2cc4
--- /dev/null
+++ b/src/codex/model-entitlement-admission.ts
@@ -0,0 +1,59 @@
+import type { OcxConfig } from "../types";
+import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
+import {
+  resolveCodexModelEntitlements,
+  type CodexModelEntitlementResolveOptions,
+  type CodexModelEntitlementSnapshot,
+} from "./model-entitlements";
+import {
+  type NativeMainCredentialAdmissionDeps,
+  withNativeMainCredentialAdmission,
+} from "./native-main-admission";
+
+interface ModelEntitlementAdmissionDeps extends NativeMainCredentialAdmissionDeps {
+  readonly resolve?: typeof resolveCodexModelEntitlements;
+}
+
+function excludeNativeMain(
+  options: CodexModelEntitlementResolveOptions,
+): CodexModelEntitlementResolveOptions {
+  return {
+    ...options,
+    excludeAccountIds: new Set([
+      ...(options.excludeAccountIds ?? []),
+      MAIN_CODEX_ACCOUNT_ID,
+    ]),
+  };
+}
+
+/**
+ * Resolve background/data-plane entitlements inside the native-main fences.
+ *
+ * Pool discovery remains available when startup recovery or a profile drain
+ * owns the physical credential. When main is admitted, the process-local lease
+ * covers only the credential snapshot: getValidMainAccountToken holds the
+ * cross-process exclusive claim just for the auth.json refresh write, and the
+ * lease is released before the upstream entitlement request so a profile drain
+ * never waits on a network fetch.
+ */
+export async function resolveAdmittedCodexModelEntitlements(
+  config: Pick<OcxConfig, "codexAccounts">,
+  options: CodexModelEntitlementResolveOptions = {},
+  deps: ModelEntitlementAdmissionDeps = {},
+): Promise<CodexModelEntitlementSnapshot> {
+  const resolve = deps.resolve ?? resolveCodexModelEntitlements;
+  // A caller-supplied roster or an already-excluded main never reads auth.json,
+  // so there is no native credential to fence.
+  if (options.credentials || options.excludeAccountIds?.has(MAIN_CODEX_ACCOUNT_ID)) {
+    return resolve(config, options);
+  }
+  return withNativeMainCredentialAdmission(
+    (excludedAccountIds, releaseMainLease) => resolve(
+      config,
+      excludedAccountIds.size === 0
+        ? { ...options, releaseNativeMainCredentialLease: releaseMainLease }
+        : excludeNativeMain(options),
+    ),
+    { acquireNativeMain: deps.acquireNativeMain },
+  );
+}
diff --git a/src/codex/model-entitlements.ts b/src/codex/model-entitlements.ts
index c9e1c8c8e0e..611ce115cfc 100644
--- a/src/codex/model-entitlements.ts
+++ b/src/codex/model-entitlements.ts
@@ -13,6 +13,7 @@ import {
   MAIN_CODEX_ACCOUNT_ID,
   type NativeMainRefreshDependencies,
 } from "./main-account";
+import { withNativeMainCredentialAdmission } from "./native-main-admission";
 import {
   ACCOUNT_GATED_NATIVE_OPENAI_MODELS,
   NATIVE_GPT6_ASTRA_MODEL,
@@ -439,6 +440,12 @@ export interface CodexModelEntitlementResolveOptions {
   readonly excludeAccountIds?: ReadonlySet<string>;
   /** Ensure-only fence; ordinary request resolvers retain their established flight identity. */
   readonly credentialMutationEpoch?: number;
+  /**
+   * Internal plumbing from `withNativeMainCredentialAdmission`: releases the
+   * native-main lifecycle lease once the credential phase settles, before any
+   * upstream roster fetch, so a profile drain never waits on network work.
+   */
+  readonly releaseNativeMainCredentialLease?: () => void;
 }
 
 export interface CodexEntitlementFreshnessOptions extends Pick<
@@ -452,6 +459,8 @@ export interface CodexEntitlementFreshnessOptions extends Pick<
   | "signal"
 > {
   readonly waitMs?: number;
+  /** Test seam for the native-main admission fence around the refresh workset. */
+  readonly nativeMainCredentialAdmission?: typeof withNativeMainCredentialAdmission;
 }
 
 const accountModelsCache = new Map<string, CachedAccountModels>();
@@ -581,21 +590,31 @@ function currentCredentialIdentity(accountId: string): string | undefined {
 
 async function accountCredentialSnapshot(
   accountId: string,
-  options: Pick<CodexModelEntitlementResolveOptions, "nativeMainRefreshDependencies" | "signal"> = {},
+  options: Pick<
+    CodexModelEntitlementResolveOptions,
+    "nativeMainRefreshDependencies" | "releaseNativeMainCredentialLease" | "signal"
+  > = {},
 ): Promise<CodexModelEntitlementCredentialSnapshot | null> {
   if (accountId === MAIN_CODEX_ACCOUNT_ID) {
-    const token = await getValidMainAccountToken({
-      signal: options.signal,
-      ...(options.nativeMainRefreshDependencies ?? {}),
-    });
-    return token
-      ? {
-        accountId,
-        accessToken: token.accessToken,
-        chatgptAccountId: token.chatgptAccountId,
-        credentialIdentity: `main:${token.chatgptAccountId}`,
-      }
-      : null;
+    try {
+      const token = await getValidMainAccountToken({
+        signal: options.signal,
+        ...(options.nativeMainRefreshDependencies ?? {}),
+      });
+      return token
+        ? {
+          accountId,
+          accessToken: token.accessToken,
+          chatgptAccountId: token.chatgptAccountId,
+          credentialIdentity: `main:${token.chatgptAccountId}`,
+        }
+        : null;
+    } finally {
+      // The lifecycle lease fences only this credential read; releasing here —
+      // on success and on a credential-ownership failure alike — keeps a
+      // profile drain from waiting on the roster fetches that follow.
+      options.releaseNativeMainCredentialLease?.();
+    }
   }
   try {
     const token = await getValidCodexToken(accountId);
@@ -911,38 +930,58 @@ async function refreshCodexEntitlementWorkset(
   mutationEpoch: number,
   options: CodexEntitlementFreshnessOptions,
 ): Promise<void> {
-  const credentialSnapshot = options.credentialSnapshot ?? accountCredentialSnapshot;
-  const observations = await Promise.all(workset.map(async accountId => {
-    const credential = await credentialSnapshot(accountId, options);
-    return {
-      accountId,
-      credential,
-      absenceObservedAt: options.now ?? Date.now(),
-    };
-  }));
-  const credentials = observations.flatMap(observation => observation.credential
-    ? [observation.credential]
-    : []);
-  if (credentials.length > 0) {
-    await resolveCodexModelEntitlements(config, {
-      ...options,
-      clientVersion,
-      credentialMutationEpoch: mutationEpoch,
-      credentials,
-    });
-  }
+  const run = async (
+    excludedAccountIds: ReadonlySet<string>,
+    releaseMainLease?: () => void,
+  ): Promise<void> => {
+    // An excluded main is filtered before the snapshot phase, not just before the
+    // roster fetch: it never produces an absence observation, so a denied
+    // admission cannot memoize a credential read that never happened.
+    const admittedWorkset = excludedAccountIds.size === 0
+      ? workset
+      : workset.filter(accountId => !excludedAccountIds.has(accountId));
+    const credentialSnapshot = options.credentialSnapshot ?? accountCredentialSnapshot;
+    const observations = await Promise.all(admittedWorkset.map(async accountId => {
+      const credential = await credentialSnapshot(accountId, {
+        ...options,
+        releaseNativeMainCredentialLease: releaseMainLease,
+      });
+      return {
+        accountId,
+        credential,
+        absenceObservedAt: options.now ?? Date.now(),
+      };
+    }));
+    // The lease fences only the credential phase; release before roster fetches
+    // so a profile drain never waits on upstream network work.
+    releaseMainLease?.();
+    const credentials = observations.flatMap(observation => observation.credential
+      ? [observation.credential]
+      : []);
+    if (credentials.length > 0) {
+      await resolveCodexModelEntitlements(config, {
+        ...options,
+        clientVersion,
+        credentialMutationEpoch: mutationEpoch,
+        credentials,
+      });
+    }
 
-  for (const observation of observations) {
-    if (observation.credential) continue;
-    const capturedIdentity = identityVector.get(observation.accountId) ?? null;
-    if (codexCredentialMutationEpoch() !== mutationEpoch) continue;
-    if ((currentCredentialIdentity(observation.accountId) ?? null) !== capturedIdentity) continue;
-    boundedNegativeCredentialMemoSet(observation.accountId, {
-      credentialIdentity: capturedIdentity,
-      mutationEpoch,
-      expiresAt: observation.absenceObservedAt + MODEL_ROSTER_NEGATIVE_CREDENTIAL_TTL_MS,
-    });
-  }
+    for (const observation of observations) {
+      if (observation.credential) continue;
+      const capturedIdentity = identityVector.get(observation.accountId) ?? null;
+      if (codexCredentialMutationEpoch() !== mutationEpoch) continue;
+      if ((currentCredentialIdentity(observation.accountId) ?? null) !== capturedIdentity) continue;
+      boundedNegativeCredentialMemoSet(observation.accountId, {
+        credentialIdentity: capturedIdentity,
+        mutationEpoch,
+        expiresAt: observation.absenceObservedAt + MODEL_ROSTER_NEGATIVE_CREDENTIAL_TTL_MS,
+      });
+    }
+  };
+  if (!workset.includes(MAIN_CODEX_ACCOUNT_ID)) return run(new Set<string>());
+  const admission = options.nativeMainCredentialAdmission ?? withNativeMainCredentialAdmission;
+  return admission(run);
 }
 
 function waitForEntitlementEnsureFlight(
@@ -1110,6 +1149,10 @@ export async function resolveCodexModelEntitlements(
     ? [...options.credentials].filter(credential => !options.excludeAccountIds?.has(credential.accountId))
     : (await Promise.all(allowedAccountIds.map(accountId => credentialSnapshot(accountId, options))))
       .filter((value): value is CodexModelEntitlementCredentialSnapshot => value !== null);
+  // The credential phase is the only part the native-main lease fences. The
+  // real snapshot releases it as soon as the main token settles; this boundary
+  // release keeps the guarantee when a seam snapshot never invokes it.
+  options.releaseNativeMainCredentialLease?.();
   const results = await Promise.all(credentials.map(async credential => ({
     credential,
     result: await modelsForCredential(
diff --git a/src/codex/native-main-admission.ts b/src/codex/native-main-admission.ts
index f5c7e809c3b..7083887b48d 100644
--- a/src/codex/native-main-admission.ts
+++ b/src/codex/native-main-admission.ts
@@ -3,7 +3,13 @@ import {
   tryAcquireNativeMainProfileClaim as tryAcquireLifecycleNativeMainProfileClaim,
   tryClaimNativeMainProfileForTurn as tryClaimLifecycleNativeMainProfileForTurn,
 } from "../server/lifecycle";
+import {
+  MAIN_CODEX_ACCOUNT_ID,
+  MainAccountTokenRefreshError,
+  MainAuthJsonChangedDuringRefreshError,
+} from "./main-account";
 import { isNativeMainTrafficBlocked } from "./native-profile-startup";
+import { NativeProfileError } from "./native-profile-types";
 
 export interface NativeMainTurnClaimDeps {
   /** Test seams for the synchronous precheck/claim/postcheck transition. */
@@ -45,3 +51,80 @@ export function tryAcquireNativeMainProfileClaim(): AdmissionLease | null {
   claim.release();
   return null;
 }
+
+export interface NativeMainCredentialAdmissionDeps {
+  /** Test seam for the synchronous admission precheck. */
+  readonly acquireNativeMain?: () => AdmissionLease | null;
+}
+
+const NO_EXCLUDED_ACCOUNT_IDS: ReadonlySet<string> = new Set();
+const NATIVE_MAIN_EXCLUDED_ACCOUNT_IDS: ReadonlySet<string> = new Set([MAIN_CODEX_ACCOUNT_ID]);
+const RELEASE_NOTHING = () => {};
+
+/**
+ * Run credential-backed work inside the native-main lifecycle fence.
+ *
+ * The lease keeps startup recovery and profile drains from owning the physical
+ * credential while the operation reads it. Cross-process ownership of the file
+ * itself is already coordinated inside the refresh path's exclusive claim, so
+ * this fence deliberately does not take the shared claim: holding it across an
+ * operation that may refresh would ask for exclusive ownership against our own
+ * shared lock, and holding it across the upstream work that follows would
+ * stall an unrelated credential commit behind a network fetch.
+ *
+ * The fence covers only the credential read. The operation must invoke
+ * `releaseMainLease` as soon as the native-main credential settles — on both
+ * the success and the credential-error path — and before any upstream model
+ * listing, so a profile drain never waits on a network fetch while this turn
+ * is still counted. The wrapper releases on settle regardless, so an
+ * operation without a fenced credential phase may ignore the callback.
+ *
+ * When the gate refuses, or the credential cannot be read because another
+ * lifecycle owns it, the operation reruns with main excluded so independent
+ * Pool work is never suppressed by main's unavailability.
+ */
+export async function withNativeMainCredentialAdmission<T>(
+  operation: (
+    excludeAccountIds: ReadonlySet<string>,
+    releaseMainLease?: () => void,
+  ) => Promise<T>,
+  deps: NativeMainCredentialAdmissionDeps = {},
+): Promise<T> {
+  const lease = (deps.acquireNativeMain ?? tryAcquireNativeMainProfileClaim)();
+  if (!lease) return operation(NATIVE_MAIN_EXCLUDED_ACCOUNT_IDS, RELEASE_NOTHING);
+  let released = false;
+  const releaseMainLease = () => {
+    if (released) return;
+    released = true;
+    lease.release();
+  };
+  try {
+    return await operation(NO_EXCLUDED_ACCOUNT_IDS, releaseMainLease);
+  } catch (error) {
+    // The Pool-only retry never reads the native-main credential; release first
+    // so a profile drain is not kept waiting behind Pool network work.
+    releaseMainLease();
+    if (!isNativeMainCredentialUnavailableError(error)) throw error;
+    return await operation(NATIVE_MAIN_EXCLUDED_ACCOUNT_IDS, RELEASE_NOTHING);
+  } finally {
+    releaseMainLease();
+  }
+}
+
+/**
+ * The credential-ownership failures that make main unavailable for one
+ * operation: a foreign exclusive holder or an unsupported claim filesystem
+ * (NATIVE_MAIN_CLAIM_BUSY / NATIVE_MAIN_CLAIM_UNAVAILABLE), a writer that moved
+ * auth.json mid-refresh, or a grant that no longer refreshes. Like a Pool
+ * credential failure, none of them may suppress independent Pool discovery.
+ * Any other NativeProfileError — MAIN_REQUESTS_ACTIVE, VAULT_INVALID,
+ * INTERNAL_ERROR — is not a credential-ownership failure and propagates.
+ */
+function isNativeMainCredentialUnavailableError(error: unknown): boolean {
+  if (error instanceof NativeProfileError) {
+    return error.code === "NATIVE_MAIN_CLAIM_BUSY"
+      || error.code === "NATIVE_MAIN_CLAIM_UNAVAILABLE";
+  }
+  return error instanceof MainAuthJsonChangedDuringRefreshError
+    || error instanceof MainAccountTokenRefreshError;
+}
diff --git a/src/codex/routing.ts b/src/codex/routing.ts
index a6c06eed431..5a092186d32 100644
--- a/src/codex/routing.ts
+++ b/src/codex/routing.ts
@@ -28,6 +28,7 @@ import {
   type CodexUpstreamOutcomeMeta,
 } from "./routing/cooldown-math";
 import {
+  carriesQuotaRefusal,
   codexPoolKeyForScope,
   codexQuotaScopeForModel,
   deleteAccountHealth,
@@ -38,6 +39,7 @@ import {
   getCodexAccountCooldownUntil,
   getCodexAccountSoftAvoidUntil,
   getCodexQuotaHealthSnapshot,
+  hasUnrecoveredCodexQuotaRefusal,
   isCodexAccountSoftAvoided,
   isCodexQuotaAvoided,
   isHealthAccountAdmissible,
@@ -93,6 +95,7 @@ import {
   getEligiblePoolAccounts,
   getPoolAccountPlanForSelection,
   hasCodexQuotaHeadroom,
+  hasCodexSharedStateQuotaHeadroom,
   isCodexAccountPlanExcluded,
   isCodexAccountSelectable,
   isHealthySharedCodexSelection,
@@ -489,45 +492,6 @@ export function resolveCodexAccountForThread(
   return resolution.status === "selected" ? resolution.accountId : null;
 }
 
-function carriesQuotaRefusal(health: CodexUpstreamHealth | undefined): boolean {
-  return health?.lastFailureStatus === 429 || health?.lastFailureStatus === 402;
-}
-
-/**
- * Has this account refused a request on quota without serving one since?
- *
- * Thread affinity is a prompt-cache optimization and every rule around it is a preference:
- * `autoSwitchThreshold` is a hint that an account is getting busy, and `pool.cacheAffinity`
- * deliberately raises that bar further. A refusal is not a preference, and once the account has
- * told THIS thread it cannot serve, the binding has nothing left to optimize.
- *
- * The distinction matters because the cooldown a 429 writes is deliberately short. A reset
- * announcement is advisory — plan quota routinely frees up before the advertised instant — so
- * {@link CODEX_MAX_RESET_DERIVED_COOLDOWN_MS} caps it at 15 minutes. The five-hour window that
- * announcement describes is not capped, so an account whose burst window is spent looks
- * selectable again long before it is. For an unbound request that is correct: going back to find
- * out is how the pool learns the window moved. For a BOUND thread it is a loop with no exit —
- * the cooldown lapses, the account still scores lowest on the only window this proxy has a
- * reading for (its weekly bar, untouched by a burst limit), the thread rebinds, and earns the
- * identical 429. Cleared affinity does not help: the next request re-derives the same choice.
- * From the Codex side that reads exactly as reported — a new session rotates normally while an
- * existing one is locked to an exhausted account until the proxy is restarted, because a restart
- * is the only thing that drops the binding and the stale health together.
- *
- * `lastFailureStatus` is the right evidence because of when it ends: {@link preservedCooldownFields}
- * strips it from every recovery write, so it survives exactly until the account actually serves a
- * request again. Nothing here blocks that — selection is untouched, so unbound traffic still probes
- * the account and the first success releases every thread this refused.
- *
- * Scope follows where the refusal was recorded. An account-wide throttle lands in
- * `upstreamHealth` and releases every lane; a reset-derived refusal lands against one native
- * quota group, so a spent Spark window still cannot displace the same thread's Terra binding.
- */
-function hasUnrecoveredCodexQuotaRefusal(accountId: string, quotaScope?: CodexQuotaScope): boolean {
-  if (carriesQuotaRefusal(getAccountHealth(accountId))) return true;
-  return quotaScope !== undefined && carriesQuotaRefusal(scopedHealthFor(accountId, quotaScope));
-}
-
 function previewReusableAffinityAccount(
   entry: ThreadAffinityEntry | undefined,
   config: OcxConfig,
@@ -952,7 +916,7 @@ export function resolveCodexAccountForThreadDetailed(
     // the account has already told this thread it cannot serve it.
     const quotaRefused = hasUnrecoveredCodexQuotaRefusal(entry.accountId, quotaScope);
     const healthyForSharedAffinity = selectableForSharedState
-      && hasCodexQuotaHeadroom(config, entry.accountId, sharedSelectionOptions, now)
+      && hasCodexSharedStateQuotaHeadroom(config, entry.accountId, quotaScope, sharedSelectionOptions, now)
       && !quotaRefused
       && !failoverReady;
     if (
@@ -1150,7 +1114,7 @@ export function resolveCodexAccountForThreadDetailed(
     sharedSelectionOptions,
   );
   const activeHealthyForSharedSelection = activeSelectableForSharedState
-    && hasCodexQuotaHeadroom(config, active, sharedSelectionOptions, now)
+    && hasCodexSharedStateQuotaHeadroom(config, active, quotaScope, sharedSelectionOptions, now)
     && !shouldFailover(config, active, now);
   if (!isCodexAccountSelectable(config, active, now, quotaScope, selectionOptions)) {
     const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope, selectionOptions);
diff --git a/src/codex/routing/health-store.ts b/src/codex/routing/health-store.ts
index 9c0d922b970..57d4cc1ab30 100644
--- a/src/codex/routing/health-store.ts
+++ b/src/codex/routing/health-store.ts
@@ -350,6 +350,45 @@ export function deleteAccountHealth(accountId: string): void {
   upstreamHealth.delete(accountId);
 }
 
+export function carriesQuotaRefusal(health: CodexUpstreamHealth | undefined): boolean {
+  return health?.lastFailureStatus === 429 || health?.lastFailureStatus === 402;
+}
+
+/**
+ * Has this account refused a request on quota without serving one since?
+ *
+ * Thread affinity is a prompt-cache optimization and every rule around it is a preference:
+ * `autoSwitchThreshold` is a hint that an account is getting busy, and `pool.cacheAffinity`
+ * deliberately raises that bar further. A refusal is not a preference, and once the account has
+ * told THIS thread it cannot serve, the binding has nothing left to optimize.
+ *
+ * The distinction matters because the cooldown a 429 writes is deliberately short. A reset
+ * announcement is advisory — plan quota routinely frees up before the advertised instant — so
+ * {@link CODEX_MAX_RESET_DERIVED_COOLDOWN_MS} caps it at 15 minutes. The five-hour window that
+ * announcement describes is not capped, so an account whose burst window is spent looks
+ * selectable again long before it is. For an unbound request that is correct: going back to find
+ * out is how the pool learns the window moved. For a BOUND thread it is a loop with no exit —
+ * the cooldown lapses, the account still scores lowest on the only window this proxy has a
+ * reading for (its weekly bar, untouched by a burst limit), the thread rebinds, and earns the
+ * identical 429. Cleared affinity does not help: the next request re-derives the same choice.
+ * From the Codex side that reads exactly as reported — a new session rotates normally while an
+ * existing one is locked to an exhausted account until the proxy is restarted, because a restart
+ * is the only thing that drops the binding and the stale health together.
+ *
+ * `lastFailureStatus` is the right evidence because of when it ends: {@link preservedCooldownFields}
+ * strips it from every recovery write, so it survives exactly until the account actually serves a
+ * request again. Nothing here blocks that — selection is untouched, so unbound traffic still probes
+ * the account and the first success releases every thread this refused.
+ *
+ * Scope follows where the refusal was recorded. An account-wide throttle lands in
+ * `upstreamHealth` and releases every lane; a reset-derived refusal lands against one native
+ * quota group, so a spent Spark window still cannot displace the same thread's Terra binding.
+ */
+export function hasUnrecoveredCodexQuotaRefusal(accountId: string, quotaScope?: CodexQuotaScope): boolean {
+  if (carriesQuotaRefusal(getAccountHealth(accountId))) return true;
+  return quotaScope !== undefined && carriesQuotaRefusal(scopedHealthFor(accountId, quotaScope));
+}
+
 export function listScopedHealthEntries(accountId: string): Array<[CodexQuotaScope, CodexUpstreamHealth]> {
   return [...(quotaScopedHealth.get(accountId) ?? [])];
 }
diff --git a/src/codex/routing/selection.ts b/src/codex/routing/selection.ts
index 2720a5eaafc..9ac5538a000 100644
--- a/src/codex/routing/selection.ts
+++ b/src/codex/routing/selection.ts
@@ -22,6 +22,7 @@ import {
   dropSpentCredentialFailure,
   getAccountHealth,
   getCodexQuotaHealthSnapshot,
+  hasUnrecoveredCodexQuotaRefusal,
   isCodexAccountSoftAvoided,
   isCodexQuotaAvoided,
   isIndependentCodexQuotaScope,
@@ -276,6 +277,40 @@ export function isCacheAffinityEnabled(config: OcxConfig): boolean {
   return config.pool?.cacheAffinity !== false;
 }
 
+/**
+ * Whether quota may retire shared state while cache affinity is active.
+ *
+ * A threshold crossing is a hint that an account is getting busy, not evidence it cannot
+ * serve — the same bar {@link mayRebindAffinityForQuota} applies to a live binding. Shared
+ * state held across a model detour gets that exhaustion boundary for the same reason: the
+ * detour is request-scoped, so retiring the binding over a hint pays a cold prefix for
+ * nothing. New/unbound selection still reads {@link hasCodexQuotaHeadroom}; only
+ * preservation of an existing shared selection or thread binding qualifies here. Like the
+ * live-binding rule, the configured threshold plays no role once retention applies: a
+ * genuinely exhausted (>=100%) account releases even with threshold switching disabled,
+ * while the fallback above keeps a disabled threshold's "never drained on quota alone".
+ */
+export function hasCodexSharedStateQuotaHeadroom(
+  config: OcxConfig,
+  accountId: string,
+  quotaScope: CodexQuotaScope | undefined,
+  selectionOptions?: CodexAccountUsabilityOptions,
+  now: number = Date.now(),
+): boolean {
+  if (
+    !isCacheAffinityEnabled(config)
+    || accountPoolStrategyForScope(config, quotaScope) !== "quota"
+  ) {
+    return hasCodexQuotaHeadroom(config, accountId, selectionOptions, now);
+  }
+  const usage = computeCodexUsageScore(
+    getAccountQuota(accountId),
+    getPoolAccountPlanForSelection(config, accountId, selectionOptions),
+    now,
+  );
+  return isUnknownUsage(usage) || usage < 100;
+}
+
 /** Earliest future shared short/weekly reset; missing evidence and ties use usage order. */
 export function pickResetFirstCodexAccount(
   config: OcxConfig,
@@ -726,7 +761,8 @@ export function isHealthySharedCodexSelection(
   selectionOptions: CodexAccountUsabilityOptions | undefined,
 ): boolean {
   return isCodexAccountSelectable(config, accountId, now, quotaScope, selectionOptions)
-    && hasCodexQuotaHeadroom(config, accountId, selectionOptions, now)
+    && hasCodexSharedStateQuotaHeadroom(config, accountId, quotaScope, selectionOptions, now)
+    && !hasUnrecoveredCodexQuotaRefusal(accountId, quotaScope)
     && !shouldFailover(config, accountId, now);
 }
 
diff --git a/src/codex/shim-templates.ts b/src/codex/shim-templates.ts
index 5ed2cb6b4a1..0f5af00d022 100644
--- a/src/codex/shim-templates.ts
+++ b/src/codex/shim-templates.ts
@@ -4,11 +4,29 @@ import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { windowsEnvIndirectBatchValue } from "../lib/win-paths";
 
 const SHIM_MARKER = "opencodex codex autostart shim";
-const UNIX_SHIM_REVISION_MARKER = "opencodex unix codex shim revision 2";
+const UNIX_SHIM_REVISION_MARKER = "opencodex unix codex shim revision 3";
 
 const CODEX_SHIM_REENTRY_EXIT_CODE = 126;
 const CODEX_SHIM_REENTRY_DIAGNOSTIC = "opencodex: saved Codex launcher resolved back to the autostart shim; run ocx codex-shim uninstall and reinstall Codex before enabling codexAutoStart.";
 
+/**
+ * Said once, on stderr, when `ocx ensure` could not bring the proxy up (#5261).
+ *
+ * The shim used to discard both of ensure's streams and ignore its exit status, so a failed
+ * autostart was completely silent: Codex launched against injected routing pointing at a port
+ * nothing was listening on, and every request — sign-in included — failed with no mention of
+ * opencodex anywhere.
+ *
+ * Ensure's own streams stay discarded rather than being let through. Ensure prints progress and
+ * warnings on exit-zero runs too, and a wrapper that leaked those would put noise in front of
+ * every ordinary Codex launch, which is how a diagnostic gets ignored. The exit status is the
+ * signal; this line is the whole message.
+ *
+ * It names `ocx restore` because bringing the proxy back is only half the choice. A user who
+ * cannot sign in needs the way out that does not require the proxy at all.
+ */
+export const CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC = "opencodex: proxy autostart failed; launching Codex anyway. Run 'ocx doctor' for details, or 'ocx restore' to hand Codex back to its own account.";
+
 const CODEX_INTERNAL_COMMANDS = [
   "app-server",
   "archive",
@@ -136,7 +154,9 @@ case "$ocx_subcommand" in
     ;;
   *)
     if [ -z "$OCX_SHIM_BYPASS" ]; then
-      ${BUN_RUNTIME_SOURCE_ENV}=${shQuote(bunRuntimeSource)} ${BUN_RUNTIME_PATH_ENV}=${shQuote(bunPath)} ${shQuote(bunPath)} ${shQuote(cliPath)} ensure >/dev/null 2>&1 || true
+      if ! ${BUN_RUNTIME_SOURCE_ENV}=${shQuote(bunRuntimeSource)} ${BUN_RUNTIME_PATH_ENV}=${shQuote(bunPath)} ${shQuote(bunPath)} ${shQuote(cliPath)} ensure >/dev/null 2>&1; then
+        printf '%s\\n' ${shQuote(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC)} >&2
+      fi
     fi
     ;;
 esac
@@ -197,6 +217,7 @@ setlocal\r
 ${windowsBatchSet(BUN_RUNTIME_SOURCE_ENV, bunRuntimeSource)}\r
 ${windowsBatchSet(BUN_RUNTIME_PATH_ENV, bunPath)}\r
 "%OCX_BUN%" "%OCX_CLI%" ensure >nul 2>nul\r
+if errorlevel 1 echo ${CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC} 1>&2\r
 endlocal\r
 :run_codex\r
 "%OCX_REAL_CODEX%" %*\r
@@ -239,13 +260,18 @@ if (-not $skipEnsure) {
   $priorRuntimePath = $env:${BUN_RUNTIME_PATH_ENV}
   $env:${BUN_RUNTIME_SOURCE_ENV} = ${psString(bunRuntimeSource)}
   $env:${BUN_RUNTIME_PATH_ENV} = ${psString(bunPath)}
-  try { & ${psString(bunPath)} ${psString(cliPath)} ensure *> $null }
+  $ocxEnsureFailed = $false
+  # Caught, not propagated: a throwing ensure used to escape this wrapper and Codex never
+  # launched at all, which is a lockout produced by the autostart helper itself (#5261).
+  try { & ${psString(bunPath)} ${psString(cliPath)} ensure *> $null; if ($LASTEXITCODE -ne 0) { $ocxEnsureFailed = $true } }
+  catch { $ocxEnsureFailed = $true }
   finally {
     if ($null -eq $priorRuntimeSource) { Remove-Item Env:\\${BUN_RUNTIME_SOURCE_ENV} -ErrorAction SilentlyContinue }
     else { $env:${BUN_RUNTIME_SOURCE_ENV} = $priorRuntimeSource }
     if ($null -eq $priorRuntimePath) { Remove-Item Env:\\${BUN_RUNTIME_PATH_ENV} -ErrorAction SilentlyContinue }
     else { $env:${BUN_RUNTIME_PATH_ENV} = $priorRuntimePath }
   }
+  if ($ocxEnsureFailed) { [Console]::Error.WriteLine(${psString(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC)}) }
 }
 & ${psString(realCodexPath)} @args
 $codexExitCode = $LASTEXITCODE
diff --git a/src/companion/settings.ts b/src/companion/settings.ts
new file mode 100644
index 00000000000..c838285b6fe
--- /dev/null
+++ b/src/companion/settings.ts
@@ -0,0 +1,131 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config/paths";
+import {
+  TIMELINE_HOURS,
+  type TimelineAggregation,
+  type TimelineGrouping,
+  type TimelineMetric,
+} from "../usage/timeline";
+
+export interface CompanionSettings {
+  menuBarMetric: "requests" | "tokens" | "cost" | "quota" | "none";
+  menuBarTemplate: string | null;
+  showToday: boolean;
+  showChart: boolean;
+  showModels: boolean;
+  showCost: boolean;
+  showAccounts: boolean;
+  chartHours: typeof TIMELINE_HOURS[number];
+  bucketMinutes: number;
+  chartStyle: "line" | "stackedBar";
+  tokenMetric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  chartGrouping: TimelineGrouping;
+  models: string[] | null;
+  hiddenProviders: string[];
+}
+
+export const DEFAULT_COMPANION_SETTINGS: CompanionSettings = {
+  menuBarMetric: "tokens",
+  menuBarTemplate: null,
+  showToday: true,
+  showChart: true,
+  showModels: true,
+  showCost: true,
+  showAccounts: true,
+  chartHours: 24,
+  bucketMinutes: 60,
+  chartStyle: "line",
+  tokenMetric: "total",
+  aggregation: "sum",
+  chartGrouping: "model",
+  models: null,
+  hiddenProviders: [],
+};
+
+const TEMPLATE_FIELDS = new Set(["requests", "totalTokens", "inputTokens", "outputTokens", "costUsd", "quotaPercent"]);
+const MENU_BAR_METRICS = new Set(["requests", "tokens", "cost", "quota", "none"]);
+const CHART_STYLES = new Set(["line", "stackedBar"]);
+const TIMELINE_METRICS = new Set(["total", "input", "output", "cached"]);
+const AGGREGATIONS = new Set(["sum", "average", "max"]);
+const GROUPINGS = new Set(["model", "modelAccount"]);
+const SETTINGS_KEYS = Object.keys(DEFAULT_COMPANION_SETTINGS) as (keyof CompanionSettings)[];
+
+export function companionSettingsPath(): string {
+  return join(getConfigDir(), "companion.json");
+}
+
+function invalid(message: string): { error: string } {
+  return { error: message };
+}
+
+function validModels(value: unknown, key: string): value is string[] | null {
+  return value === null
+    || (Array.isArray(value)
+      && value.length <= 100
+      && value.every(model => typeof model === "string" && /^[^/\s]+\/[^/\s]+$/.test(model)));
+}
+
+function validateValue(key: keyof CompanionSettings, value: unknown): string | null {
+  if (key === "menuBarMetric") return typeof value === "string" && MENU_BAR_METRICS.has(value) ? null : "menuBarMetric is invalid";
+  if (key === "menuBarTemplate") {
+    if (value === null) return null;
+    if (typeof value !== "string" || value.length > 200) return "menuBarTemplate must be null or at most 200 characters";
+    for (const match of value.matchAll(/\{([^{}]+)\}/g)) {
+      if (!TEMPLATE_FIELDS.has(match[1]!)) return `menuBarTemplate contains unknown placeholder: ${match[1]}`;
+    }
+    return null;
+  }
+  if (["showToday", "showChart", "showModels", "showCost", "showAccounts"].includes(key)) {
+    return typeof value === "boolean" ? null : `${key} must be a boolean`;
+  }
+  if (key === "chartHours") return TIMELINE_HOURS.includes(value as typeof TIMELINE_HOURS[number]) ? null : "chartHours is invalid";
+  if (key === "bucketMinutes") return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 1440 ? null : "bucketMinutes must be an integer from 1 through 1440";
+  if (key === "chartStyle") return typeof value === "string" && CHART_STYLES.has(value) ? null : "chartStyle is invalid";
+  if (key === "tokenMetric") return typeof value === "string" && TIMELINE_METRICS.has(value) ? null : "tokenMetric is invalid";
+  if (key === "aggregation") return typeof value === "string" && AGGREGATIONS.has(value) ? null : "aggregation is invalid";
+  if (key === "chartGrouping") return typeof value === "string" && GROUPINGS.has(value) ? null : "chartGrouping is invalid";
+  if (key === "models") return validModels(value, key) ? null : "models must be null or at most 100 provider/model identifiers";
+  if (key === "hiddenProviders") return Array.isArray(value) && value.length <= 100 && value.every(item => typeof item === "string" && item.length > 0 && !/\s/.test(item))
+    ? null : "hiddenProviders must contain at most 100 provider names";
+  return `${key} is unsupported`;
+}
+
+export function applyCompanionSettingsPatch(
+  current: CompanionSettings,
+  patch: unknown,
+): CompanionSettings | { error: string } {
+  if (!patch || typeof patch !== "object" || Array.isArray(patch)) return invalid("settings must be an object");
+  const values = patch as Record<string, unknown>;
+  for (const key of Object.keys(values)) {
+    if (!SETTINGS_KEYS.includes(key as keyof CompanionSettings)) return invalid(`unknown settings key: ${key}`);
+    const error = validateValue(key as keyof CompanionSettings, values[key]);
+    if (error) return invalid(error);
+  }
+  return { ...current, ...values } as CompanionSettings;
+}
+
+export function loadCompanionSettings(): { settings: CompanionSettings; updatedAt: number | null; corrupt?: true } {
+  const path = companionSettingsPath();
+  if (!existsSync(path)) return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    const settings = applyCompanionSettingsPatch(DEFAULT_COMPANION_SETTINGS, parsed);
+    if ("error" in settings) return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null, corrupt: true };
+    return { settings, updatedAt: statSync(path).mtimeMs };
+  } catch {
+    return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null, corrupt: true };
+  }
+}
+
+export function saveCompanionSettings(settings: CompanionSettings): void {
+  const path = companionSettingsPath();
+  const dir = getConfigDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(temp, 0o600);
+  renameSync(temp, path);
+  chmodSync(path, 0o600);
+}
diff --git a/src/config.ts b/src/config.ts
index 9788f252144..0c63a168bad 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -110,7 +110,7 @@ export {
   sanitizeModelCostsForDisplay,
   modelPreferHostedToolsConfigError,
 } from "./config/schema/leaf-validators";
-export { hardenExistingSecret, retryOn429PolicyConfigError } from "./config/load-degrade";
+export { hardenExistingSecret, retryOn429PolicyConfigError, retryOnResetPolicyConfigError } from "./config/load-degrade";
 export { backupInvalidConfig } from "./config/salvage";
 export type { ConfigDiagnostics, ConfigAdmissionSnapshot } from "./config/diagnostics";
 export {
diff --git a/src/config/atomic-write.ts b/src/config/atomic-write.ts
index 4ad69b1bb9d..2bdb9508e2c 100644
--- a/src/config/atomic-write.ts
+++ b/src/config/atomic-write.ts
@@ -2,6 +2,7 @@ import {
   chmodSync,
   closeSync,
   fchmodSync,
+  fsyncSync,
   fstatSync,
   lstatSync,
   openSync,
@@ -10,7 +11,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { dirname } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import {
@@ -162,6 +163,27 @@ function carryHardenAcrossContentWrite(path: string): void {
   reattributeHardenedSecretPath(path);
 }
 
+/**
+ * Commit the directory entry a rename just wrote.
+ *
+ * Best effort by platform, not by importance: Windows has no directory descriptor to sync and
+ * some filesystems refuse the open, and failing a replacement that already happened would be
+ * worse than reporting it. The throw that matters is the temp's own `fsync`, which runs before
+ * the rename and stops it.
+ */
+function syncParentDirectory(target: string): void {
+  if (process.platform === "win32") return;
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(dirname(target), "r");
+    fsyncSync(descriptor);
+  } catch {
+    /* the rename already landed; a directory that cannot be synced is not a reason to undo it */
+  } finally {
+    if (descriptor !== undefined) { try { closeSync(descriptor); } catch { /* already closed */ } }
+  }
+}
+
 function writePrivateTempFile(
   path: string,
   content: string,
@@ -191,6 +213,40 @@ function writePrivateTempFile(
   carryHardenAcrossContentWrite(path);
 }
 
+/**
+ * The same private temp, filled by a writer that streams into the descriptor.
+ *
+ * For content that must not be held in memory as one string. The identity assertions, the
+ * ownership handshake and the hardening are the same; the difference is that the bytes arrive in
+ * bounded chunks and the descriptor is flushed before it closes.
+ *
+ * The `fsync` is not optional here and its failure is not swallowed. A replacement whose
+ * REPLACEMENT is not on disk can lose the rows it was supposed to retain, so the throw is what
+ * stops the rename from happening at all.
+ */
+function writePrivateTempFileWith(
+  path: string,
+  write: (descriptor: number) => void,
+  timeoutMemoKey: string,
+  onCreated: () => void,
+): void {
+  const descriptor = openSync(path, "wx", 0o600);
+  onCreated();
+  try {
+    if (windowsHardeningApplies()) {
+      hardenSecretPath(path, { required: true, timeoutMemoKey });
+    }
+    if (process.platform !== "win32") fchmodSync(descriptor, 0o600);
+    assertPrivateTempDescriptor(path, descriptor);
+    write(descriptor);
+    assertPrivateTempDescriptor(path, descriptor);
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+  carryHardenAcrossContentWrite(path);
+}
+
 async function writePrivateTempFileAsync(
   path: string,
   content: string,
@@ -215,14 +271,14 @@ async function writePrivateTempFileAsync(
   carryHardenAcrossContentWrite(path);
 }
 
-export function atomicWriteFile(
+function atomicWriteFileToTarget(
   path: string,
-  content: string,
+  content: string | ((descriptor: number) => void),
+  target: string,
   io?: AtomicWriteIO,
   hooks: AtomicWriteHooks = {},
 ): void {
   recordOwnedConfigPath(getConfigDir(), path);
-  const target = resolveWriteTarget(path);
   assertResolvedTargetAllowed(path, target);
   const tmp = `${target}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
   let hardened = false;
@@ -246,13 +302,26 @@ export function atomicWriteFile(
   };
   try {
     if (io) ownsTemp = true;
-    effective.write(tmp, content);
+    // A streaming writer bypasses the string form of `write` and nothing else. Every later
+    // step -- harden, the pre-rename hooks, the rename and the whole residual-cleanup path,
+    // which still scrubs through `effective.write(tmp, "")` -- is shared with the string form.
+    if (typeof content === "function") writePrivateTempFileWith(tmp, content, path, () => { ownsTemp = true; });
+    else effective.write(tmp, content);
     hooks.afterTempWrite?.(tmp, target);
     effective.harden(tmp);
     hardened = true;
     hooks.beforeRename?.(tmp, target);
     hooks.validateBeforeRename?.(target);
     effective.rename(tmp, target);
+    // The rename is only as durable as the directory entry recording it. Fsyncing the temp's
+    // CONTENT and then losing the entry in a power cut leaves the old file in place, or the
+    // directory in an indeterminate state, while the caller was told the replacement landed.
+    //
+    // Only the streaming form does this. It is the one that makes a durability claim -- a
+    // replacement is not an append, and losing it can lose the rows it was meant to keep -- and
+    // adding a directory sync to the string form would charge every config write for a promise
+    // its callers have never been given.
+    if (typeof content === "function") syncParentDirectory(target);
     forgetEphemeralSecretPath(tmp);
   } catch (cause) {
     if (!ownsTemp) throw cause;
@@ -287,6 +356,49 @@ export function atomicWriteFile(
   }
 }
 
+export function atomicWriteFile(
+  path: string,
+  content: string,
+  io?: AtomicWriteIO,
+  hooks: AtomicWriteHooks = {},
+): void {
+  atomicWriteFileToTarget(path, content, resolveWriteTarget(path), io, hooks);
+}
+
+/**
+ * Atomically replace a file with bytes produced straight into the temporary descriptor.
+ *
+ * Same publication contract as {@link atomicWriteFile}: an exclusively created private temp, the
+ * identity assertions around the write, `hooks.validateBeforeRename` immediately before the
+ * rename, the platform-aware replace, and the residual cleanup on any failure. A custom
+ * {@link AtomicWriteIO} is not accepted, because the point of this form is that the default
+ * writer owns the descriptor.
+ */
+export function atomicWriteFileStreamed(
+  path: string,
+  write: (descriptor: number) => void,
+  hooks: AtomicWriteHooks = {},
+): void {
+  atomicWriteFileToTarget(path, write, resolveWriteTarget(path), undefined, hooks);
+}
+
+/**
+ * Atomically replace the named directory entry without resolving a symlink at
+ * that entry. This is for files in directories writable by another process:
+ * a raced symlink is replaced, never followed to a more privileged target.
+ */
+export function atomicWriteFileNoFollow(
+  path: string,
+  content: string,
+  io?: AtomicWriteIO,
+  hooks: AtomicWriteHooks = {},
+): void {
+  // Only the final entry is no-follow: the parent still resolves, because an
+  // OS alias above the configured root (a home junction, /tmp) is legitimate
+  // and Windows cannot exclusive-create a temp through a junction.
+  atomicWriteFileToTarget(path, content, join(resolveWriteTarget(dirname(path)), basename(path)), io, hooks);
+}
+
 export interface AtomicWriteAsyncIO {
   write: (path: string, content: string) => void | Promise<void>;
   harden: (path: string) => void | Promise<void>;
diff --git a/src/config/load-degrade.ts b/src/config/load-degrade.ts
index 1787ad109a6..daf16aba298 100644
--- a/src/config/load-degrade.ts
+++ b/src/config/load-degrade.ts
@@ -32,6 +32,7 @@ import {
   quotaResetNotifySchema,
   remoteGuiConfigSchema,
   retryOn429PolicySchema,
+  retryOnResetPolicySchema,
   runtimeRoleSchema,
   spendSchema,
 } from "./schema/leaf-validators";
@@ -195,18 +196,44 @@ export function sanitizeRetryOn429ForLoad(parsed: unknown): void {
  * redacted (a malformed write can place a secret in a property name).
  */
 export function retryOn429PolicyConfigError(policy: unknown): string | null {
+  return strictPolicyConfigError("retryOn429", retryOn429PolicySchema, policy);
+}
+
+/**
+ * Management write-boundary validation for `retryOnReset`, with the same fail-closed contract
+ * as `retryOn429PolicyConfigError`: the load-time schema degrades a malformed block to
+ * "absent", so this is the one place a bad value is refused instead of silently dropped.
+ */
+export function retryOnResetPolicyConfigError(policy: unknown): string | null {
+  return strictPolicyConfigError("retryOnReset", retryOnResetPolicySchema, policy);
+}
+
+/**
+ * The shared body of both. Written once because the two differ only in the field name they
+ * report, and a second hand-copied formatter is a second place for the redaction to be
+ * forgotten.
+ */
+function strictPolicyConfigError(
+  field: string,
+  schema: {
+    safeParse: (value: unknown) => { success: true } | {
+      success: false;
+      error: { issues: Array<{ code: string; message: string; path: PropertyKey[]; keys?: string[] }> };
+    };
+  },
+  policy: unknown,
+): string | null {
   if (policy === undefined) return null;
-  const result = retryOn429PolicySchema.safeParse(policy);
+  const result = schema.safeParse(policy);
   if (result.success) return null;
   const first = result.error.issues[0];
-  if (!first) return "retryOn429 is invalid";
-  if (first.code === "unrecognized_keys") {
+  if (!first) return `${field} is invalid`;
+  if (first.code === "unrecognized_keys" && first.keys) {
     const names = first.keys.map(key => JSON.stringify(redactSecretString(key))).join(", ");
-    return `retryOn429 has unrecognized field${first.keys.length > 1 ? "s" : ""}: ${names}`;
+    return `${field} has unrecognized field${first.keys.length > 1 ? "s" : ""}: ${names}`;
   }
-  if (first.path.length === 0) return `retryOn429 is invalid (${first.message})`;
-  const field = String(first.path[first.path.length - 1]);
-  return `retryOn429.${field} is invalid (${first.message})`;
+  if (first.path.length === 0) return `${field} is invalid (${first.message})`;
+  return `${field}.${String(first.path[first.path.length - 1])} is invalid (${first.message})`;
 }
 
 export function sanitizeCapabilityDeclarationsForLoad(parsed: unknown): void {
diff --git a/src/config/process-state.ts b/src/config/process-state.ts
index b42a022894c..79d40a0ffc3 100644
--- a/src/config/process-state.ts
+++ b/src/config/process-state.ts
@@ -127,7 +127,7 @@ export function isOcxCommandLine(commandLine: string): boolean {
     || normalized.includes("src/cli/index.ts")
     || normalized.includes("@bitkyc08/opencodex")
     || /@bitkyc08\/\.opencodex-/.test(normalized)
-    || /(?:^|[\s/"'])(?:ocx|opencodex)(?:\.cmd)?(?:$|[\s"'])/.test(normalized);
+    || /(?:^|[\s/"'])(?:ocx|opencodex)(?:\.cmd|\.exe)?(?:$|[\s"'])/.test(normalized);
 }
 
 export function isOcxStartCommandLine(commandLine: string): boolean {
diff --git a/src/config/schema/config-schema.ts b/src/config/schema/config-schema.ts
index 18a45a68412..6d1e936670c 100644
--- a/src/config/schema/config-schema.ts
+++ b/src/config/schema/config-schema.ts
@@ -46,6 +46,7 @@ import {
   MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET,
 } from "../../codex/account-namespace-match";
 import { UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD } from "../../codex/upstream-host-health";
+import { MIN_USAGE_LEDGER_MAX_BYTES } from "../../usage/retention-contract";
 import { COMBO_NAMESPACE, comboConfigIssues } from "../../combos/types";
 import { routingProfileIssues } from "../../routing/profile";
 import { POLICY_NAMESPACE } from "../../routing/profile-namespace";
@@ -82,6 +83,14 @@ export const configSchema = z.object({
   managementUsageMaxReadBytes: z.number().int().positive().default(64 * 1024 * 1024).describe(
     "Deprecated compatibility limit for bounded legacy usage readers; GET /api/usage always aggregates the complete ledger",
   ),
+  // Opt-in ledger ceiling. A hand edit below the floor, or a non-safe integer, disables only
+  // this limit rather than failing the config: refusing to start because history retention was
+  // mistyped would be a worse outcome than not trimming history.
+  usageLedgerMaxBytes: z.number().int()
+    .min(MIN_USAGE_LEDGER_MAX_BYTES)
+    .max(Number.MAX_SAFE_INTEGER)
+    .optional()
+    .catch(undefined),
   // Invalid hand edits disable only this opt-in circuit. Live writes remain strict.
   upstreamHostCircuitThreshold: z.number().int()
     .min(0)
@@ -261,7 +270,24 @@ export const configSchema = z.object({
   if (claudeCode !== undefined && (!claudeCode || typeof claudeCode !== "object" || Array.isArray(claudeCode))) {
     ctx.addIssue({ code: "custom", path: ["claudeCode"], message: "claudeCode must be an object" });
   } else if (claudeCode) {
-    const claude = claudeCode as { desktopProfile?: unknown };
+    const claude = claudeCode as { desktopProfile?: unknown; desktopMode?: unknown; intercept?: unknown };
+    if (claude.desktopMode !== undefined && claude.desktopMode !== "first-party" && claude.desktopMode !== "gateway") {
+      ctx.addIssue({ code: "custom", path: ["claudeCode", "desktopMode"], message: "desktopMode must be \"first-party\" or \"gateway\"" });
+    }
+    if (claude.intercept !== undefined) {
+      const intercept = claude.intercept;
+      if (!intercept || typeof intercept !== "object" || Array.isArray(intercept)) {
+        ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept"], message: "intercept must be an object" });
+      } else {
+        const { enabled, port } = intercept as { enabled?: unknown; port?: unknown };
+        if (enabled !== undefined && typeof enabled !== "boolean") {
+          ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "enabled"], message: "intercept.enabled must be a boolean" });
+        }
+        if (port !== undefined && (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535)) {
+          ctx.addIssue({ code: "custom", path: ["claudeCode", "intercept", "port"], message: "intercept.port must be an integer between 1 and 65535" });
+        }
+      }
+    }
     if (claude.desktopProfile !== undefined) {
       try {
         parseDesktopProfile(claude.desktopProfile);
diff --git a/src/config/schema/leaf-validators.ts b/src/config/schema/leaf-validators.ts
index f3160644b08..0210a9d0c3d 100644
--- a/src/config/schema/leaf-validators.ts
+++ b/src/config/schema/leaf-validators.ts
@@ -17,6 +17,7 @@ import { isCodexAccountPriorityKey } from "../../codex/account-priority";
 import { parseAccountPriority } from "../../codex/pool-rotation";
 import { credentialGroupIssues } from "../../routing/identity-domains";
 import { providerDestinationConfigError } from "../../lib/destination-policy";
+import { providerEgressConfigError } from "../../lib/provider-egress";
 import { redactSecretString } from "../../lib/redact";
 import {
   MODEL_ADAPTER_OVERRIDE_ALLOWED,
@@ -80,6 +81,17 @@ const transientRetryOn5xxPolicySchema = z.object({
   attempts: z.number().int().min(1).max(10).optional(),
 }).strict();
 
+/**
+ * `retryOnReset` accepts only these keys. `replacements` counts DUPLICATE inferences the
+ * operator is willing to risk for one logical request, so the ceiling is two rather than a
+ * send budget: this is the one send the proxy otherwise refuses outright, and a third of them
+ * says the connection, not the retry policy, is the problem.
+ */
+export const retryOnResetPolicySchema = z.object({
+  enabled: z.boolean().optional(),
+  replacements: z.number().int().min(1).max(2).optional(),
+}).strict();
+
 const requestPacingRuleSchema = z.object({
   // Keep the RPM-derived timer within the same one-hour bound as minIntervalMs.
   requestsPerMinute: z.number().min(1 / 60).max(60_000).optional(),
@@ -221,6 +233,25 @@ const modelCapabilitiesSchema = z.unknown().superRefine((value, ctx) => {
   if (error) ctx.addIssue({ code: "custom", message: error });
 }).transform(value => mergeModelCapabilities(undefined, value));
 
+/**
+ * Per-provider egress fields, validated by the resolver the transports themselves use.
+ *
+ * Calling `providerEgressConfigError` rather than restating the accepted forms keeps one
+ * definition of a usable value: a proxy the config loader admits is one the transport can
+ * carry, and a value rejected here is rejected at request time for the identical reason.
+ * Each field is checked on its own because neither depends on the other's value to be
+ * well-formed; how they combine is decided per request against the destination.
+ */
+const providerProxySchema = z.unknown().superRefine((value, ctx) => {
+  const error = providerEgressConfigError({ proxy: value as string | null | undefined });
+  if (error) ctx.addIssue({ code: "custom", message: error });
+}).transform(value => value as string | null | undefined);
+
+const providerNoProxySchema = z.unknown().superRefine((value, ctx) => {
+  const error = providerEgressConfigError({ noProxy: value as string | string[] | undefined });
+  if (error) ctx.addIssue({ code: "custom", message: error });
+}).transform(value => value as string | string[] | undefined);
+
 /**
  * Zod schema for one provider entry: known fields are validated strictly while unknown
  * fields pass through (preserved for runtime extensions).
@@ -258,6 +289,7 @@ export const providerConfigSchema = z.object({
   requiresAdjacentResponsesToolResults: z.boolean().optional(),
   requiresPairedResponsesToolResults: z.boolean().optional(),
   annotateEmptyToolOutputs: z.boolean().optional(),
+  foldDeveloperRoleToSystem: z.boolean().optional(),
   fastWire: fastWireSchema.nullable().optional(),
   supportsServiceTier: z.boolean().optional(),
   modelSupportsServiceTier: z.record(z.string().min(1), z.boolean()).optional(),
@@ -268,6 +300,10 @@ export const providerConfigSchema = z.object({
   decodesNativeCompactionBlobs: z.boolean().optional(),
   allowEncryptedV2AgentTasks: z.boolean().optional(),
   allowPrivateNetwork: z.boolean().optional(),
+  // Per-provider egress (#2894): absent inherits the global proxy decision, "direct"/null
+  // refuses it, and an http(s) or socks5 URL replaces it for this provider only.
+  proxy: providerProxySchema.optional(),
+  noProxy: providerNoProxySchema.optional(),
   // The management API accepts `null` as "clear this", so a config written before the POST
   // canonicalization below can hold one on disk. Rejecting it here would send the operator
   // through invalid-config recovery for a value the API told them was fine.
@@ -306,6 +342,10 @@ export const providerConfigSchema = z.object({
     .optional(),
   retryOn429: retryOn429PolicySchema.optional(),
   transientRetryOn5xx: transientRetryOn5xxPolicySchema.optional(),
+  // Degrades to "absent" like `webSearchBridge`: a malformed hand edit of an opt-in feature
+  // that is off by default must not send the operator through invalid-config recovery. The
+  // management write boundary still rejects it loudly (`retryOnResetPolicyConfigError`).
+  retryOnReset: retryOnResetPolicySchema.optional().catch(undefined),
   codexAccountMode: z.enum(["pool", "direct"]).optional(),
   // Validated rather than passed through: this schema ends in `.passthrough()`, so an
   // undeclared key survives verbatim. A misspelled `codexToolMode` therefore used to be
@@ -649,6 +689,13 @@ export const apiKeyEntrySchema = z.object({
   createdAt: z.string().catch(""),
   // A damaged overlap record must never discard the still-authoritative key.
   pendingRotation: pendingApiKeyRotationSchema.optional().catch(undefined),
+  // Deliberately NOT `.catch`ed, unlike every field above. Degrading a damaged
+  // scope to `undefined` would silently widen the key to the whole catalog,
+  // which is the one direction a permission field must never fail. Letting the
+  // record fail instead drops the key, so a corrupted scope stops that client
+  // rather than promoting it.
+  allowedProviders: z.array(z.string().trim().min(1).max(256)).optional(),
+  allowedModels: z.array(z.string().trim().min(1).max(256)).optional(),
 }).passthrough();
 
 /**
diff --git a/src/integrations/config-io.ts b/src/integrations/config-io.ts
index 8a1e1480ec8..df5337a121e 100644
--- a/src/integrations/config-io.ts
+++ b/src/integrations/config-io.ts
@@ -10,7 +10,7 @@
 import { lstatSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import type { ConfigFormat } from "../clients/config-export";
 import { MAX_JSON_NESTING } from "./serialize";
-import { atomicWriteFile } from "../config";
+import { atomicWriteFileNoFollow, isMissingPathError } from "../config/atomic-write";
 import type { JournalEntry } from "./journal";
 import type { OwnershipRecord } from "./ownership";
 import type { IntegrationClientId } from "./registry";
@@ -192,6 +192,15 @@ export type ReadResult =
 
 export type StatKind = "file" | "dir" | "other" | "missing" | "failed";
 
+function lstatKind(path: string): StatKind {
+  try {
+    const stats = lstatSync(path);
+    return stats.isFile() ? "file" : stats.isDirectory() ? "dir" : "other";
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "failed";
+  }
+}
+
 export interface IntegrationIO {
   /**
    * ONLY a missing file yields `missing`. Every other failure (EACCES, EPERM,
@@ -234,6 +243,18 @@ export type TargetState =
  * an unreadable config gets clobbered.
  */
 export function loadTarget(io: IntegrationIO, configPath: string): TargetState {
+  // Managed client paths are a lower-trust boundary. Never inspect through a
+  // final symlink that can be retargeted between this read and the eventual
+  // write: when a no-follow probe exists, the named directory entry itself must
+  // be a regular file or absent. `missing` stays legal so a virtual pair probe
+  // (such as Cline's pair-aware statKind) can still report one absent member.
+  const named = io.lstatKind?.(configPath);
+  // A failed probe is uncertainty, not evidence about the entry's shape: it
+  // keeps the read-failed classification the follow-probe would have produced.
+  if (named === "failed") return { ok: false, why: "read-failed" };
+  if (named !== undefined && named !== "file" && named !== "missing") {
+    return { ok: false, why: "not-regular-file" };
+  }
   const kind = io.statKind(configPath);
   if (kind === "missing") return { ok: true, before: null };
   if (kind === "failed") return { ok: false, why: "read-failed" };
@@ -252,14 +273,7 @@ export function loadTarget(io: IntegrationIO, configPath: string): TargetState {
  */
 export function fileIO(): Omit<IntegrationIO, "appendJournal" | "putRecord" | "dropRecord"> {
   return {
-    lstatKind: path => {
-      try {
-        const stats = lstatSync(path);
-        return stats.isFile() ? "file" : stats.isDirectory() ? "dir" : "other";
-      } catch (error) {
-        return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "failed";
-      }
-    },
+    lstatKind,
     readText: path => {
       try {
         return { kind: "text", text: readFileSync(path, "utf8") };
@@ -277,8 +291,28 @@ export function fileIO(): Omit<IntegrationIO, "appendJournal" | "putRecord" | "d
       }
     },
     writeText: (path, text) => {
+      const kind = lstatKind(path);
+      if (kind !== "file" && kind !== "missing") {
+        throw new Error(`refusing unsafe integration write target: ${path}`);
+      }
       assertIntegrationWriteOwnership(path);
-      atomicWriteFile(path, text);
+      atomicWriteFileNoFollow(path, text, undefined, {
+        // The pre-check above rejects a symlink already in place; this one runs
+        // inside the atomic write immediately before the rename, so a link
+        // exchanged after validation is refused rather than followed. Even a
+        // swap past this point can only replace the named entry, never redirect
+        // the write through it.
+        validateBeforeRename: target => {
+          try {
+            if (lstatSync(target).isSymbolicLink()) {
+              throw new Error(`refusing to replace symbolic-link integration target: ${target}`);
+            }
+          } catch (error) {
+            if (isMissingPathError(error)) return;
+            throw error;
+          }
+        },
+      });
     },
     removeFile: path => rmSync(path, { force: true }),
     mkdirp: path => mkdirSync(path, { recursive: true, mode: 0o700 }),
diff --git a/src/integrations/merge.ts b/src/integrations/merge.ts
index ab2099b4242..46c1bd3802b 100644
--- a/src/integrations/merge.ts
+++ b/src/integrations/merge.ts
@@ -9,7 +9,7 @@
  *
  * Design of record: devlog/_fin/260802_client_toggle_api/031_wp3_writer_impl.md.
  */
-import type { ManagedContribution } from "../clients/config-export";
+import type { ManagedContribution } from "../clients/config-export/contracts";
 
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -22,20 +22,87 @@ function clone<T>(value: T): T {
 
 /**
  * `[field=value]` addresses the ONE element of a sequence whose `field` equals
- * `value`. Raycast keeps its providers as a YAML list, so the element is the
+ * `value`, and `[v2:field=value,field=value]` the one whose every named field
+ * matches. Raycast keeps its providers as a YAML list, so the element is the
  * smallest thing we can own there; an index would move under us the moment
  * the user reordered their own entries. Any other segment is a plain key.
+ *
+ * A conjunction exists because one field is not always the identity. ZCode
+ * keys a model rule in its provider store by the PAIR `(providerId, modelId)`,
+ * so a `[modelId=…]` selector alone would match another provider's rule for the
+ * same model and then replace it, in a file holding every provider the user
+ * has. Addressing an element by less than what identifies it is the same
+ * defect as addressing it by index.
+ *
+ * The single-criterion spelling keeps its original grammar, where the value may
+ * itself contain commas and equals signs. A conjunction uses an explicit v2
+ * marker, so no path already written into an ownership record on disk changes
+ * meaning. Once the marker is present the whole segment must be valid; falling
+ * back to a key or v1 selector would recreate the silent reselection hazard.
  */
 const ARRAY_SELECTOR = /^\[([A-Za-z_][A-Za-z0-9_]*)=([^\]]+)\]$/u;
+const SELECTOR_FIELD = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const SELECTOR_CONJUNCTION_PREFIX = "[v2:";
+
+/** One `field=value` equality a selector requires of the element it names. */
+export interface SelectorCriterion {
+  field: string;
+  value: string;
+}
 
 export type PathSegment =
   | { kind: "key"; key: string }
-  | { kind: "select"; field: string; value: string };
+  | { kind: "select"; criteria: readonly SelectorCriterion[] };
+
+/** A reserved v2 selector marker was present, but its complete grammar was not. */
+export class InvalidSelectorError extends Error {
+  constructor() {
+    super("invalid versioned selector");
+    this.name = "InvalidSelectorError";
+  }
+}
+
+function validConjunctionCriteria(criteria: readonly SelectorCriterion[]): boolean {
+  return criteria.length >= 2 && criteria.every(criterion => (
+    SELECTOR_FIELD.test(criterion.field)
+    && criterion.value.length > 0
+    && !criterion.value.includes(",")
+    && !criterion.value.includes("]")
+  ));
+}
+
+/** Spell a multi-field selector without colliding with persisted v1 paths. */
+export function formatSelectorConjunction(criteria: readonly SelectorCriterion[]): string | null {
+  if (!validConjunctionCriteria(criteria)) return null;
+  return `${SELECTOR_CONJUNCTION_PREFIX}${criteria
+    .map(criterion => `${criterion.field}=${criterion.value}`)
+    .join(",")}]`;
+}
 
 export function parseSegment(raw: string): PathSegment {
+  if (raw.startsWith(SELECTOR_CONJUNCTION_PREFIX)) {
+    if (!raw.endsWith("]")) throw new InvalidSelectorError();
+    const parts = raw.slice(SELECTOR_CONJUNCTION_PREFIX.length, -1).split(",");
+    const criteria = parts.map(part => {
+      const equals = part.indexOf("=");
+      return equals < 0
+        ? { field: "", value: "" }
+        : { field: part.slice(0, equals), value: part.slice(equals + 1) };
+    });
+    if (!validConjunctionCriteria(criteria)) throw new InvalidSelectorError();
+    return {
+      kind: "select",
+      criteria,
+    };
+  }
   const match = ARRAY_SELECTOR.exec(raw);
   if (!match) return { kind: "key", key: raw };
-  return { kind: "select", field: match[1]!, value: match[2]! };
+  return { kind: "select", criteria: [{ field: match[1]!, value: match[2]! }] };
+}
+
+/** The `field=value` list a selector segment spells, for messages and seeding. */
+export function selectorPairs(criteria: readonly SelectorCriterion[]): string {
+  return criteria.map(criterion => `${criterion.field}=${criterion.value}`).join(", ");
 }
 
 /**
@@ -44,19 +111,21 @@ export function parseSegment(raw: string): PathSegment {
  * this to an `unsafe` refusal instead.
  */
 export class AmbiguousSelectorError extends Error {
-  constructor(field: string, value: string) {
-    super(`more than one entry has ${field}=${value}`);
+  constructor(criteria: readonly SelectorCriterion[]) {
+    super(`more than one entry has ${selectorPairs(criteria)}`);
     this.name = "AmbiguousSelectorError";
   }
 }
 
 /** The index of the element a selector names, -1 when none matches. */
-export function selectIndex(items: readonly unknown[], field: string, value: string): number {
+export function selectIndex(items: readonly unknown[], criteria: readonly SelectorCriterion[]): number {
   const matches: number[] = [];
   items.forEach((item, index) => {
-    if (isPlainRecord(item) && item[field] === value) matches.push(index);
+    if (isPlainRecord(item) && criteria.every(criterion => item[criterion.field] === criterion.value)) {
+      matches.push(index);
+    }
   });
-  if (matches.length > 1) throw new AmbiguousSelectorError(field, value);
+  if (matches.length > 1) throw new AmbiguousSelectorError(criteria);
   return matches[0] ?? -1;
 }
 
@@ -64,6 +133,44 @@ function assertNever(segment: never): never {
   throw new Error(`unknown path segment ${JSON.stringify(segment)}`);
 }
 
+/** The element a selector names, or `undefined` when none matches. */
+function selectElement(items: readonly unknown[], segment: PathSegment & { kind: "select" }): unknown {
+  return items[selectIndex(items, segment.criteria)];
+}
+
+/**
+ * Read `path` through the same segment grammar `setPath` writes through.
+ *
+ * It belongs here rather than beside the classifier because the grammar does: a
+ * reader that resolved a selector differently from the writer would report one
+ * element as ours and then rewrite another. `state` re-exports it for the
+ * callers that have always imported it from there.
+ */
+export function readPath(doc: unknown, path: readonly string[]): unknown {
+  let cursor: unknown = doc;
+  // Validate the complete persisted grammar before document shape can short-circuit
+  // the walk. Otherwise an absent early key can hide a malformed later selector,
+  // making an unreadable ownership record look absent and move the operation to a
+  // different file.
+  const segments = path.map(parseSegment);
+  for (const segment of segments) {
+    switch (segment.kind) {
+      case "key":
+        if (!isPlainRecord(cursor)) return undefined;
+        cursor = cursor[segment.key];
+        break;
+      case "select":
+        if (!Array.isArray(cursor)) return undefined;
+        cursor = selectElement(cursor, segment);
+        break;
+      default:
+        return assertNever(segment);
+    }
+    if (cursor === undefined) return undefined;
+  }
+  return cursor;
+}
+
 /**
  * Write `value` at `path`, creating intermediate containers. Returns a new document.
  *
@@ -99,7 +206,7 @@ export function setPath(doc: unknown, path: readonly string[], value: unknown):
       case "select": {
         if (!Array.isArray(read())) write([]);
         const items = read() as unknown[];
-        const found = selectIndex(items, segment.field, segment.value);
+        const found = selectIndex(items, segment.criteria);
         parent = items;
         if (found >= 0) {
           slot = found;
@@ -107,7 +214,7 @@ export function setPath(doc: unknown, path: readonly string[], value: unknown):
           // Seed the element so the selector stays true for whatever a deeper
           // segment writes into it; a last-position select replaces it whole.
           slot = items.length;
-          items.push({ [segment.field]: segment.value });
+          items.push(Object.fromEntries(segment.criteria.map(criterion => [criterion.field, criterion.value])));
         }
         break;
       }
@@ -155,7 +262,7 @@ export function deletePath(
       }
       case "select": {
         if (!Array.isArray(container)) return { doc: root, removed: false };
-        const found = selectIndex(container, segment.field, segment.value);
+        const found = selectIndex(container, segment.criteria);
         if (found < 0) return { doc: root, removed: false };
         slots.push(found);
         chain.push(container[found] as Record<string, unknown> | unknown[]);
@@ -249,7 +356,7 @@ export function createdContainerPaths(
         case "select": {
           // A selector that matches nothing means setPath will push the element.
           next = Array.isArray(cursor)
-            ? cursor[selectIndex(cursor, segment.field, segment.value)]
+            ? cursor[selectIndex(cursor, segment.criteria)]
             : undefined;
           break;
         }
diff --git a/src/integrations/mutation-plan.ts b/src/integrations/mutation-plan.ts
index 20cc91c9f6a..9ab2fac0d82 100644
--- a/src/integrations/mutation-plan.ts
+++ b/src/integrations/mutation-plan.ts
@@ -17,12 +17,23 @@ import { createHash } from "node:crypto";
 import { canonicalContribution, fingerprint, type OwnershipRecord } from "./ownership";
 import { ClientPathError, EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import { OPENCODE_PROVIDER_ID } from "../clients/config-export/constants";
+import {
+  ZCODE_STORE_MODEL_RULES_PATH,
+  ZCODE_STORE_PROVIDER_RULES_PATH,
+} from "../clients/config-export/zcode-store";
 import { createClineIO, ClineTransactionError } from "./cline-io";
 import { parseClineDocument } from "./cline-document";
 import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
-import { INTEGRATION_CLIENTS, isLoopbackOnly, resolveIntegrationPaths, type IntegrationClientId } from "./registry";
+import {
+  INTEGRATION_CLIENTS,
+  isLoopbackOnly,
+  resolveIntegrationPaths,
+  type IntegrationClientId,
+} from "./registry";
+import { declaredIntegrationTarget, resolveIntegrationTarget, type IntegrationTarget } from "./target";
 import { shouldInjectApiAuthHeader } from "../codex/inject";
 import { classifyIntegration, exportContextOf, readPath, type IntegrationState, type StateReason } from "./state";
+import { InvalidSelectorError } from "./merge";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 import type { OcxConfig } from "../types";
 import { matchesOperationResult, type JournalEntry } from "./journal";
@@ -37,6 +48,7 @@ export type RefusalReason =
   | "conflict"
   | "unsafe"
   | "non_loopback"
+  | "superseded_store"
   | "drift_requires_confirm"
   | "snapshot_expired"
   | "write_failed";
@@ -114,7 +126,16 @@ const CLIENT_MANAGED_PATHS = {
   gajae: [["providers", OPENCODE_PROVIDER_ID]],
   dsh: [["llm-pi-ai", "providers", OPENCODE_PROVIDER_ID]],
   mcode: [["custom_provider", OPENCODE_PROVIDER_ID]],
-  zcode: [["provider", OPENCODE_PROVIDER_ID]],
+  zcode: [
+    ["provider", OPENCODE_PROVIDER_ID],
+    /*
+     * The store the current client reads. The model rule carries the model id in
+     * its own selector, so the published segment is the dynamic one: the template
+     * leaves this module, never the observed path.
+     */
+    [...ZCODE_STORE_PROVIDER_RULES_PATH, `[providerId=${OPENCODE_PROVIDER_ID}]`],
+    [...ZCODE_STORE_MODEL_RULES_PATH, DYNAMIC_SEGMENT],
+  ],
   prime: [["providers", OPENCODE_PROVIDER_ID]],
   aside: [["providers", OPENCODE_PROVIDER_ID]],
   raycast: [["providers", `[id=${OPENCODE_PROVIDER_ID}]`]],
@@ -205,6 +226,18 @@ export interface PlanFingerprintInput {
    * plan that did not bind it could be confirmed after the proxy stopped being a legal target.
    */
   readonly admissionBlocked: boolean;
+  /**
+   * Why a write to the target would not reach the client, or null.
+   *
+   * Bound for the same reason `installKind` is: it can flip without touching the
+   * file, the record or the contribution. A client that creates its new store
+   * while a confirmation is outstanding has changed whether the write can reach
+   * it, and a plan that did not bind this would still authorize the write. The
+   * reason travels with the location because both can move on their own: a store
+   * whose schema version changes under an unchanged path is the same class of
+   * flip as a store appearing.
+   */
+  readonly ineffectiveWrite: string | null;
   /** Exact current bytes, or null when the target is missing. Missing and empty are not equal. */
   readonly before: string | null;
   readonly contribution: ManagedContribution | null;
@@ -226,7 +259,7 @@ export interface PlanFingerprintInput {
   };
 }
 
-const PLAN_FINGERPRINT_VERSION = "p1";
+const PLAN_FINGERPRINT_VERSION = "p2";
 
 function digest(value: string): string {
   return createHash("sha256").update(value).digest("hex").slice(0, 32);
@@ -251,6 +284,7 @@ export function planFingerprint(input: PlanFingerprintInput): string {
     input.detectDir,
     input.installKind,
     input.admissionBlocked,
+    input.ineffectiveWrite,
     input.before === null ? "\u0000absent" : fingerprint(input.before),
     input.contribution === null ? null : fingerprint(canonicalContribution(input.contribution)),
     input.record === null ? null : fingerprint(JSON.stringify(input.record)),
@@ -305,6 +339,13 @@ function foreignEditOf(input: PlanInput): IntegrationPlanForeignEdit {
 function applyOutcome(input: PlanInput): PlanOutcome {
   if (input.installKind !== "dir") return deny("not_installed");
   if (input.admissionBlocked) return deny("non_loopback");
+  /*
+   * Before any file state. The document may be perfectly writable and our block
+   * may already be current in it; neither says anything about whether the
+   * client reads it, and reporting a change to a file nobody opens is the
+   * defect this refusal exists for.
+   */
+  if (input.ineffectiveWrite !== null) return deny("superseded_store");
   // Overwrite exists precisely to proceed through a conflict the operator has been shown.
   if (input.classified.state === "conflict" && input.operation !== "overwrite") return deny("conflict");
   if (input.classified.state === "unsafe") return deny("unsafe");
@@ -400,7 +441,20 @@ function changesOf(input: PlanInput): readonly IntegrationPlanChange[] {
      */
     const documentKnown = input.parsed !== PARSE_FAILED;
     for (const [path, fragment] of prior) {
-      const absent = documentKnown && readPath(input.parsed, fragment) === undefined;
+      let absent = false;
+      if (documentKnown) {
+        try {
+          absent = readPath(input.parsed, fragment) === undefined;
+        } catch (error) {
+          /*
+           * Restore eligibility is byte-based and does not parse ownership paths.
+           * A malformed versioned selector therefore makes this ONE descriptive
+           * comparison unknown; it must not make preview execute a different
+           * selector, and it must not hide the backup behind an internal error.
+           */
+          if (!(error instanceof InvalidSelectorError)) throw error;
+        }
+      }
       changes.push({ kind: absent ? "add" : "replace", path });
     }
     for (const fragment of input.record?.fragmentPaths ?? []) {
@@ -514,9 +568,16 @@ export function observeRestore(
     return { failed: observationFailure("unsafe", "unsafe", "that operation cannot be undone") } as const;
   }
   const configPath = entry.configPath;
-  // An undo acts on the path the operation was journaled against. A row recorded for one home must
-  // never be allowed to rewrite a file in another.
-  if (resolved.configPath !== configPath) {
+  /*
+   * An undo acts on the path the operation was journaled against. A row recorded for one home must
+   * never be allowed to rewrite a file in another — but a client may legally have written more than
+   * one file, so the test is whether this client still names that location, not whether it is the
+   * config file. The answer also carries the document shape those bytes are in.
+   */
+  const rowTarget = declaredIntegrationTarget({
+    clientId, configPath, resolvedConfigPath: resolved.configPath, env: input.env, home: input.home,
+  });
+  if (rowTarget === null) {
     return {
       failed: observationFailure("conflict", "conflict", "that operation was recorded for a different location"),
     } as const;
@@ -546,6 +607,7 @@ export function observeRestore(
     failed: undefined,
     clientId,
     configPath,
+    format: rowTarget.format,
     detectDir: resolved.detectDir,
     installKind: io.statKind(resolved.detectDir),
     entry,
@@ -589,6 +651,7 @@ export function previewIntegration(input: IntegrationWriteInput, request: Previe
     installKind: observed.io.statKind(observed.detectDir),
     // Loopback-only clients cannot carry the admission header a non-loopback bind requires.
     admissionBlocked: isLoopbackOnly(observed.clientId) && shouldInjectApiAuthHeader(input.config),
+    ineffectiveWrite: observed.ineffectiveWrite,
     before: observed.before,
     contribution: observed.contribution,
     record: observed.record,
@@ -659,6 +722,13 @@ function previewRestore(input: IntegrationWriteInput, request: PreviewRequest):
     detectDir: observed.detectDir,
     installKind: observed.installKind,
     admissionBlocked: false,
+    /*
+     * Undo puts back bytes this project already wrote to this file. Whether the
+     * client still reads the file does not change whether those bytes may be
+     * restored, and refusing here would strand a user on a state they asked to
+     * leave.
+     */
+    ineffectiveWrite: null,
     before: observed.before,
     contribution: null,
     // Descriptive, never decisive. The record says which places are ours now and the document
@@ -673,7 +743,7 @@ function previewRestore(input: IntegrationWriteInput, request: PreviewRequest):
       ? {}
       : observed.clientId === "cline"
         ? parseClineDocument(observed.before)
-        : parseConfig(observed.before, EXPORT_CLIENTS[observed.clientId].format),
+        : parseConfig(observed.before, observed.format),
     restore: {
       opId: observed.entry.opId,
       entry: observed.entry,
@@ -757,6 +827,8 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
    */
   let configPath: string;
   let detectDir: string;
+  let effective: IntegrationTarget;
+  let stored: OwnershipRecord | null;
   try {
     /*
      * Resolve the PAIR, never one half.
@@ -768,9 +840,26 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
      * verify account 1 was installed and then write account 0's catalog.
      */
     const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
-    configPath = resolved.configPath;
     detectDir = resolved.detectDir;
-    if (clientId === "cline") io = createClineIO(io, configPath, store, effects.recover);
+    if (clientId === "cline") io = createClineIO(io, resolved.configPath, store, effects.recover);
+    /*
+     * A record proves ownership of the file it was written FOR, and it is also
+     * one of the inputs the target is chosen from: a block we already wrote to
+     * the config file keeps this operation on that file, so disable removes what
+     * we wrote from where we wrote it. Matching by path happens after the
+     * target is known, because that is the path it has to match.
+     */
+    stored = store.readRecords()[clientId] ?? null;
+    /*
+     * Inside the same guard as resolution, because this resolver can refuse the
+     * same way: the store is named by a client env var, and a relative one is a
+     * misconfiguration to report rather than an exception to leak through the
+     * collection route.
+     */
+    effective = resolveIntegrationTarget({
+      clientId, configPath: resolved.configPath, io, record: stored, env: input.env, home: input.home,
+    });
+    configPath = effective.configPath;
   } catch (error) {
     if (error instanceof ClineTransactionError) {
       return { failed: { ...observationFailure("unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const;
@@ -781,26 +870,31 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
   // Pruning writes, so only a mutation may perform it. Preview reports the state it finds.
   if (effects.maintenance) store.retryPendingPrunes();
 
-  const target = loadTarget(io, configPath);
-  if (!target.ok) {
+  const loaded = loadTarget(io, configPath);
+  if (!loaded.ok) {
     return {
       failed: observationFailure("unsafe", "unsafe",
-        target.why === "read-failed"
+        loaded.why === "read-failed"
           ? `${configPath} exists but could not be read`
           : `${configPath} is not a regular file`),
     } as const;
   }
-  const before = target.before;
-  const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, exportSpec.format);
+  const before = loaded.before;
+  const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, effective.format);
   if (parsed === PARSE_FAILED) {
     return { failed: observationFailure("unsafe", "unsafe",
       `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
   }
-  const contribution = exportSpec.buildContribution(exportContextOf(input));
+  /*
+   * The shape the TARGET's reader understands, which is not always the
+   * client's config format: a client that moved its providers to another file
+   * reads a different document there, and a write in the config file's shape
+   * would be as unread as a write to the config file itself.
+   */
+  const contribution = effective.buildContribution(exportContextOf(input));
   // A record proves ownership of the file it was written FOR. Matching only by
   // client id let a record for one home authorize a write to another whose
   // bytes happened to hash the same — which deleted a config we never touched.
-  const stored = store.readRecords()[clientId] ?? null;
   const record = stored && stored.clientId === clientId && stored.configPath === configPath
     ? stored
     : null;
@@ -810,6 +904,18 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
   // ownership here and disable would delete fragments it never wrote.
   const classified = classifyIntegration({
     fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId,
+    format: effective.format,
   });
-  return { failed: undefined, store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } as const;
+  return {
+    failed: undefined, store, io, clientId, spec, exportSpec, target: effective, configPath, detectDir,
+    /*
+     * One token for the plan, because the location alone is not the input: a
+     * store whose schema stops being one we recognise changes the answer while
+     * its path stays exactly the same.
+     */
+    ineffectiveWrite: effective.ineffective === null
+      ? null
+      : `${effective.ineffective.why}\u0000${effective.ineffective.store}`,
+    before, parsed, contribution, record, classified,
+  } as const;
 }
diff --git a/src/integrations/registry.ts b/src/integrations/registry.ts
index 41813162074..55d87a60ac4 100644
--- a/src/integrations/registry.ts
+++ b/src/integrations/registry.ts
@@ -43,6 +43,11 @@ import {
   raycastConfigPath,
   zcodeConfigPath,
   zcodeHomeDir,
+  zcodeProviderStorePath,
+  buildZcodeStoreContribution,
+  zcodeStoreSchemaEstablished,
+  type BuildContribution,
+  type ConfigFormat,
   type ExportClientId,
 } from "../clients/config-export";
 
@@ -58,6 +63,28 @@ export interface IntegrationClientSpec {
   configPath: (env?: NodeJS.ProcessEnv, home?: string) => string;
   /** Directory whose existence is the cheap "is it installed?" signal. */
   detectDir: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  /**
+   * The provider store this client reads INSTEAD of `configPath`.
+   *
+   * A client that moves its store between releases usually keeps a one-shot
+   * import from the old location, and that import is exactly what makes the old
+   * write look like it still works: it runs once, on an install that has never
+   * created the new file, and never again. Everything after it lands in a file
+   * the client does not open.
+   *
+   * A declaration carries everything needed to write the store, not only its
+   * location: the text format, the contribution shape its reader understands,
+   * and the predicate that says whether a document on disk is a version whose
+   * shape has been observed. The last one is what keeps this honest — a store
+   * we cannot establish is reported as the reason the write cannot reach the
+   * client, never merged into on a guess.
+   */
+  currentStore?: {
+    path: (env?: NodeJS.ProcessEnv, home?: string) => string;
+    format: ConfigFormat;
+    establishes: (parsed: unknown) => boolean;
+    buildContribution: BuildContribution;
+  };
   /** Patch only this block-map YAML leaf; never re-render the shared file. */
   sourcePreservingYaml?: { path: readonly string[] };
   /** Coordinate the complete mutation through a sibling config lock. */
@@ -231,6 +258,17 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     id: "zcode",
     configPath: (env = process.env, home = homedir()) => zcodeConfigPath(env, home),
     detectDir: (env = process.env, home = homedir()) => zcodeHomeDir(env, home),
+    /*
+     * ZCode 3.14 reads its providers from `v2/provider_config.json` and reaches
+     * `v2/config.json` only through the import that seeded it. Where the new
+     * file exists the import is spent, so our write is read by nobody (#5348).
+     */
+    currentStore: {
+      path: (env = process.env, home = homedir()) => zcodeProviderStorePath(env, home),
+      format: "json",
+      establishes: zcodeStoreSchemaEstablished,
+      buildContribution: buildZcodeStoreContribution,
+    },
   },
   prime: {
     id: "prime",
diff --git a/src/integrations/state.ts b/src/integrations/state.ts
index c1c90961406..0b76efb9af2 100644
--- a/src/integrations/state.ts
+++ b/src/integrations/state.ts
@@ -11,10 +11,18 @@
 import { createClineIO } from "./cline-io";
 import { parseClineDocument } from "./cline-document";
 import { ClientPathError, EXPORT_CLIENTS, opencodeProxyBaseUrl, type ExportModel, type ManagedContribution } from "../clients/config-export";
+import type { ConfigFormat } from "../clients/config-export";
 import type { OcxConfig } from "../types";
 import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import { SNAPSHOT_RETENTION } from "./journal";
-import { AmbiguousSelectorError, parseSegment, selectIndex, type PathSegment } from "./merge";
+import {
+  AmbiguousSelectorError,
+  InvalidSelectorError,
+  parseSegment,
+  readPath,
+  selectIndex,
+  type PathSegment,
+} from "./merge";
 import { canonicalContribution, fingerprint, semanticContribution, type OwnershipRecord } from "./ownership";
 import {
   protectedContributionFingerprint,
@@ -28,6 +36,7 @@ import {
   unresolvedPathHintFor,
   type IntegrationClientId,
 } from "./registry";
+import { resolveIntegrationTarget, type IntegrationTarget } from "./target";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 
 export type IntegrationState = "absent" | "current" | "stale" | "conflict" | "unsafe";
@@ -50,6 +59,21 @@ export interface IntegrationStatus {
   appliedAt?: string;
   lastOpId?: string;
   reason?: StateReason;
+  /**
+   * The store this client reads instead of `configPath`.
+   *
+   * Present only when the integration is NOT writing that store: either our
+   * block is still in the config file, or the store is not a document whose
+   * shape has been observed. Where the store is written, `configPath` names it
+   * and there is nothing to report beside the state.
+   *
+   * Orthogonal to `state`, which answers "what is on disk, and did we put it
+   * there?" — and answers it correctly here: the block can be byte-for-byte
+   * current in a file the client stopped opening. That pair is not a
+   * contradiction, it is the whole of #5348, so the surface that reports
+   * `current` has to be able to report this beside it.
+   */
+  supersededBy?: string;
   /** Snapshot files retained for this client; -1 when they cannot be inspected. */
   snapshotCount: number;
   /** Pruning is behind, so older (possibly credential-bearing) snapshots remain. */
@@ -64,37 +88,14 @@ function assertNever(segment: never): never {
   throw new Error(`unknown path segment ${JSON.stringify(segment)}`);
 }
 
-/** The element a selector names, or `undefined` when none matches. */
-function selectElement(items: readonly unknown[], segment: PathSegment & { kind: "select" }): unknown {
-  return items[selectIndex(items, segment.field, segment.value)];
-}
-
 /**
- * Same segment grammar as `setPath`: a plain key reads through a record, a
- * `[field=value]` selector reads through an array. Because the classifier and
- * the writer share this one function, status and mutation cannot disagree
- * about which element is ours.
+ * The path reader lives with the path grammar, in `merge`, and is re-exported
+ * here because the classifier was its original home and every caller imports
+ * it from this module. One implementation is the point: a reader that resolved
+ * a selector differently from the writer would report one element as ours and
+ * then rewrite another.
  */
-export function readPath(doc: unknown, path: readonly string[]): unknown {
-  let cursor: unknown = doc;
-  for (const raw of path) {
-    const segment = parseSegment(raw);
-    switch (segment.kind) {
-      case "key":
-        if (!isPlainRecord(cursor)) return undefined;
-        cursor = cursor[segment.key];
-        break;
-      case "select":
-        if (!Array.isArray(cursor)) return undefined;
-        cursor = selectElement(cursor, segment);
-        break;
-      default:
-        return assertNever(segment);
-    }
-    if (cursor === undefined) return undefined;
-  }
-  return cursor;
-}
+export { readPath };
 
 /** Does the document carry any fragment we would write? */
 export function hasOurFragments(doc: unknown, contribution: ManagedContribution): boolean {
@@ -136,7 +137,7 @@ export function blockedContainerPath(
       case "key":
         return (value as Record<string, unknown>)[segment.key];
       case "select":
-        return selectElement(value as readonly unknown[], segment);
+        return (value as readonly unknown[])[selectIndex(value as readonly unknown[], segment.criteria)];
       default:
         return assertNever(segment);
     }
@@ -285,6 +286,14 @@ export function classifyIntegration(input: {
    */
   configPath?: string;
   clientId?: IntegrationClientId;
+  /**
+   * Text format of the file being classified, which is not always the client's
+   * config format: a client that moved its providers keeps a second document
+   * whose format is declared with the store. Only the comment-capability of the
+   * format is read here, and reading the wrong one would decide a sibling edit
+   * the wrong way.
+   */
+  format?: ConfigFormat;
 }): { state: IntegrationState; reason?: StateReason } {
   if (input.fileText !== null && !input.fileIsRegular) {
     return { state: "unsafe", reason: "not-regular-file" };
@@ -310,8 +319,13 @@ export function classifyIntegration(input: {
       }
     }
   } catch (error) {
-    if (!(error instanceof AmbiguousSelectorError)) throw error;
-    return { state: "unsafe", reason: "ambiguous-selector" };
+    if (error instanceof AmbiguousSelectorError) {
+      return { state: "unsafe", reason: "ambiguous-selector" };
+    }
+    if (error instanceof InvalidSelectorError) {
+      return { state: "unsafe", reason: "unparseable" };
+    }
+    throw error;
   }
   if (!hasOurFragments(input.parsed, input.contribution)) return { state: "absent" };
 
@@ -393,7 +407,7 @@ export function classifyIntegration(input: {
      * stands and re-owns the file. This also lets disable proceed on a
      * drifted file — removal still touches only the recorded fragment paths.
      */
-    if (EXPORT_CLIENTS[clientId].format !== "json") {
+    if ((input.format ?? EXPORT_CLIENTS[clientId].format) !== "json") {
       return { state: "conflict", reason: "foreign-edit" };
     }
     return { state: "stale" };
@@ -491,7 +505,6 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   retryPendingPrunesOnce(store);
   let io = input.io ?? store.io();
   const spec = INTEGRATION_CLIENTS[input.clientId];
-  const exportSpec = EXPORT_CLIENTS[input.clientId];
   const retention = retentionOf(input.clientId, store);
   /*
    * Resolution can refuse — a relative OPENCLAW_* selector names a file whose
@@ -499,14 +512,25 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
    * every client for its state, so letting that escape would answer 500 for
    * the whole Integrations page because one client is misconfigured.
    */
-  let configPath: string;
   let installed: boolean;
+  let effective: IntegrationTarget;
+  let record: OwnershipRecord | null;
   try {
     // One resolution for both, so a client whose paths come from mutable state
     // cannot report one account's install beside another account's config path.
     const paths = input.resolvedPaths ?? resolveIntegrationPaths(input.clientId, input.env, input.home);
-    configPath = paths.configPath;
     installed = io.statKind(paths.detectDir) === "dir";
+    if (input.clientId === "cline") io = createClineIO(io, paths.configPath, store);
+    /*
+     * The record is one of the inputs the target is chosen from, so it is read
+     * here rather than after the file. The status this function reports is about
+     * whichever file the next mutation would act on; reading a different one
+     * would let the badge and the switch disagree.
+     */
+    record = store.readRecords()[input.clientId] ?? null;
+    effective = resolveIntegrationTarget({
+      clientId: input.clientId, configPath: paths.configPath, io, record, env: input.env, home: input.home,
+    });
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
     /*
@@ -531,30 +555,32 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     };
   }
 
-  if (input.clientId === "cline") io = createClineIO(io, configPath, store);
-  const target = loadTarget(io, configPath);
-  if (!target.ok) {
+  const configPath = effective.configPath;
+  const loaded = loadTarget(io, configPath);
+  if (!loaded.ok) {
     return {
       clientId: input.clientId,
       state: "unsafe",
       installed,
       configPath,
-      reason: target.why === "read-failed" ? "unparseable" : "not-regular-file",
+      reason: loaded.why === "read-failed" ? "unparseable" : "not-regular-file",
       ...retention,
     };
   }
 
-  const parsed = input.clientId === "cline" ? parseClineDocument(target.before) : parseConfig(target.before, exportSpec.format);
-  const contribution = exportSpec.buildContribution(exportContextOf(input));
-  const record = store.readRecords()[input.clientId] ?? null;
+  const parsed = input.clientId === "cline"
+    ? parseClineDocument(loaded.before)
+    : parseConfig(loaded.before, effective.format);
+  const contribution = effective.buildContribution(exportContextOf(input));
   const { state, reason } = classifyIntegration({
-    fileText: target.before,
+    fileText: loaded.before,
     fileIsRegular: true,
     parsed,
     record,
     contribution,
     configPath,
     clientId: input.clientId,
+    format: effective.format,
   });
 
   return {
@@ -563,6 +589,13 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     installed,
     configPath,
     ...(reason ? { reason } : {}),
+    /*
+     * Only when the client reads a DIFFERENT file than the one this status is
+     * about. A store we are writing needs no notice; the path already names it.
+     */
+    ...(effective.ineffective && effective.ineffective.store !== configPath
+      ? { supersededBy: effective.ineffective.store }
+      : {}),
     ...(record ? { appliedAt: record.appliedAt, lastOpId: record.opId } : {}),
     ...retention,
   };
diff --git a/src/integrations/target.ts b/src/integrations/target.ts
new file mode 100644
index 00000000000..f79b645b074
--- /dev/null
+++ b/src/integrations/target.ts
@@ -0,0 +1,205 @@
+/**
+ * Which file an integration operation reads, writes and records — and, when
+ * that is not the file the client reads, which file is.
+ *
+ * A client may move its provider list between releases and keep the old file
+ * reachable only through a one-shot import. Everything the integration checks
+ * still passes against the old file: it is writable, the block merges, the
+ * ownership record describes it correctly. The only thing that changed is
+ * whether anything reads it (#5348).
+ *
+ * So the target is chosen before anything is classified, and it is chosen by
+ * three facts in this order:
+ *
+ * 1. No declared store, or no store on disk — the config file, exactly as
+ *    before. A client that has never run still imports what we write there.
+ * 2. Our own block already sits in the config file this record names. Stay
+ *    there. Disable removes what we wrote from where we wrote it, and the
+ *    caller reports the write as ineffective rather than orphaning a block in
+ *    one file while writing another.
+ * 3. Otherwise the store, but only when its schema can be established. A store
+ *    we cannot parse or whose version we have not observed is reported as the
+ *    reason the write cannot reach the client, because merging an invented
+ *    nesting into a file holding the user's other providers would trade a
+ *    silent no-op for a silent loss.
+ */
+import { EXPORT_CLIENTS, ClientPathError, type BuildContribution, type ConfigFormat } from "../clients/config-export";
+import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
+import { AmbiguousSelectorError, InvalidSelectorError, readPath } from "./merge";
+import type { OwnershipRecord } from "./ownership";
+import { INTEGRATION_CLIENTS, type IntegrationClientId } from "./registry";
+
+export interface IntegrationTarget {
+  /** The file this operation reads, writes, journals and records ownership for. */
+  readonly configPath: string;
+  /** Text format of that file, which is not always the client's config format. */
+  readonly format: ConfigFormat;
+  /** The contribution shape that file's reader understands. */
+  readonly buildContribution: BuildContribution;
+  /**
+   * Set when a write to the file above would not reach the client.
+   *
+   * `why` is carried rather than re-derived because the cases have different
+   * remedies and only this function knows which one it took. Disable is not
+   * gated on it: removing bytes this project wrote from the file it wrote them
+   * to is as effective as it ever was.
+   */
+  readonly ineffective: IneffectiveWrite | null;
+}
+
+export interface IneffectiveWrite {
+  /** The provider store the client reads. */
+  readonly store: string;
+  /**
+   * `owned-config-file` — this project's block is still in the config file, so
+   * the operation stays there and the remedy is to remove it first, rather than
+   * leave a block in one file while writing another.
+   *
+   * `unestablished-schema` — the store is not a document whose shape has been
+   * observed, so there is nothing safe to merge into it. This one is reachable
+   * with the store itself as the target: a client that bumps its schema after
+   * we wrote the store leaves our block there, removable, and the file no
+   * longer one we may merge into.
+   */
+  readonly why: "owned-config-file" | "unestablished-schema";
+}
+
+function configFileTarget(
+  clientId: IntegrationClientId,
+  configPath: string,
+  ineffective: IneffectiveWrite | null,
+): IntegrationTarget {
+  const exportSpec = EXPORT_CLIENTS[clientId];
+  return {
+    configPath,
+    format: exportSpec.format,
+    buildContribution: exportSpec.buildContribution,
+    ineffective,
+  };
+}
+
+function storeTarget(
+  declared: NonNullable<(typeof INTEGRATION_CLIENTS)[IntegrationClientId]["currentStore"]>,
+  configPath: string,
+  ineffective: IneffectiveWrite | null = null,
+): IntegrationTarget {
+  return {
+    configPath,
+    format: declared.format,
+    buildContribution: declared.buildContribution,
+    ineffective,
+  };
+}
+
+/**
+ * Does the file this record names still hold any fragment it claims?
+ *
+ * Uncertainty answers yes. An unreadable or unparseable config file is a state
+ * the classifier is about to refuse on, and it must refuse on the file our
+ * record is about rather than silently move the operation to a different one.
+ * An ambiguous or invalid selector is the same kind of answer.
+ */
+function recordedBlockStillPresent(
+  io: IntegrationIO,
+  format: ConfigFormat,
+  configPath: string,
+  record: OwnershipRecord,
+): boolean {
+  const loaded = loadTarget(io, configPath);
+  if (!loaded.ok) return true;
+  const parsed = parseConfig(loaded.before, format);
+  if (parsed === PARSE_FAILED) return true;
+  try {
+    return record.fragmentPaths.some(path => readPath(parsed, path) !== undefined);
+  } catch (error) {
+    if (error instanceof AmbiguousSelectorError || error instanceof InvalidSelectorError) return true;
+    throw error;
+  }
+}
+
+/**
+ * Resolve the target for one operation.
+ *
+ * `configPath` is the client's config file as the registry resolves it now, and
+ * `record` is the stored ownership as read, before any path filtering — the
+ * filtering depends on the answer this function returns.
+ *
+ * The store is observed through the caller's own `IntegrationIO`, never the
+ * real filesystem directly, so status and mutation cannot disagree about
+ * whether a write can land.
+ */
+export function resolveIntegrationTarget(args: {
+  clientId: IntegrationClientId;
+  configPath: string;
+  io: IntegrationIO;
+  record: OwnershipRecord | null;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}): IntegrationTarget {
+  const { clientId, configPath, io, record } = args;
+  const declared = INTEGRATION_CLIENTS[clientId].currentStore;
+  if (!declared) return configFileTarget(clientId, configPath, null);
+  const storePath = declared.path(args.env, args.home);
+  /*
+   * Only a regular file. A failed stat is an unreadable path, not evidence
+   * that the client migrated, and a directory there is not a provider list the
+   * client loaded — refusing over either would block an apply that would have
+   * worked.
+   */
+  if (io.statKind(storePath) !== "file") return configFileTarget(clientId, configPath, null);
+  const loaded = loadTarget(io, storePath);
+  const parsed = loaded.ok ? parseConfig(loaded.before, declared.format) : PARSE_FAILED;
+  const established = parsed !== PARSE_FAILED && declared.establishes(parsed);
+  const unestablished: IneffectiveWrite = { store: storePath, why: "unestablished-schema" };
+  /*
+   * Our own block decides the target before the store's schema does, whichever
+   * file holds it. Disable has to remove what we wrote from where we wrote it,
+   * and an apply must never leave a block in one file while writing another.
+   */
+  const owned = record !== null && record.clientId === clientId ? record : null;
+  if (owned?.configPath === storePath && recordedBlockStillPresent(io, declared.format, storePath, owned)) {
+    return storeTarget(declared, storePath, established ? null : unestablished);
+  }
+  if (
+    owned?.configPath === configPath
+    && recordedBlockStillPresent(io, EXPORT_CLIENTS[clientId].format, configPath, owned)
+  ) {
+    return configFileTarget(clientId, configPath, { store: storePath, why: "owned-config-file" });
+  }
+  if (!established) {
+    return configFileTarget(clientId, configPath, unestablished);
+  }
+  return storeTarget(declared, storePath);
+}
+
+/**
+ * The target a path NAMES, or null when this client may not write there.
+ *
+ * Undo acts on the file its journal row recorded, so it needs the meaning of a
+ * historical path rather than the choice above: which contribution shape
+ * describes those bytes, and whether this client still resolves that location
+ * at all. Resolving a path the client no longer names is what would let a row
+ * recorded for one home delete a file in another, so an unrecognised path is
+ * null and the caller refuses.
+ */
+export function declaredIntegrationTarget(args: {
+  clientId: IntegrationClientId;
+  configPath: string;
+  resolvedConfigPath: string;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}): IntegrationTarget | null {
+  const { clientId, configPath, resolvedConfigPath } = args;
+  if (configPath === resolvedConfigPath) return configFileTarget(clientId, configPath, null);
+  const declared = INTEGRATION_CLIENTS[clientId].currentStore;
+  if (!declared) return null;
+  try {
+    if (declared.path(args.env, args.home) !== configPath) return null;
+  } catch (error) {
+    // A store the operator relocated with a path we cannot resolve proves
+    // nothing about the row, so the row is not a legal target.
+    if (error instanceof ClientPathError) return null;
+    throw error;
+  }
+  return storeTarget(declared, configPath);
+}
diff --git a/src/integrations/writer.ts b/src/integrations/writer.ts
index fa783c37057..262b7a235a7 100644
--- a/src/integrations/writer.ts
+++ b/src/integrations/writer.ts
@@ -13,7 +13,7 @@ import { homedir } from "node:os";
 import { createClineIO, ClineTransactionError } from "./cline-io";
 import { serializeClineDocument, preserveClineSelection } from "./cline-document";
 import { dirname } from "node:path";
-import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
+import type { ExportModel, ManagedContribution } from "../clients/config-export";
 import { shouldInjectApiAuthHeader } from "../codex/inject";
 import { detachedConfigSnapshot } from "../config/admitted-identity";
 import { copyPlainData } from "../lib/plain-data";
@@ -33,6 +33,7 @@ import {
 } from "./ownership-policy";
 import { AmbiguousSelectorError, createdContainerPaths, mergeContribution, removeFragments } from "./merge";
 import { INTEGRATION_CLIENTS, isLoopbackOnly, resolveIntegrationPaths, type IntegrationClientId } from "./registry";
+import { declaredIntegrationTarget } from "./target";
 import { exportContextOf } from "./state";
 import type { IntegrationState } from "./state";
 import { serializeDocument, UnserializableValueError } from "./serialize";
@@ -251,7 +252,7 @@ function applyOrRefreshIntegration(
 ): WriteOutcome {
   const pre = preflight(input);
   if (pre.failed) return pre.failed;
-  const { store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } = pre;
+  const { store, io, clientId, spec, target, configPath, detectDir, before, parsed, contribution, record, classified } = pre;
 
   // The detect directory preflight already resolved, so it cannot name a
   // different account than the config path this operation is about to write.
@@ -262,6 +263,35 @@ function applyOrRefreshIntegration(
     return refuse(clientId, "non_loopback", classified.state,
       `The generated ${clientId} integration is loopback-only and does not emit the admission header a non-loopback bind requires. Give it loopback access instead, through a tunnel or a local forwarder.`);
   }
+  /*
+   * The write would land, and nothing would read it.
+   *
+   * This is deliberately a refusal rather than a warning attached to a success.
+   * The file is writable, our block merges cleanly, and the ownership record
+   * that follows would describe a real state of a real file — which is exactly
+   * how the original defect stayed invisible: every check the integration runs
+   * passed, the journal recorded a correct apply, and no model ever appeared in
+   * the client (#5348). Reporting the operation as done is the part that is
+   * wrong, so the operation does not report at all.
+   *
+   * Reached only when the store cannot be written: either this project's block
+   * is still in the config file, where removing it is the way forward, or the
+   * store is not a document whose shape has been observed. Where the store can
+   * be written the operation targets it and never arrives here.
+   *
+   * Apply, overwrite and refresh only. Disable removes bytes this project put
+   * in this file, and that removal is as effective as it ever was.
+   */
+  if (target.ineffective !== null) {
+    const readsFrom = target.ineffective.store;
+    const fallback = `Add the proxy as a provider in ${clientId}'s own settings instead; \`ocx export --client ${clientId}\` prints the model list to copy.`;
+    return refuse(clientId, "superseded_store", classified.state,
+      target.ineffective.why === "owned-config-file"
+        ? `${clientId} now reads its providers from ${readsFrom}, and opencodex still has a block in ${configPath}, which it no longer reads. Disable the ${clientId} integration to remove that block, then enable it again to write ${readsFrom}.`
+        : readsFrom === configPath
+          ? `opencodex does not recognise the schema of ${readsFrom}, the file ${clientId} reads its providers from, so it will not merge into it. ${fallback}`
+          : `${clientId} now reads its providers from ${readsFrom}, whose schema opencodex does not recognise, so writing ${configPath} would change nothing it loads. ${fallback}`);
+  }
   if (classified.state === "conflict") {
     if (conflictPolicy === "refuse") {
       return refuse(clientId, "conflict", "conflict",
@@ -372,7 +402,7 @@ function applyOrRefreshIntegration(
       }
       text = patched;
     } else {
-      text = clientId === "cline" ? serializeClineDocument(nextDocument) : serializeDocument(nextDocument, exportSpec.format);
+      text = clientId === "cline" ? serializeClineDocument(nextDocument) : serializeDocument(nextDocument, target.format);
     }
   } catch (error) {
     if (error instanceof AmbiguousSelectorError) {
@@ -460,7 +490,7 @@ export function refreshIntegration(input: IntegrationWriteInput): WriteOutcome {
 export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
   const pre = preflight(input);
   if (pre.failed) return pre.failed;
-  const { store, io, clientId, spec, exportSpec, configPath, before, parsed, record, classified } = pre;
+  const { store, io, clientId, spec, target, configPath, before, parsed, record, classified } = pre;
 
   if (classified.state === "absent") {
     return { ok: true, changed: false, state: "absent", clientId, message: "not applied" };
@@ -532,7 +562,7 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
       }
       text = patched;
     } else {
-      text = clientId === "cline" ? serializeClineDocument(doc) : serializeDocument(doc, exportSpec.format);
+      text = clientId === "cline" ? serializeClineDocument(doc) : serializeDocument(doc, target.format);
     }
   } catch (error) {
     if (!(error instanceof UnserializableValueError)) throw error;
@@ -570,13 +600,21 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
   const clientId = entry.clientId;
   const resolvedPath = input.resolvedPaths?.configPath
     ?? INTEGRATION_CLIENTS[clientId].configPath(input.env, input.home);
-  // Restore acts on the path the operation was journaled against. Resolving a
-  // different path here would let an operation recorded for one home delete a
-  // file in another.
   const configPath = entry.configPath;
-  if (resolvedPath !== configPath) {
+  /*
+   * Restore acts on the path the operation was journaled against. Resolving a
+   * different path here would let an operation recorded for one home delete a
+   * file in another — but a client may legally have written more than one file,
+   * so the question is whether this client still names that location, not
+   * whether it is the config file. The answer also carries the contribution
+   * shape those bytes are in, which is what the state below is measured against.
+   */
+  const rowTarget = declaredIntegrationTarget({
+    clientId, configPath, resolvedConfigPath: resolvedPath, env: input.env, home: input.home,
+  });
+  if (rowTarget === null) {
     return refuse(clientId, "conflict", "conflict",
-      `that operation was recorded for ${configPath}, but this client now resolves to ${resolvedPath}`);
+      `that operation was recorded for ${configPath}, which this client no longer writes; it now resolves to ${resolvedPath}`);
   }
   if (clientId === "cline") {
     try { io = createClineIO(io, configPath, store, true); }
@@ -625,7 +663,7 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
   // exact bytes when the snapshot was taken. Re-deriving it from the file would
   // mean guessing which entries are ours, and a wrong guess deletes a user's.
   const restoredRecord = entry.priorRecord;
-  const fresh = EXPORT_CLIENTS[clientId].buildContribution(exportContextOf(input));
+  const fresh = rowTarget.buildContribution(exportContextOf(input));
   /*
    * Does the restored record actually describe the restored bytes?
    *
diff --git a/src/lab/conformance/fixture-provider.ts b/src/lab/conformance/fixture-provider.ts
index d389deb6733..9fe74178b3b 100644
--- a/src/lab/conformance/fixture-provider.ts
+++ b/src/lab/conformance/fixture-provider.ts
@@ -12,6 +12,11 @@ export function fixtureProviderConfig(adapter: string): OcxProviderConfig {
     models: ["fixture-model"],
     defaultModel: "fixture-model",
     liveModels: false,
+    // The wire role is no longer read from the hostname, and an undeclared destination folds
+    // `developer` to `system` because one that rejects the role answers 400 and the turn never
+    // starts. This fixture is the one place that asserts the forwarded role, so the destination
+    // it stands for records that it accepts it. Only the Chat adapter reaches that decision.
+    ...(adapter === "openai-chat" ? { foldDeveloperRoleToSystem: false } : {}),
   };
 }
 
diff --git a/src/lib/browser-launch-notice.ts b/src/lib/browser-launch-notice.ts
new file mode 100644
index 00000000000..fb39c0193e1
--- /dev/null
+++ b/src/lib/browser-launch-notice.ts
@@ -0,0 +1,59 @@
+import type { OpenUrlResult } from "./open-url";
+
+/**
+ * The one sentence a terminal login says when nothing opened.
+ *
+ * Stated once because it is now said from three places — the Codex account login, the generic
+ * OAuth login and the key login — and a sentence restated three times drifts three ways. Callers
+ * that have something more specific to add append to it rather than rewriting it, so the part a
+ * user learns to recognize stays identical everywhere.
+ */
+export const BROWSER_LAUNCH_FAILED_NOTICE =
+  "⚠️  No browser could be opened here — open the URL above yourself.";
+
+/**
+ * Report a browser launch whose answer arrives after the code that started it has moved on.
+ *
+ * The OAuth controller does not await `onAuth`, so a CLI login cannot simply await the launcher
+ * there: the flow continues, and on a callback-server provider the very next thing it does is
+ * draw a readline prompt. A warning written at that moment lands on the line the user is typing
+ * on, which is worse than not warning at all.
+ *
+ * So the launch reports itself as soon as it settles, and anything that would collide with it
+ * waits on {@link BrowserLaunchReport.settled} first. The launcher answers within its own settle
+ * window, so the wait costs a fraction of a second and buys a deterministic order.
+ */
+export interface BrowserLaunchReport {
+  /** Adopt a launch already in flight. Its failure is reported once, when it settles. */
+  track(launch: Promise<OpenUrlResult>): void;
+  /**
+   * Resolves once every launch tracked BEFORE this call has been reported, and immediately when
+   * none was. A login publishes one URL, so "before this call" and "at all" are the same set
+   * here; the narrower promise is the one this actually keeps.
+   */
+  settled(): Promise<void>;
+}
+
+export function createBrowserLaunchReport(
+  warn: (message: string) => void = message => { console.warn(message); },
+): BrowserLaunchReport {
+  let pending: Promise<void> = Promise.resolve();
+  return {
+    track(launch) {
+      pending = pending
+        .then(() => launch)
+        .then(
+          result => {
+            if (result.status !== "started") warn(`\n${BROWSER_LAUNCH_FAILED_NOTICE}`);
+          },
+          // openUrl is documented never to reject, and a launcher that did would mean the same
+          // thing as one that failed. Swallowing it here is not politeness: this chain is what
+          // `settled()` hands to a prompt, so a rejection would propagate out of a login that
+          // is still perfectly able to continue, and would go unhandled in the polling flows
+          // that do not reach that await until minutes later.
+          () => { warn(`\n${BROWSER_LAUNCH_FAILED_NOTICE}`); },
+        );
+    },
+    settled: () => pending,
+  };
+}
diff --git a/src/lib/bun-runtime.ts b/src/lib/bun-runtime.ts
index e5c7ed31d34..ffe5e0b53f2 100644
--- a/src/lib/bun-runtime.ts
+++ b/src/lib/bun-runtime.ts
@@ -14,6 +14,7 @@ import { createRequire } from "node:module";
 import { realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { isRealBunBinary } from "./bun-binary-validator.mjs";
+import { isStandaloneBinary } from "./standalone";
 
 export { isRealBunBinary };
 
@@ -38,10 +39,10 @@ export const BUN_RUNTIME_SOURCE_ENV = "OCX_BUN_RUNTIME_SOURCE";
  */
 export const BUN_RUNTIME_PATH_ENV = "OCX_BUN_RUNTIME_PATH";
 
-export type BunRuntimeSource = "override" | "bundled" | "process";
+export type BunRuntimeSource = "override" | "bundled" | "process" | "standalone";
 
 /** The only provenance values any surface may accept off the wire or out of the env. */
-export const BUN_RUNTIME_SOURCES: readonly BunRuntimeSource[] = ["override", "bundled", "process"];
+export const BUN_RUNTIME_SOURCES: readonly BunRuntimeSource[] = ["override", "bundled", "process", "standalone"];
 
 export type DurableBunRuntime = {
   path: string;
@@ -165,6 +166,9 @@ function unmarkedDurableBunRuntime(): DurableBunRuntime {
 }
 
 export function durableBunRuntime(): DurableBunRuntime {
+  if (isStandaloneBinary()) {
+    return { path: process.execPath, source: "standalone", overrideEnv: BUN_OVERRIDE_ENV };
+  }
   // A durable artifact must use the runtime selected BEFORE Bun auto-loaded a
   // project dotenv. The Node launcher and owned service/shim launchers stamp the
   // selected source/path pair; it is accepted only when it names this exact
diff --git a/src/lib/debug.ts b/src/lib/debug.ts
index 938e5737ea7..9167b6ccbd0 100644
--- a/src/lib/debug.ts
+++ b/src/lib/debug.ts
@@ -52,3 +52,43 @@ export function debugProviderDiagnosticLazy(
     /* diagnostics must never affect request handling */
   }
 }
+
+/**
+ * One line per finalized attempt, formatted from what the recorder already counted.
+ *
+ * #3983 wanted this visibility and emitted a line per stream event to get it. Two things made
+ * that the wrong shape. It is a second record: `emitDebugLine` writes the ring AND stderr, and
+ * a service manager redirects stderr to a file, so an installed service accumulates a per-event
+ * history beside the ledger with its own retention and sequencing. And per-event lines needed a
+ * per-payload fingerprint to correlate, which under a process-global key makes every repeated
+ * prompt fragment and tool name correlatable for the life of the process.
+ *
+ * So this writes the ring ONLY -- `appendDebugLogLine` directly, never `emitDebugLine` -- and
+ * says nothing the ledger does not already hold. The ring becomes a live view of the durable
+ * record rather than a parallel source for it.
+ */
+export function debugAttemptDeliverySummary(
+  requestId: string,
+  attempt: {
+    ordinal: number;
+    adapter: string;
+    deliverySummary?: {
+      adapterEvents: number;
+      relayedEvents: number;
+      semanticBytes: number;
+      sideEffectEvents: number;
+      terminalEvents: number;
+    };
+  },
+): void {
+  if (!isDebugEnabled() || !attempt.deliverySummary) return;
+  try {
+    appendDebugLogLine(`[ocx:${attempt.adapter}:delivery] ${JSON.stringify({
+      requestId,
+      ordinal: attempt.ordinal,
+      ...attempt.deliverySummary,
+    })}`);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}
diff --git a/src/lib/open-url.ts b/src/lib/open-url.ts
index ae6cb900362..a13287ccf6e 100644
--- a/src/lib/open-url.ts
+++ b/src/lib/open-url.ts
@@ -8,8 +8,33 @@ function windowsRundll32(): string {
   return existsSync(candidate) ? candidate : "rundll32";
 }
 
-export function openUrl(url: string): void {
-  if (!/^https?:\/\//i.test(url)) return;
+/**
+ * Whether the OS launcher actually started. `started` does not prove a browser rendered the
+ * page — nothing observable from here can — but it does separate "we handed the URL off" from
+ * "there was nothing to hand it to", which is the distinction a caller needs (#5261).
+ */
+export type OpenUrlResult =
+  | { status: "started" }
+  | { status: "failed"; reason: "invalid-url" | "spawn-error" | "launcher-exit" };
+
+/**
+ * How long to watch a launcher that did spawn before calling it started.
+ *
+ * `spawn` only proves a process began. `xdg-open` with no desktop handler, and rundll32 given a
+ * broken association, both spawn happily and exit nonzero a moment later without opening
+ * anything — so resolving on `spawn` alone would report a launch that did not happen. Those
+ * failures are immediate, and the only caller that awaits this is a login start, so a short
+ * window buys a true answer cheaply. A launcher still running when it elapses has started.
+ */
+const LAUNCHER_SETTLE_MS = 400;
+
+/**
+ * Never rejects. A browser that would not open is an inconvenience, not a login failure: the
+ * URL is still a valid thing to open by hand, so the caller decides what to say about it.
+ * Callers that genuinely do not care use `void openUrl(...)`.
+ */
+export function openUrl(url: string): Promise<OpenUrlResult> {
+  if (!/^https?:\/\//i.test(url)) return Promise.resolve({ status: "failed", reason: "invalid-url" });
   const cmd =
     process.platform === "darwin" ? "open"
     : process.platform === "win32" ? windowsRundll32()
@@ -17,9 +42,28 @@ export function openUrl(url: string): void {
   const args = process.platform === "win32"
     ? ["url.dll,FileProtocolHandler", url]
     : [url];
-  const child = spawn(cmd, args, { detached: true, stdio: "ignore", shell: false });
-  // Headless hosts (no xdg-open) emit ENOENT as an async 'error' event; without a
-  // listener that is an uncaught exception that kills the whole proxy/login flow.
-  child.on("error", () => {});
-  child.unref();
+  return new Promise<OpenUrlResult>(resolve => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const settle = (result: OpenUrlResult) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore", shell: false });
+    // Headless hosts (no xdg-open) emit ENOENT as an async 'error' event; without a
+    // listener that is an uncaught exception that kills the whole proxy/login flow.
+    // It is also the signal itself: on Windows this is how a missing rundll32 arrives.
+    child.on("error", () => settle({ status: "failed", reason: "spawn-error" }));
+    child.on("spawn", () => {
+      // Unref'd either way: this never keeps the process alive, it only decides what to report.
+      timer = setTimeout(() => settle({ status: "started" }), LAUNCHER_SETTLE_MS);
+      timer.unref?.();
+    });
+    child.on("exit", code => settle(code === 0 || code === null
+      ? { status: "started" }
+      : { status: "failed", reason: "launcher-exit" }));
+    child.unref();
+  });
 }
diff --git a/src/lib/package-tree-integrity.ts b/src/lib/package-tree-integrity.ts
index 9b7d1e8429f..30372de183e 100644
--- a/src/lib/package-tree-integrity.ts
+++ b/src/lib/package-tree-integrity.ts
@@ -1,4 +1,5 @@
 import { statSync } from "node:fs";
+import { isStandaloneBinary } from "./standalone";
 
 export interface PackageTreeObservation {
   readonly device: bigint;
@@ -96,6 +97,6 @@ export function createRuntimePackageTreeIntegrityGuard(
   observe: ObservePackageTree = observePackageManifest,
   now: () => number = Date.now,
 ): PackageTreeIntegrityGuard {
-  if (installer === "source") return { status: () => ({ ok: true }) };
+  if (installer === "source" || isStandaloneBinary()) return { status: () => ({ ok: true }) };
   return createPackageTreeIntegrityGuard(observe, now);
 }
diff --git a/src/lib/package-version.ts b/src/lib/package-version.ts
new file mode 100644
index 00000000000..100f7e9bc0d
--- /dev/null
+++ b/src/lib/package-version.ts
@@ -0,0 +1,8 @@
+import pkg from "../../package.json" with { type: "json" };
+
+type PackageManifest = { version?: unknown };
+
+export function packageVersion(fallback = "unknown"): string {
+  const version = (pkg as PackageManifest).version;
+  return typeof version === "string" ? version : fallback;
+}
diff --git a/src/lib/provider-egress.ts b/src/lib/provider-egress.ts
new file mode 100644
index 00000000000..f37fefd9bd8
--- /dev/null
+++ b/src/lib/provider-egress.ts
@@ -0,0 +1,310 @@
+/**
+ * Per-provider egress: which transport a request for THIS provider actually leaves by.
+ *
+ * The global `proxy`/`noProxy` pair is process-wide (mirrored into HTTP_PROXY/HTTPS_PROXY/
+ * ALL_PROXY/NO_PROXY by `applyProxyEnv`), so it cannot express the split #2894 describes:
+ * one upstream must exit through a regional proxy, another must stay direct on the local
+ * network. This module is the single authority that answers that question for one request,
+ * and every transport owner that can carry the answer consumes it rather than re-deriving it.
+ *
+ * It deliberately mirrors the shape #5087 established for the global decision in
+ * `effectiveProxyFor`: the question is never "is a proxy configured" but "does a proxy apply
+ * to THIS request". A provider route is resolved against the request URL, so a per-provider
+ * bypass list is part of the decision rather than a second check somewhere downstream.
+ *
+ * The three states are exactly the ones the issue asks for, with one deliberate divergence:
+ *
+ * - field absent          -> `inherit`: the global decision stands, byte-identical to today;
+ * - `null` or `"direct"` -> `direct`: this provider never uses the global proxy;
+ * - an http(s) URL        -> `proxy`: this provider uses its own HTTP(S) proxy;
+ * - a socks5(h) URL       -> `proxy`: this provider uses its own SOCKS5 proxy.
+ *
+ * The divergence is the empty string. #2894 sketches `""` as a third spelling of DIRECT.
+ * Treating it that way would make a dashboard field the operator merely cleared silently
+ * change a provider from "inherit the global proxy" to "never use the global proxy" — the
+ * quiet reinterpretation this batch exists to remove. An empty or whitespace-only value is
+ * therefore a configuration error naming both real alternatives.
+ */
+import type { OcxProviderConfig } from "../types";
+import { isSocks5ProxyUrl, noProxyMatches } from "./proxy-env";
+
+export class InvalidProviderEgressError extends Error {
+  override readonly name = "InvalidProviderEgressError";
+  constructor(
+    /** The provider field that carries the offending value. */
+    readonly field: "proxy" | "noProxy",
+    /** The failure on its own, so configuration surfaces can phrase it their own way. */
+    readonly reason: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** The literal an operator writes to pin one provider to direct egress. */
+export const PROVIDER_EGRESS_DIRECT = "direct";
+
+export type ProviderEgress =
+  | { kind: "inherit" }
+  | { kind: "direct"; reason: "configured" | "noProxy" }
+  | { kind: "proxy"; proxyUrl: string; transport: "http" | "socks5" };
+
+export interface ProviderEgressContext {
+  providerName: string;
+  provider: Pick<OcxProviderConfig, "proxy" | "noProxy">;
+  url: string | URL;
+}
+
+function egressFailure(providerName: string, field: "proxy" | "noProxy", reason: string): never {
+  throw new InvalidProviderEgressError(field, reason, `providers.${providerName}.${field} is invalid: ${reason}`);
+}
+
+/**
+ * A proxy URL reduced to scheme, host and port for operator-facing output.
+ *
+ * A proxy URL routinely carries `user:password@`, and this value reaches startup banners,
+ * diagnostics and the dashboard DTO. `URL.origin` drops userinfo, query and path, so what is
+ * left identifies the route without reproducing the credential. Nothing derived from the
+ * credential is emitted either — not a hash, not a prefix — because a short digest over a
+ * known host is a guessable stand-in for the secret and a durable correlation key for the
+ * account behind it.
+ */
+export function sanitizeProxyUrlForLog(proxyUrl: string): string {
+  try {
+    const parsed = new URL(proxyUrl);
+    return parsed.port ? `${parsed.protocol}//${parsed.hostname}:${parsed.port}` : parsed.origin;
+  } catch {
+    return "<unparseable-proxy-url>";
+  }
+}
+
+export function describeProviderEgressForLog(egress: ProviderEgress): string {
+  if (egress.kind === "inherit") return "inherit";
+  if (egress.kind === "direct") return `direct(${egress.reason})`;
+  return `${egress.transport}(${sanitizeProxyUrlForLog(egress.proxyUrl)})`;
+}
+
+function parseTargetUrl(providerName: string, url: string | URL): URL {
+  if (url instanceof URL) return url;
+  try {
+    return new URL(url);
+  } catch {
+    return egressFailure(providerName, "proxy", "the request URL is not parseable, so no provider route can be decided for it");
+  }
+}
+
+function normalizeNoProxy(providerName: string, raw: string | string[] | undefined): string | null {
+  if (raw === undefined) return null;
+  const entries = Array.isArray(raw) ? raw : [raw];
+  for (const entry of entries) {
+    if (typeof entry !== "string") {
+      return egressFailure(providerName, "noProxy", "every entry must be a string host pattern");
+    }
+  }
+  const joined = entries.join(",").trim();
+  return joined.length > 0 ? joined : null;
+}
+
+function parseProviderProxyRoute(providerName: string, raw: string): ProviderEgress {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return egressFailure(
+      providerName,
+      "proxy",
+      `an empty value is ambiguous; write "${PROVIDER_EGRESS_DIRECT}" to force direct egress, or remove the field to inherit the global proxy`,
+    );
+  }
+  if (trimmed.toLowerCase() === PROVIDER_EGRESS_DIRECT) return { kind: "direct", reason: "configured" };
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return egressFailure(
+      providerName,
+      "proxy",
+      `"${PROVIDER_EGRESS_DIRECT}" or an absolute proxy URL is required; this value is neither`,
+    );
+  }
+  if (isSocks5ProxyUrl(trimmed)) {
+    if (!parsed.hostname) {
+      return egressFailure(providerName, "proxy", "the SOCKS5 proxy URL has no host");
+    }
+    return { kind: "proxy", proxyUrl: trimmed, transport: "socks5" };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return egressFailure(
+      providerName,
+      "proxy",
+      `unsupported proxy scheme "${parsed.protocol}"; supported schemes are http, https, socks5 and socks5h`,
+    );
+  }
+  if (!parsed.hostname) {
+    return egressFailure(providerName, "proxy", "the proxy URL has no host");
+  }
+  return { kind: "proxy", proxyUrl: parsed.toString(), transport: "http" };
+}
+
+/**
+ * The route this provider's request leaves by, or `inherit` when the global decision stands.
+ *
+ * Throws `InvalidProviderEgressError` rather than degrading to `inherit`: a malformed egress
+ * field is the one case where guessing is worst. Falling back to the global proxy would send a
+ * credential through a route the operator did not choose, and falling back to direct would
+ * leave a restricted network with no exit. Both read as success at the call site.
+ *
+ * A per-provider `noProxy` match outranks the provider's own proxy for the same reason it
+ * outranks the global one: it names destinations this provider must reach without a proxy.
+ * It is evaluated against the resolved route, so it also carves holes in an inherited global
+ * proxy — which is how a provider exempts one host without owning a proxy of its own.
+ */
+export function resolveProviderEgress(context: ProviderEgressContext): ProviderEgress {
+  const { providerName, provider } = context;
+  const raw = provider.proxy;
+  let route: ProviderEgress;
+  if (raw === undefined) {
+    route = { kind: "inherit" };
+  } else if (raw === null) {
+    route = { kind: "direct", reason: "configured" };
+  } else if (typeof raw !== "string") {
+    return egressFailure(providerName, "proxy", "the value must be a proxy URL string, \"direct\", null, or absent");
+  } else {
+    route = parseProviderProxyRoute(providerName, raw);
+  }
+  const noProxy = normalizeNoProxy(providerName, provider.noProxy);
+  if (noProxy !== null) {
+    const target = parseTargetUrl(providerName, context.url);
+    if (noProxyMatches(target, { NO_PROXY: noProxy })) return { kind: "direct", reason: "noProxy" };
+  }
+  return route;
+}
+
+/**
+ * Whether this provider decided the route itself, as opposed to deferring to the global one.
+ *
+ * Transport owners use this to tell "the operator chose this" from "nothing was configured",
+ * which are the two cases that must not be collapsed when a transport cannot carry the choice.
+ */
+export function providerEgressIsExplicit(egress: ProviderEgress): boolean {
+  return egress.kind !== "inherit";
+}
+
+/**
+ * The request-scoped fetch options that express `egress` to Bun's fetch.
+ *
+ * `proxy: false` is Bun's documented per-request direct connection: it ignores HTTP_PROXY,
+ * HTTPS_PROXY and ALL_PROXY, and it ignores NO_PROXY as well, which is what makes it a
+ * decision rather than a hint. `undefined`, `null` and `""` all mean "no option given" to
+ * Bun and fall through to the environment, so none of them can express direct egress — the
+ * reason this returns the literal `false` and never an empty string.
+ *
+ * A SOCKS5 route is returned as the same `proxy` string; `configuredOutboundFetch` recognises
+ * the scheme and hands the request to the SOCKS transport, because Bun's own fetch ignores a
+ * socks5 value.
+ */
+export function providerEgressFetchInit(egress: ProviderEgress): { proxy?: string | false } {
+  if (egress.kind === "inherit") return {};
+  if (egress.kind === "direct") return { proxy: false };
+  return { proxy: egress.proxyUrl };
+}
+
+/**
+ * Marker for an executor that forwards its `RequestInit` to a transport which honours the
+ * request-scoped proxy option.
+ *
+ * A provider route is refused on an executor that owns its own transport, because applying it
+ * is impossible and ignoring it is worse. But not every `provider.fetch` owns a transport:
+ * some are internal wrappers that add a header and delegate, and `src/providers/xai-transport.ts`
+ * installs exactly such a wrapper on every xAI route. Refusing those would make the per-provider
+ * proxy unusable on one of the two providers the original issue names.
+ *
+ * The marker is opt-in and applied by the wrapper's author, so an executor that arrives from
+ * configuration or from a caller is opaque by default and still refused. `Symbol.for` keeps the
+ * mark readable across duplicated module instances.
+ */
+const EGRESS_TRANSPARENT_EXECUTOR = Symbol.for("opencodex.provider-egress.transparent-executor");
+
+export function markEgressTransparentExecutor<Fetch extends typeof globalThis.fetch>(executor: Fetch): Fetch {
+  (executor as unknown as Record<symbol, boolean>)[EGRESS_TRANSPARENT_EXECUTOR] = true;
+  return executor;
+}
+
+export function isEgressTransparentExecutor(executor: unknown): boolean {
+  return typeof executor === "function"
+    && (executor as unknown as Record<symbol, unknown>)[EGRESS_TRANSPARENT_EXECUTOR] === true;
+}
+
+/** The destination of a fetch input, or null when it cannot be read as a URL. */
+export function egressTargetUrl(input: string | URL | Request): string | null {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.toString();
+  return typeof input?.url === "string" ? input.url : null;
+}
+
+/** Everything a physical send needs to decide the route for the request it is about to make. */
+export interface ProviderEgressBinding {
+  providerName: string;
+  provider: Pick<OcxProviderConfig, "proxy" | "noProxy">;
+}
+
+/**
+ * The request options expressing `binding`'s route for the destination actually being sent to.
+ *
+ * Resolved at the physical send rather than when the executor was built, for the reason #4992
+ * already established for the connection policy: a queued request can be rebuilt against a
+ * different upstream host before it leaves, and a route decided against the original
+ * destination would then be applied to a different one. With a host-scoped `noProxy` that
+ * inverts the decision, and the credential leaves by a route the operator did not choose.
+ *
+ * Refuses rather than degrades when the selected executor owns its own transport.
+ */
+export function providerEgressSendInit(
+  binding: ProviderEgressBinding,
+  physicalFetch: unknown,
+  input: string | URL | Request,
+): { proxy?: string | false } {
+  const url = egressTargetUrl(input);
+  if (url === null) return {};
+  const egress = resolveProviderEgress({ providerName: binding.providerName, provider: binding.provider, url });
+  if (providerEgressIsExplicit(egress) && !isEgressTransparentExecutor(physicalFetch)) {
+    // Name the field that actually made the route explicit. A bypass-list match with no
+    // `proxy` field at all would otherwise tell the operator to remove an override they
+    // never wrote.
+    const field = egress.kind === "direct" && egress.reason === "noProxy" ? "noProxy" : "proxy";
+    throw new InvalidProviderEgressError(
+      field,
+      "the selected transport owns its own routing, so this route cannot be applied",
+      `providers.${binding.providerName}.${field} cannot be applied to the selected provider transport; `
+      + "remove the provider egress override or the custom executor",
+    );
+  }
+  return providerEgressFetchInit(egress);
+}
+
+/**
+ * A destination used only to exercise the resolver at configuration time.
+ *
+ * Validation has no request URL, but `noProxy` is only meaningful against one. Resolving a
+ * reserved name checks the shape of both fields without asserting anything about which route a
+ * real request would take.
+ */
+const EGRESS_VALIDATION_URL = "https://validation.invalid/";
+
+/**
+ * The configuration error for a provider's egress fields, or null when they are usable.
+ *
+ * Delegates to `resolveProviderEgress` so configuration and request time cannot drift apart:
+ * a value accepted by `ocx config set` or the dashboard is one the transport will accept, and
+ * one rejected here is rejected there for the identical reason. Restating the rules would give
+ * this repository two definitions of a valid proxy value and no check that they agree.
+ */
+export function providerEgressConfigError(
+  provider: Pick<OcxProviderConfig, "proxy" | "noProxy">,
+): string | null {
+  try {
+    resolveProviderEgress({ providerName: "<validation>", provider, url: EGRESS_VALIDATION_URL });
+    return null;
+  } catch (error) {
+    if (error instanceof InvalidProviderEgressError) return `${error.field} is invalid: ${error.reason}`;
+    throw error;
+  }
+}
diff --git a/src/lib/provider-outbound.ts b/src/lib/provider-outbound.ts
index 799c8d69fa6..995e9b4c8fb 100644
--- a/src/lib/provider-outbound.ts
+++ b/src/lib/provider-outbound.ts
@@ -7,12 +7,13 @@ import {
   resolvePublicAddresses,
 } from "./destination-policy";
 import { pinnedHttpGet, pinnedHttpPost } from "./pinned-http";
-import { configuredOutboundFetch, effectiveProxyFor, noProxyMatches, normalizeProxyHostname, outboundProxyConfigured } from "./proxy-env";
+import { configuredOutboundFetch, effectiveProxyFor, noProxyMatches, normalizeProxyHostname, schemeMatchedProxyFor } from "./proxy-env";
+import { InvalidProviderEgressError, resolveProviderEgress } from "./provider-egress";
 import { publicProviderBaseUrl } from "./provider-url";
 
 type ProviderGetInit = Omit<RequestInit, "body" | "method" | "redirect">;
 type ProviderPostInit = ProviderGetInit & { body: string };
-type ProviderOutboundConfig = Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork"> & {
+type ProviderOutboundConfig = Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork" | "proxy" | "noProxy"> & {
   fetch?: typeof globalThis.fetch;
 };
 export interface ProviderOutboundDependencies {
@@ -165,6 +166,17 @@ async function providerOutboundRequest(
   // throw inside discovery and fail the provider for a reason nothing in its configuration
   // explains; the built-in transport is what a configured value means.
   if (typeof provider.fetch === "function") {
+    // A caller-owned executor decides its own transport, so a provider egress route cannot be
+    // applied to it. Refusing is the only honest answer: running the executor anyway would send
+    // the request by whatever route that executor picked while the configuration says otherwise.
+    if (resolveProviderEgress({ providerName: name, provider, url }).kind !== "inherit") {
+      throw new InvalidProviderEgressError(
+        "proxy",
+        "a caller-supplied fetch executor owns its own routing, so this route cannot be applied",
+        `providers.${name}.proxy cannot be applied to a caller-supplied fetch executor; `
+        + "remove the provider egress override or the custom executor",
+      );
+    }
     // A caller-owned executor cannot be peer-pinned here. This branch keeps literal/config
     // checks and redirect blocking, but does not provide the resolved-address guarantees of
     // the built-in transport. Main-request migration must define that executor contract first.
@@ -186,13 +198,39 @@ async function providerOutboundRequest(
     return provider.fetch(url, { ...init, method, redirect: "manual" });
   }
   const parsed = postUrl ?? new URL(url);
-  const proxyConfigured = outboundProxyConfigured();
-  // Snapshot the scheme-matched proxy once, before the DNS await, so admission and transport
-  // below reason about the same value. `null` here means "no proxy fetch would actually use",
-  // even if some other proxy variable is set.
-  const effectiveProxy = effectiveProxyFor(parsed);
+  // The provider's own route, decided against this request URL. `inherit` leaves every value
+  // below exactly as the global decision computed it.
+  const egress = resolveProviderEgress({ providerName: name, provider, url: parsed });
+  const providerProxy = egress.kind === "proxy" ? egress.proxyUrl : null;
+  // Snapshot the proxy fetch would actually use once, before the DNS await, so admission
+  // and transport below reason about the same value. `null` here means "no proxy fetch
+  // would actually use", even if some other proxy variable is set.
+  const globalProxy = effectiveProxyFor(parsed);
+  // The request leaves the DNS-pinned transport only when a proxy will actually carry it:
+  // a proxy variable fetch would use for this URL that NO_PROXY does not exempt.
+  // A scheme-mismatched or unusable variable, a NO_PROXY match, or an ALL_PROXY
+  // this target's scheme cannot use must not downgrade pinning or admit
+  // proxy-only DNS answers.
+  //
+  // A provider route replaces that decision outright rather than combining with it. An
+  // explicit provider proxy applies even where global NO_PROXY exempts the host, because the
+  // operator named this proxy for this provider; `providers.<name>.noProxy` is the exemption
+  // that belongs to that choice, and `resolveProviderEgress` has already applied it. A
+  // provider pinned to `direct` keeps the DNS-pinned transport, which reaches the peer
+  // through no proxy at all — the one route on this path that needs nothing from Bun.
+  const proxyApplies = egress.kind === "inherit"
+    ? globalProxy !== null && !noProxyMatches(parsed)
+    : providerProxy !== null;
   const isCanonicalUrl = dependencies.isCanonicalUrl ?? (() => false);
-  const allowMihomoIpv6FakeIp = (effectiveProxy !== null && !noProxyMatches(parsed))
+  // The IPv6 fake-IP gate keeps its stricter documented condition — a
+  // scheme-matched variable or a SOCKS5 ALL_PROXY, never a non-SOCKS
+  // ALL_PROXY — even when proxyApplies admits one for the transport
+  // decision, because admission binds the fetch to this value explicitly.
+  // An explicit provider proxy is exactly such a binding: the fetch below is pinned to it.
+  const bindingProxy = egress.kind === "inherit"
+    ? schemeMatchedProxyFor(parsed)
+    : providerProxy;
+  const allowMihomoIpv6FakeIp = (bindingProxy !== null && (providerProxy !== null || !noProxyMatches(parsed)))
     || transparentFakeIpException(url, parsed, isCanonicalUrl, name);
   const resolveAddresses = dependencies.resolveAddresses ?? resolvePublicAddresses;
   const pinnedGet = dependencies.pinnedGet ?? pinnedHttpGet;
@@ -216,7 +254,7 @@ async function providerOutboundRequest(
       // proof is on the final request URL — not the provider name — because an
       // OAuth/forward name matches any baseUrl by design while the bearer is
       // pinned to the registry destination independently.
-      allowBenchmarkAddresses: (proxyConfigured && !noProxyMatches(parsed))
+      allowBenchmarkAddresses: proxyApplies
         || transparentFakeIpException(url, parsed, isCanonicalUrl, name),
       // Mihomo IPv6 fake-IP (fdfe:dcba:9876::/48) answers are admitted either when bound
       // to a scheme-matched proxy (#3462) or under the TUN transparency exception for a
@@ -229,21 +267,28 @@ async function providerOutboundRequest(
     if (!dnsResolutionFailed) {
       throw new ProviderOutboundPolicyError(error instanceof Error ? error.message : "provider destination was blocked");
     }
-    if (!proxyConfigured) throw error;
+    if (!proxyApplies) throw error;
     warnProxyBoundaryOnce();
     warnProxyDnsDegradationOnce();
-    return configuredOutboundFetch(url, { ...init, method, redirect: "manual" });
+    // An explicit provider proxy stays pinned through the degradation too; re-inferring the
+    // route from the environment here would quietly move the request to a different exit.
+    return configuredOutboundFetch(url, {
+      ...init, method, redirect: "manual",
+      ...(providerProxy ? { proxy: providerProxy } : {}),
+    });
   }
   // A canonical TUN exception with no scheme-matched proxy must retain the
   // validated address, even when an unrelated HTTP_PROXY/ALL_PROXY is present.
-  if (proxyConfigured && !resolved.privateNetwork && (effectiveProxy !== null || !allowMihomoIpv6FakeIp)) {
+  if (proxyApplies && !resolved.privateNetwork) {
     warnProxyBoundaryOnce();
     // When the Mihomo exception could have admitted an answer, pin the transport to the
     // proxy the admission assumed instead of letting fetch re-infer it from the environment.
-    const proxy = (allowMihomoIpv6FakeIp && effectiveProxy) ? effectiveProxy : undefined;
+    // An explicit provider proxy is always pinned, for the same reason and unconditionally:
+    // the operator named the exit for this provider, so the environment must not re-decide it.
+    const proxy = providerProxy ?? ((allowMihomoIpv6FakeIp && bindingProxy) ? bindingProxy : undefined);
     return configuredOutboundFetch(url, { ...init, method, redirect: "manual", ...(proxy ? { proxy } : {}) });
   }
-  if (proxyConfigured && resolved.privateNetwork && !noProxyMatches(parsed)) {
+  if (proxyApplies && resolved.privateNetwork) {
     const hostname = normalizeProxyHostname(parsed.hostname);
     throw new Error(
       `provider URL resolves to a private-network destination; add ${hostname} to NO_PROXY before using allowPrivateNetwork with an outbound proxy`,
diff --git a/src/lib/proxy-env.ts b/src/lib/proxy-env.ts
index aebf62730bc..bf2e70b9175 100644
--- a/src/lib/proxy-env.ts
+++ b/src/lib/proxy-env.ts
@@ -86,12 +86,30 @@ export function outboundProxyConfigured(
   return OUTBOUND_PROXY_ENV_KEYS.some(key => proxyEnvPresent(key, env));
 }
 
+/**
+ * The value when `raw` is a proxy URL Bun fetch can actually use, else null.
+ * Bun rejects unparseable values and non-http(s) schemes (UnsupportedProxyProtocol),
+ * so admitting them as "the proxy that applies" would only downgrade DNS pinning.
+ */
+function usableHttpProxyUrl(raw: string | undefined): string | null {
+  if (!raw) return null;
+  try {
+    const scheme = new URL(raw).protocol;
+    return scheme === "http:" || scheme === "https:" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The proxy URL selected by configured outbound fetch for `url`, or null when none applies.
  *
  * Bun selects by scheme: `HTTPS_PROXY` for `https:` targets, `HTTP_PROXY` for `http:`.
- * A SOCKS5 `ALL_PROXY` is selected by the explicit wrapper first; other ALL_PROXY
- * schemes remain excluded because the native HTTP fetch does not honor them.
+ * A SOCKS5 `ALL_PROXY` is selected by the explicit wrapper first. A non-SOCKS
+ * `ALL_PROXY` is still honoured by the native fetch for plain `http:` targets on
+ * every platform the CI matrix covers — the provider-outbound e2e drives exactly that
+ * request through the proxy on Linux, macOS and Windows. For `https:` targets the
+ * SOCKS wrapper remains the only `ALL_PROXY` route this module counts.
  * Presence of *some* proxy variable (`outboundProxyConfigured`) is not that guarantee.
  */
 export function effectiveProxyFor(
@@ -107,8 +125,47 @@ export function effectiveProxyFor(
   // The installed SOCKS wrapper takes this route before Bun sees scheme proxies.
   const socksProxy = socks5ProxyFromEnv(env);
   if (socksProxy) return socksProxy;
+  const schemeValue = env[key]?.trim() || env[key.toLowerCase()]?.trim();
+  if (schemeValue) {
+    // A SOCKS URL in a scheme-matched variable is a usable proxy: admission
+    // binds it explicitly and the transport follows, so it applies here too.
+    if (isSocks5ProxyUrl(schemeValue)) return schemeValue;
+    // A present but unusable scheme-matched variable fails closed: it is not a
+    // proxy Bun fetch can use, and it must not fall through to ALL_PROXY either.
+    // If Bun would have used ALL_PROXY here, keeping the DNS-pinned transport is
+    // the safe direction; if it would not, this is exactly right.
+    return usableHttpProxyUrl(schemeValue);
+  }
+  if (url.protocol !== "http:") return null;
+  return usableHttpProxyUrl(env.ALL_PROXY?.trim() || env.all_proxy?.trim());
+}
+
+/**
+ * The proxy a request can be explicitly bound to for fake-IP admission, or
+ * null: a scheme-matched variable or a SOCKS5 `ALL_PROXY`. This is the
+ * stricter documented gate for Mihomo IPv6 fake-IP answers — a non-SOCKS
+ * `ALL_PROXY` does not count here even when `effectiveProxyFor` reports it,
+ * because admission pins the transport to the returned value and the gate's
+ * contract is stated in those terms. The scheme-matched value counts only as
+ * a usable binding — a SOCKS or http(s) URL; anything else would admit a
+ * fake-IP answer nothing can resolve.
+ */
+export function schemeMatchedProxyFor(
+  url: URL,
+  env: ProxyEnvMap = process.env,
+): string | null {
+  const key: ProxyEnvKey | null = url.protocol === "https:"
+    ? "HTTPS_PROXY"
+    : url.protocol === "http:"
+      ? "HTTP_PROXY"
+      : null;
+  if (!key) return null;
+  const socksProxy = socks5ProxyFromEnv(env);
+  if (socksProxy) return socksProxy;
   const value = env[key]?.trim() || env[key.toLowerCase()]?.trim();
-  return value ? value : null;
+  if (!value) return null;
+  if (isSocks5ProxyUrl(value)) return value;
+  return usableHttpProxyUrl(value);
 }
 
 export function isSocks5ProxyUrl(proxy: string): boolean {
@@ -120,16 +177,34 @@ export function socks5ProxyFromEnv(env: ProxyEnvMap = process.env): string | und
   return candidates.find(value => typeof value === "string" && isSocks5ProxyUrl(value));
 }
 
+/**
+ * A request-scoped proxy decision as the outbound transports express it.
+ *
+ * `false` is Bun's documented "connect directly": it overrides HTTP_PROXY, HTTPS_PROXY and
+ * ALL_PROXY, and it overrides NO_PROXY too. Bun treats `undefined`, `null` and `""` alike as
+ * "no option given" and falls back to the environment, so none of those can express direct
+ * egress. Declared locally because the value travels through `RequestInit`, which does not
+ * carry it in the ambient DOM types.
+ */
+export type ProxyCapableRequestInit = RequestInit & { proxy?: string | false };
+
 export function configuredOutboundFetch(
   input: RequestInfo | URL,
   init?: RequestInit,
   fallback?: typeof globalThis.fetch,
 ): Promise<Response> {
   const base = fallback ?? (globalThis.fetch === installedFetch ? nativeFetch : globalThis.fetch);
-  const explicitProxy = (init as (RequestInit & { proxy?: string }) | undefined)?.proxy;
-  const proxy = typeof explicitProxy === "string"
-    ? (isSocks5ProxyUrl(explicitProxy) ? explicitProxy : undefined)
-    : socks5ProxyFromEnv();
+  const explicitProxy = (init as ProxyCapableRequestInit | undefined)?.proxy;
+  // An explicit `false` is a decision, so it also has to win over the installed SOCKS wrapper.
+  // Reading it as "no string was supplied" would fall through to ALL_PROXY and send a request
+  // the caller pinned to direct egress through the global SOCKS proxy instead — the silent
+  // substitution the caller asked this option to prevent. Bun applies the same `false` to its
+  // own HTTP(S) proxy environment once the request reaches the base fetch below.
+  const proxy = explicitProxy === false
+    ? undefined
+    : typeof explicitProxy === "string"
+      ? (isSocks5ProxyUrl(explicitProxy) ? explicitProxy : undefined)
+      : socks5ProxyFromEnv();
   let url: URL;
   try {
     url = new URL(input instanceof Request ? input.url : String(input));
diff --git a/src/lib/request-execution-budget.ts b/src/lib/request-execution-budget.ts
index f17e44350fe..429c0bc1e9d 100644
--- a/src/lib/request-execution-budget.ts
+++ b/src/lib/request-execution-budget.ts
@@ -165,6 +165,28 @@ export interface RequestExecutionBudget extends TransientSendBudget {
   readonly alternateTargetSends: number;
   readonly targetTransitions: number;
   readonly lastTargetKey: string | undefined;
+  /**
+   * Spend one operator-granted replacement for an AMBIGUOUS failure of this logical request,
+   * up to `limit`. False once the request has none left.
+   *
+   * It lives on the budget rather than beside the policy that grants it because it has to be
+   * shared exactly where the physical-send ledger is shared. A combo child derives its own
+   * budget from the parent's ledger, and two counters would let a request whose parent leg
+   * reset before the head and whose child leg reset after it replace an unknown-state send
+   * twice. It is NOT a send budget: an authorised replacement still has to fit inside
+   * `remainingBaseSends` like every other send.
+   *
+   * `limit` is the ceiling the ASKING leg is authorised to present, and the request keeps the
+   * smallest one any leg has presented. A leg reads it from `route.provider`, which credential
+   * rotation, OAuth refresh, transport resolution and a combo target all reassign mid-request,
+   * so a per-call ceiling meant the number of duplicate inferences a request could make
+   * depended on which row happened to ask last: a row granting one, then a row granting two,
+   * bought a second replacement of a turn that may already have run.
+   *
+   * Optional so a hand-written stub that satisfies the shape test keeps typechecking; a caller
+   * that cannot reach it has no operator override, which is the fail-closed answer.
+   */
+  claimAmbiguousResend?(limit: number): boolean;
 }
 
 const RESERVE_FUNDED_CLASSES: ReadonlySet<SendClass> = new Set<SendClass>([
@@ -192,11 +214,49 @@ let logicalRequestSeq = 0;
 interface SharedSendLedger {
   spent: number;
   pendingExternalSends: number;
+  /**
+   * Spend one of this logical request's replacements for an ambiguous failure. Beside `spent`
+   * for the same reason `pendingExternalSends` is: a derived scope that shared one without the
+   * other would hand the request a second grant.
+   *
+   * A function rather than the raw count, because the count is not the whole state. The
+   * ceiling belongs to the request too, and a bridged scope has no counter of its own to keep
+   * it in -- it has to ask whoever holds the request's grant.
+   */
+  claimAmbiguousResend(limit: number): boolean;
   readonly observer?: RequestSendObserver;
 }
 
 const sharedSendLedgers = new WeakMap<RequestExecutionBudget, SharedSendLedger>();
 
+/**
+ * One logical request's replacement grant: how many it has spent, and the ceiling it is held
+ * to.
+ *
+ * The ceiling is the SMALLEST any leg has presented rather than whatever the current leg
+ * presents. Each leg reads its number from the provider row it is running against, and that
+ * row changes inside one request -- credential rotation, OAuth refresh, transport resolution
+ * and each combo target reassign it. Taking the asking leg's number let a request that had
+ * already spent the one replacement a strict row granted buy another as soon as a more
+ * permissive row asked, which is a second duplicate inference of one turn.
+ */
+function createAmbiguousResendGrant(): (limit: number) => boolean {
+  let claimed = 0;
+  let ceiling: number | undefined;
+  return (limit: number): boolean => {
+    const presented = Number.isFinite(limit) ? Math.trunc(limit) : 0;
+    // A zero or nonsense ceiling refuses on its own and leaves the request's alone. It is a
+    // caller that cannot state a grant, not an operator narrowing this request: a leg with no
+    // policy is refused before it ever claims, so binding the request to a malformed number
+    // would only let such a caller cancel a grant an opted-in row really made.
+    if (presented <= 0) return false;
+    ceiling = ceiling === undefined ? presented : Math.min(ceiling, presented);
+    if (claimed >= ceiling) return false;
+    claimed += 1;
+    return true;
+  };
+}
+
 function createRequestExecutionBudgetWithLedger(
   policy: RequestExecutionBudgetPolicy,
   logicalRequestId: string | undefined,
@@ -239,6 +299,9 @@ function createRequestExecutionBudgetWithLedger(
       const capped = Number.isFinite(cap) ? Math.trunc(cap) : 0;
       return Math.max(0, Math.min(capped, policy.baseSendAllowance - counter.spent));
     },
+    claimAmbiguousResend(limit: number): boolean {
+      return counter.claimAmbiguousResend(limit);
+    },
     reserveDispatch(intent: DispatchIntent): DispatchDecision {
       if (intent.replaySafe === false) return { allowed: false, reason: "not-replay-safe" };
       if (counter.spent >= policy.maxTotalModelSends) return { allowed: false, reason: "total-exhausted" };
@@ -336,6 +399,7 @@ export function createRequestExecutionBudget(
   return createRequestExecutionBudgetWithLedger(policy, logicalRequestId, {
     spent: 0,
     pendingExternalSends: 0,
+    claimAmbiguousResend: createAmbiguousResendGrant(),
     ...(observer ? { observer } : {}),
   });
 }
@@ -375,6 +439,14 @@ function ledgerFor(parent: RequestExecutionBudget): SharedSendLedger {
     set spent(next: number) { parent.used = next; },
     get pendingExternalSends(): number { return pendingExternalSends; },
     set pendingExternalSends(next: number) { pendingExternalSends = next; },
+    // Asked of the parent rather than counted here. A local counter is a SECOND grant: two
+    // scopes derived from one bridged parent, or one scope beside the parent it was derived
+    // from, each replaced an unknown-state send once. Pending bookings and the durable-spend
+    // observer genuinely cannot cross this boundary because they are private to the factory,
+    // but the grant can -- `claimAmbiguousResend` is public on the parent. A parent that does
+    // not implement it grants nothing, which is the fail-closed answer for a send whose
+    // upstream state is unknown.
+    claimAmbiguousResend: (limit: number): boolean => parent.claimAmbiguousResend?.(limit) === true,
   };
 }
 
diff --git a/src/lib/request-failure-attribution.ts b/src/lib/request-failure-attribution.ts
new file mode 100644
index 00000000000..098af493003
--- /dev/null
+++ b/src/lib/request-failure-attribution.ts
@@ -0,0 +1,183 @@
+/**
+ * Derive how far a failed request got and why, from the closed facts the recorder already holds.
+ *
+ * #2366 asked for durable failure attribution and shipped its own `FailureSide` and seven-member
+ * `FailureStage` to carry it. Those are a second attribution vocabulary beside the one that
+ * landed in {@link ../lib/request-failure-model}, and two vocabularies for one question is the
+ * class of defect that blocked 2.60.0. This module is the same answer expressed in the landed
+ * vocabulary: no new stage names, no new cause names, and no new record store.
+ *
+ * Everything it reads is a CLOSED value the row already carries -- an HTTP status, a terminal
+ * status, a close reason, a transport phase, a recovery kind. It never reads `errorCode` or
+ * `upstreamError`, which are open strings assembled partly from upstream text: a classification
+ * keyed on those is a different answer per provider and per locale, and a grouping key built from
+ * them cannot promise it carries no content.
+ *
+ * MUST stay a leaf. Its only imports are types and the two tables it decides with, so nothing
+ * here can pull the usage or budget subsystems into a request path that lacked them.
+ */
+import type { AttemptRecoveryKind, RequestFailureCause, RequestFailureStage } from "../usage/telemetry-contract";
+import { causeForRecoveryKind } from "./request-failure-model";
+import { classifyRequestOutcome, type RequestOutcomeFacts } from "../usage/request-outcome";
+
+/**
+ * What the recorder knows about one finished exchange at the single seam every request passes.
+ *
+ * Deliberately the same narrow set {@link RequestOutcomeFacts} reads, plus the four observation
+ * facts a stage needs. A field that could carry a provider name, a model, an account or upstream
+ * text is absent by construction rather than by review.
+ */
+export interface RequestFailureFacts extends RequestOutcomeFacts {
+  readonly transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse" | undefined;
+  /** Where the status and message came from: an origin response, or a tail this proxy wrote. */
+  readonly terminalSource?: "upstream" | "synthetic" | undefined;
+  /** True when the upstream stream died after its head was committed. */
+  readonly streamAborted?: boolean | undefined;
+  /** True once any output-bearing event reached the caller; `firstOutputMs` is the usual source. */
+  readonly outputObserved?: boolean | undefined;
+  /** True once a tool call or other externally visible effect was relayed to the caller. */
+  readonly sideEffectObserved?: boolean | undefined;
+  /** True when this proxy answered the turn itself and issued no upstream request. */
+  readonly locallyAnswered?: boolean | undefined;
+  /**
+   * Recovery kinds recorded on the attempt that ended the request, in the order they happened.
+   * Only the LAST one is ever consulted, and only under the narrow rule below.
+   */
+  readonly recoveryKinds?: readonly AttemptRecoveryKind[] | undefined;
+  /**
+   * A cause the CALLER proved, which the status alone cannot reconstruct.
+   *
+   * Set only by a finalizer that is sealing an attempt it knows the rejection for -- the
+   * key-account rotation seals the previous attempt because a named recovery rejected it, and
+   * that argument is direct evidence rather than an inference from history. It outranks the
+   * status table and is outranked by a client cancel, which is a fact about the caller and not
+   * about the origin.
+   */
+  readonly causeHint?: RequestFailureCause | undefined;
+}
+
+/**
+ * How far the caller's view of the exchange got.
+ *
+ * Total by construction and ordered downward from the most committed observation, so a fact that
+ * proves a later stage wins over one that only proves an earlier one. The boundary between
+ * `headers-only` and `protocol-prelude` is the one genuinely debatable step -- a non-streaming
+ * 4xx error body is a body, but not a protocol body event -- and it is safe to argue about
+ * because both stages carry the same `nothing-observed` commitment, so no resend decision turns
+ * on which side of it a row lands.
+ */
+export function deriveRequestFailureStage(facts: RequestFailureFacts): RequestFailureStage {
+  if (facts.terminalStatus === "completed" && facts.outputObserved === true) return "terminal";
+  if (facts.sideEffectObserved === true) return "side-effect";
+  if (facts.outputObserved === true) return "semantic-output";
+  if (facts.terminalStatus !== undefined
+    || facts.closeReason === "terminal"
+    || facts.transportPhase === "mid_stream"
+    || facts.transportPhase === "terminal_sse") return "protocol-prelude";
+  if (facts.status >= 100) return "headers-only";
+  return "pre-header";
+}
+
+/**
+ * The two recovery kinds that name a 4xx the status alone cannot tell apart.
+ *
+ * `causeForRecoveryKind` answers why a recovery was ATTEMPTED, which is usually a different
+ * question from why the request finally failed -- one that recovered from a 401 and then died on
+ * a 500 failed for the 500. So the rule here is deliberately narrow on three axes at once: only
+ * these two kinds, only when they are the LAST recovery this attempt recorded, and only when the
+ * attempt then ended on the very status that recovery was made for. Everything else falls
+ * through to the status table.
+ *
+ * The residual: a ciphertext recovery that SUCCEEDED, followed by an unrelated 400 on the same
+ * attempt, still reads as `ciphertext-refusal`, because a successful recovery does not currently
+ * clear its own evidence. Closing that belongs in the recovery path rather than here -- it is
+ * recorded in this lane's devlog as the next step -- and the rule is kept meanwhile because
+ * without it a rejected ciphertext, a rejected reasoning parameter and a rejected payload are one
+ * undifferentiated answer, which is three different remedies collapsed into one.
+ */
+const STATUS_CONFIRMED_RECOVERY_KINDS: Readonly<Partial<Record<AttemptRecoveryKind, number>>> = Object.freeze({
+  "opaque-blob-rejection": 400,
+  "reasoning-effort-downgrade": 400,
+});
+
+function refinedFourHundredCause(
+  facts: RequestFailureFacts,
+): RequestFailureCause | undefined {
+  const last = facts.recoveryKinds?.at(-1);
+  if (last === undefined) return undefined;
+  const confirmedStatus = STATUS_CONFIRMED_RECOVERY_KINDS[last];
+  return confirmedStatus === facts.status ? causeForRecoveryKind(last) : undefined;
+}
+
+/**
+ * Why the request failed.
+ *
+ * Returns `undefined` for an outcome that is not a failure. An incomplete turn is a real
+ * shortfall and gets a stage, but this dictionary answers "why did it fail", and a turn cut short
+ * by `max_output_tokens` did not fail for any of these reasons; inventing one would put a
+ * fabricated cause into a metric label and a grouping key.
+ *
+ * The status is the primary evidence because it is the one fact every transport produces. Two
+ * refinements sit above it, both from closed values: a client cancel is known from the close
+ * reason before any status is consulted, and a 400 that a recovery kind identified as a rejected
+ * ciphertext or a rejected reasoning parameter is not the same answer as a rejected payload.
+ */
+export function deriveRequestFailureCause(facts: RequestFailureFacts): RequestFailureCause | undefined {
+  const outcome = classifyRequestOutcome(facts);
+  if (outcome === "completed" || outcome === "incomplete") return undefined;
+  if (outcome === "aborted") return "client-cancelled";
+  if (facts.locallyAnswered === true) return "local-refusal";
+  // A cause the finalizer proved outranks anything reconstructed from the status.
+  if (facts.causeHint !== undefined) return facts.causeHint;
+
+  const status = facts.status;
+  // Transport evidence outranks the numeric status, because a stream that died mid-flight is
+  // reported as a SYNTHETIC 502 -- a tail this proxy wrote, not an answer the origin gave. Read
+  // in status order that 502 becomes `upstream-fault`, which claims the origin answered when it
+  // did not. Both causes refuse an automatic resend, so this is an accuracy fix rather than a
+  // safety one, but a label an operator cannot trust is a label they stop reading.
+  if (facts.streamAborted === true
+    || (facts.terminalSource === "synthetic"
+      && (facts.transportPhase === "mid_stream" || facts.transportPhase === "terminal_sse"))) {
+    return "transport-ambiguous";
+  }
+  // A 2xx head that carried a failed terminal: the origin ran the turn and said it failed. With
+  // no output relayed the useful distinction is that nothing usable came back at all.
+  if (status >= 100 && status < 400) {
+    return facts.outputObserved === true ? "upstream-fault" : "empty-output";
+  }
+  if (status === 401) return "credential-rejected";
+  if (status === 403) return "credential-rejected";
+  // Payment required. Waiting out a retry window does not help; the account has to change.
+  if (status === 402) return "quota-exhausted";
+  if (status === 413) return "payload-too-large";
+  if (status === 429) return "rate-limit";
+  if (status === 451) return "policy-refusal";
+  if (status === 503) return "upstream-declined";
+  if (status >= 500) return "upstream-fault";
+  if (status >= 400) return refinedFourHundredCause(facts) ?? "payload-rejected";
+  // No response head at all, and nothing proved the bytes never left. `transport-ambiguous` is
+  // the honest answer for an unknown execution state, and it is the safe one: it refuses an
+  // automatic resend where `transport-unsent` would permit one. `transport-unsent` is reachable
+  // only through `causeHint`, from a site that classified a pre-connect failure and can prove it.
+  return "transport-ambiguous";
+}
+
+export interface RequestFailureAttribution {
+  stage: RequestFailureStage;
+  cause?: RequestFailureCause;
+}
+
+/**
+ * The attribution to persist, or `undefined` when the request completed.
+ *
+ * A completed request has no failure to attribute, and recording a stage for one would put a
+ * `terminal` row into every grouping that exists to find failures.
+ */
+export function deriveRequestFailureAttribution(
+  facts: RequestFailureFacts,
+): RequestFailureAttribution | undefined {
+  if (classifyRequestOutcome(facts) === "completed") return undefined;
+  const cause = deriveRequestFailureCause(facts);
+  return { stage: deriveRequestFailureStage(facts), ...(cause ? { cause } : {}) };
+}
diff --git a/src/lib/request-failure-model.ts b/src/lib/request-failure-model.ts
new file mode 100644
index 00000000000..1fc3211a66b
--- /dev/null
+++ b/src/lib/request-failure-model.ts
@@ -0,0 +1,236 @@
+/**
+ * One vocabulary for how far a failed request got, why it failed, and whether this proxy may
+ * send it again (roadmap items 7 and 14).
+ *
+ * These two items are one module on purpose. Item 7 wants a resend decision per failure stage;
+ * item 14 wants one cause dictionary spanning logical request, attempt, physical send and
+ * terminal. Defined apart they typecheck on each branch and contradict each other in the merge,
+ * which is the class that blocked 2.60.0.
+ *
+ * What lives here is the vocabulary and the decision derived from it. What does NOT live here is
+ * a second record store: the durable shapes stay `PersistedUsageAttempt` and
+ * `PersistedUsageEntry` in src/usage/log.ts, and every projection below reads those structurally
+ * rather than growing a parallel history.
+ *
+ * MUST stay a leaf. Its one runtime import is `src/usage/telemetry-contract.ts`, which has no
+ * imports at all; everything else it names is a type, erased at runtime. So nothing here can
+ * pull the usage or budget subsystems into a request path that did not already have them.
+ */
+import type { SendClass } from "./request-execution-budget";
+import {
+  REQUEST_FAILURE_STAGES,
+  type AttemptRecoveryKind,
+  type RequestFailureCause,
+  type RequestFailureStage,
+  type ResendPermission,
+} from "../usage/telemetry-contract";
+
+/**
+ * The vocabulary this module decides over is DECLARED in `src/usage/telemetry-contract.ts` and
+ * re-exported here, so every importer of this module keeps its path while the dashboard can
+ * reach the same rosters without pulling this file's import graph into the browser project.
+ *
+ * What stays here is the decision: the per-stage commitment, the per-cause evidence and
+ * disposition, and the resend permission derived from them.
+ *
+ * A stage is how far the OBSERVABLE progression got, not which events happened to arrive. A turn
+ * that settled carrying no output -- an empty completion, a 4xx error body -- did not reach
+ * `terminal`; it stalled below `semantic-output`, because the caller saw no answer. `terminal`
+ * means the answer was delivered, which is why it is both last and refused.
+ */
+export {
+  REQUEST_FAILURE_CAUSES,
+  REQUEST_FAILURE_STAGES,
+  RESEND_PERMISSIONS,
+} from "../usage/telemetry-contract";
+export type {
+  RequestFailureCause,
+  RequestFailureStage,
+  ResendPermission,
+} from "../usage/telemetry-contract";
+
+/** Position in {@link REQUEST_FAILURE_STAGES}. Derived, so the order is stated exactly once. */
+export function stageRank(stage: RequestFailureStage): number {
+  return REQUEST_FAILURE_STAGES.indexOf(stage);
+}
+
+/**
+ * What the caller has irreversibly observed at a stage.
+ *
+ * Named separately from the rank so a reader can see WHY a stage refuses rather than inferring it
+ * from a position, and so the three committed stages stay distinguishable in a record.
+ */
+export type StageCommitment = "nothing-observed" | "output-observed" | "effect-observed" | "answer-delivered";
+
+const STAGE_COMMITMENT = {
+  "pre-header": "nothing-observed",
+  "headers-only": "nothing-observed",
+  "protocol-prelude": "nothing-observed",
+  "semantic-output": "output-observed",
+  "side-effect": "effect-observed",
+  "terminal": "answer-delivered",
+} as const satisfies Record<RequestFailureStage, StageCommitment>;
+
+export function stageCommitment(stage: RequestFailureStage): StageCommitment {
+  return STAGE_COMMITMENT[stage];
+}
+
+/**
+ * What the cause proves about whether the origin ran the turn.
+ *
+ * This is the safety axis. `unknown` is the RFC 9110 9.2.2 case and is never upgraded by having
+ * budget left: a request whose upstream execution state is unknown is not replayable merely
+ * because a counter allows another send.
+ */
+export type UpstreamProcessingEvidence = "not-processed" | "declined" | "processed" | "unknown";
+
+const CAUSE_EVIDENCE = {
+  "transport-unsent": "not-processed",
+  "transport-ambiguous": "unknown",
+  "upstream-declined": "declined",
+  "rate-limit": "declined",
+  "quota-exhausted": "declined",
+  "credential-rejected": "declined",
+  "policy-refusal": "processed",
+  "parameter-rejected": "declined",
+  "ciphertext-refusal": "declined",
+  "payload-too-large": "declined",
+  "payload-rejected": "declined",
+  "upstream-fault": "unknown",
+  "empty-output": "processed",
+  "client-cancelled": "unknown",
+  "local-refusal": "not-processed",
+} as const satisfies Record<RequestFailureCause, UpstreamProcessingEvidence>;
+
+export function causeEvidence(cause: RequestFailureCause): UpstreamProcessingEvidence {
+  return CAUSE_EVIDENCE[cause];
+}
+
+/**
+ * What a resend would have to change to have any chance.
+ *
+ * The usefulness axis, orthogonal to safety. A policy refusal is perfectly safe to repeat and
+ * completely pointless; an ambiguous reset is the reverse.
+ */
+export type ResendDisposition = "resend-may-help" | "resend-after-repair" | "resend-is-futile";
+
+const CAUSE_DISPOSITION = {
+  "transport-unsent": "resend-may-help",
+  "transport-ambiguous": "resend-may-help",
+  "upstream-declined": "resend-may-help",
+  "rate-limit": "resend-may-help",
+  "quota-exhausted": "resend-is-futile",
+  "credential-rejected": "resend-after-repair",
+  "policy-refusal": "resend-is-futile",
+  "parameter-rejected": "resend-after-repair",
+  "ciphertext-refusal": "resend-after-repair",
+  "payload-too-large": "resend-after-repair",
+  "payload-rejected": "resend-is-futile",
+  "upstream-fault": "resend-may-help",
+  "empty-output": "resend-may-help",
+  "client-cancelled": "resend-is-futile",
+  "local-refusal": "resend-is-futile",
+} as const satisfies Record<RequestFailureCause, ResendDisposition>;
+
+export function causeDisposition(cause: RequestFailureCause): ResendDisposition {
+  return CAUSE_DISPOSITION[cause];
+}
+
+/**
+ * Whether this proxy may send the request again, from the stage it failed at and the cause.
+ *
+ * Derived from the two per-cause facts above and the per-stage commitment, rather than written
+ * out as a stage-by-cause matrix. A matrix of that size is a restatement: it would have to be
+ * re-derived by hand every time a member is added, and the cell nobody revisited is exactly how
+ * two correct branches merge into a wrong table.
+ *
+ * `refused-ambiguous` forbids an AUTOMATIC resend. It does not forbid a narrowly scoped,
+ * explicitly opted-in recovery that a maintainer reasoned about and bounded -- the reset replay
+ * behind a default-off provider flag, the single-shot empty-completion rebuild. Those are
+ * separate recorded decisions with their own acceptance, which is precisely what distinguishes
+ * them from a retry loop that fires because a counter had room.
+ */
+export function resendPermission(
+  stage: RequestFailureStage,
+  cause: RequestFailureCause,
+): ResendPermission {
+  // Any stage at which the caller observed something refuses, whatever the cause says. Testing
+  // the commitment rather than listing the committed stages is what keeps a stage added later
+  // from defaulting into permission.
+  if (STAGE_COMMITMENT[stage] !== "nothing-observed") return "refused-committed";
+  if (CAUSE_DISPOSITION[cause] === "resend-is-futile") return "refused-futile";
+  const evidence = CAUSE_EVIDENCE[cause];
+  if (evidence === "unknown" || evidence === "processed") return "refused-ambiguous";
+  return CAUSE_DISPOSITION[cause] === "resend-after-repair" ? "permitted-after-repair" : "permitted";
+}
+
+/** True for the two permissions that allow a further send. */
+export function permitsResend(permission: ResendPermission): boolean {
+  return permission === "permitted" || permission === "permitted-after-repair";
+}
+
+/**
+ * Which request-wide send budget class a resend for this cause draws on, or null when no resend
+ * of any kind makes sense.
+ *
+ * Funding is keyed on the DISPOSITION, not on the permission. A cause the table refuses to resend
+ * automatically may still be resent by a narrowly scoped recovery a maintainer opted into, and
+ * that send has to be bought from the same budget every other send comes from -- the opt-in reset
+ * replay and the bounded empty-completion rebuild both draw on the transient allowance. Keying on
+ * permission instead would leave exactly those paths unfunded, which is how a per-layer counter
+ * reappears.
+ *
+ * Only a futile cause is null. `quota-exhausted` is null rather than `account-failover` because
+ * moving accounts is a route decision this table does not make.
+ */
+const CAUSE_SEND_CLASS = {
+  "transport-unsent": "transient",
+  "transport-ambiguous": "transient",
+  "upstream-declined": "transient",
+  "rate-limit": "transient",
+  "quota-exhausted": null,
+  "credential-rejected": "auth-recovery",
+  "policy-refusal": null,
+  "parameter-rejected": "repair",
+  "ciphertext-refusal": "repair",
+  "payload-too-large": "repair",
+  "payload-rejected": null,
+  "upstream-fault": "transient",
+  "empty-output": "transient",
+  "client-cancelled": null,
+  "local-refusal": null,
+} as const satisfies Record<RequestFailureCause, SendClass | null>;
+
+export function resendSendClass(cause: RequestFailureCause): SendClass | null {
+  return CAUSE_SEND_CLASS[cause];
+}
+
+/**
+ * The cause behind each recovery this proxy already records.
+ *
+ * Total over `AttemptRecoveryKind` by construction, so a new recovery kind is a typecheck
+ * failure here rather than a row that quietly classifies as "other" in three projections.
+ */
+const RECOVERY_KIND_CAUSE = {
+  // The retried status set mixes 503, which declined, with 500, which may already have run the
+  // turn. One kind cannot say both, so it says the weaker thing.
+  "transient-5xx": "upstream-fault",
+  "connection-reset": "transport-ambiguous",
+  "oauth-401": "credential-rejected",
+  "key-401": "credential-rejected",
+  "key-429": "rate-limit",
+  "rate-limit-429": "rate-limit",
+  "anthropic-oauth-429": "rate-limit",
+  "oauth-account-429": "rate-limit",
+  "image-413": "payload-too-large",
+  // The gateway rejects a body it accepts seconds later and the replay is byte-identical, so
+  // nothing about the payload was wrong; the origin declined to take it at that moment.
+  "console-go-upload-retry": "upstream-declined",
+  "opaque-blob-rejection": "ciphertext-refusal",
+  "empty-completion": "empty-output",
+  "reasoning-effort-downgrade": "parameter-rejected",
+} as const satisfies Record<AttemptRecoveryKind, RequestFailureCause>;
+
+export function causeForRecoveryKind(kind: AttemptRecoveryKind): RequestFailureCause {
+  return RECOVERY_KIND_CAUSE[kind];
+}
diff --git a/src/lib/request-resend-gate.ts b/src/lib/request-resend-gate.ts
new file mode 100644
index 00000000000..0107aa648bb
--- /dev/null
+++ b/src/lib/request-resend-gate.ts
@@ -0,0 +1,138 @@
+/**
+ * Whether one leg of a logical request may send it again, asked in the #5266 vocabulary.
+ *
+ * Two pull requests arrived at this question from opposite sides of the response head. #4942
+ * asked it for a connection that died before any head; #4989 asked it for an SSE body that
+ * died after the head while carrying only control events. Both are the same row of the stage
+ * table: a stage the caller observed nothing at, with a cause that cannot prove the origin did
+ * not run the turn. `resendPermission` answers `refused-ambiguous` for both, and
+ * request-failure-model.ts already names the only thing that may override that answer -- a
+ * narrowly scoped recovery a maintainer opted into and bounded.
+ *
+ * One override, not two. The reason this module exists rather than a boolean in each caller is
+ * that a request which resets before the head and again after it would otherwise buy a
+ * replacement send on each side, and the second one is exactly the duplicated inference the
+ * refusal exists to prevent. The allowance is claimed HERE, at the moment of authorisation, so
+ * a caller cannot ask without paying.
+ *
+ * MUST stay a leaf. It imports the vocabulary as values and everything else as types, so it
+ * reaches no request path that did not already have it.
+ */
+import {
+  causeForRecoveryKind,
+  permitsResend,
+  resendPermission,
+  resendSendClass,
+  type RequestFailureCause,
+  type RequestFailureStage,
+  type ResendPermission,
+} from "./request-failure-model";
+import type { SendClass } from "./request-execution-budget";
+import type { AttemptRecoveryKind } from "../usage/telemetry-contract";
+
+/**
+ * Why an authorisation was refused.
+ *
+ * The three ambiguous members are separate because they need different operator responses: no
+ * policy is a configuration choice, a request the proxy cannot judge is a property of the turn,
+ * and a spent allowance means the replacement already went somewhere else in this request.
+ */
+export const RESEND_REFUSALS = Object.freeze([
+  /** The caller already observed output, an effect, or the delivered answer. */
+  "committed",
+  /** Identical bytes would get the identical answer. */
+  "futile",
+  /** The origin's execution state is unknown and no operator policy overrides that. */
+  "ambiguous-no-policy",
+  /** An operator policy exists, but this request's second send could do more than re-infer. */
+  "ambiguous-request-not-replayable",
+  /** The operator policy exists and its replacement was already spent by this request. */
+  "ambiguous-allowance-spent",
+] as const);
+
+export type ResendRefusal = typeof RESEND_REFUSALS[number];
+
+/**
+ * The operator-granted replacement for ONE logical request.
+ *
+ * `claim` is the single counter both stages draw on. It is a method rather than a number
+ * because the holder is the request's send ledger, which a combo child shares with its parent;
+ * a number passed down per leg is what let each leg hold its own.
+ */
+export interface AmbiguousResendAllowance {
+  /** True when a second send of this request's body can only repeat the inference. */
+  readonly selfContained: boolean;
+  /** Spend one replacement. False once the request has none left. */
+  claim(): boolean;
+}
+
+interface ResendDecisionBase {
+  readonly stage: RequestFailureStage;
+  readonly cause: RequestFailureCause;
+  readonly permission: ResendPermission;
+  /**
+   * The recovery this send will be recorded as, when the caller asked in those terms. Carried
+   * back rather than re-chosen at the call site: the cause was derived from it, so recording a
+   * different kind would describe the send by a reason the gate never evaluated.
+   */
+  readonly recoveryKind?: AttemptRecoveryKind;
+}
+
+export type ResendDecision =
+  | ResendDecisionBase & {
+    readonly allowed: true;
+    /** Which request-wide send class funds it, or null when the cause funds no resend. */
+    readonly sendClass: SendClass | null;
+    /** True when the table refused and an operator allowance was spent to proceed. */
+    readonly spentOperatorAllowance: boolean;
+  }
+  | ResendDecisionBase & { readonly allowed: false; readonly refusal: ResendRefusal };
+
+/**
+ * Decide whether this proxy may send the request again after a failure at `stage` caused by
+ * `cause`, spending `allowance` when the table refuses only because the upstream state is
+ * unknown.
+ *
+ * The allowance is touched on exactly one path: a decision the table would otherwise refuse as
+ * ambiguous, for a request whose body the caller has judged replayable. A committed or futile
+ * failure never reaches it, so a turn that already produced output cannot quietly drain the
+ * replacement a later ambiguous reset would have been entitled to.
+ */
+export function authorizeResend(
+  stage: RequestFailureStage,
+  cause: RequestFailureCause,
+  allowance?: AmbiguousResendAllowance,
+  recoveryKind?: AttemptRecoveryKind,
+): ResendDecision {
+  const permission = resendPermission(stage, cause);
+  const base = { stage, cause, permission, ...(recoveryKind ? { recoveryKind } : {}) };
+  if (permitsResend(permission)) {
+    return { ...base, allowed: true, sendClass: resendSendClass(cause), spentOperatorAllowance: false };
+  }
+  if (permission === "refused-committed") return { ...base, allowed: false, refusal: "committed" };
+  if (permission === "refused-futile") return { ...base, allowed: false, refusal: "futile" };
+  if (!allowance) return { ...base, allowed: false, refusal: "ambiguous-no-policy" };
+  if (!allowance.selfContained) {
+    return { ...base, allowed: false, refusal: "ambiguous-request-not-replayable" };
+  }
+  // Claimed last, and only here. Asking earlier would spend the request's one replacement on a
+  // question whose answer was already no.
+  if (!allowance.claim()) return { ...base, allowed: false, refusal: "ambiguous-allowance-spent" };
+  return { ...base, allowed: true, sendClass: resendSendClass(cause), spentOperatorAllowance: true };
+}
+
+/**
+ * The same decision, asked in terms of the recovery this proxy will RECORD for the send.
+ *
+ * Deriving the cause from the recorded kind is what keeps the log honest: the reason an
+ * operator reads beside a send count is the reason the gate weighed, because it is the same
+ * value. A call site that recorded one kind and reasoned about another is how a send count
+ * stops meaning anything.
+ */
+export function authorizeResendForRecovery(
+  stage: RequestFailureStage,
+  kind: AttemptRecoveryKind,
+  allowance?: AmbiguousResendAllowance,
+): ResendDecision {
+  return authorizeResend(stage, causeForRecoveryKind(kind), allowance, kind);
+}
diff --git a/src/lib/standalone.ts b/src/lib/standalone.ts
new file mode 100644
index 00000000000..72cc9f36183
--- /dev/null
+++ b/src/lib/standalone.ts
@@ -0,0 +1,16 @@
+import { realpathSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Compiled Bun binaries expose their bundled module tree through the `$bunfs` marker. */
+export function isStandaloneBinary(): boolean {
+  return isStandaloneModuleUrl(import.meta.url);
+}
+
+export function isStandaloneModuleUrl(url: string): boolean {
+  return url.includes("/$bunfs/") || /^file:\/\/\/[A-Za-z]:\/~BUN\//.test(url);
+}
+
+/** Directory containing the compiled executable and its copied runtime assets. */
+export function standaloneRoot(): string {
+  return dirname(realpathSync(process.execPath));
+}
diff --git a/src/lib/upstream-retry.ts b/src/lib/upstream-retry.ts
index 8dd6f1146f1..23d1f0c4ffd 100644
--- a/src/lib/upstream-retry.ts
+++ b/src/lib/upstream-retry.ts
@@ -8,13 +8,15 @@
  * becomes a terminal, non-replayable response unless the operation is explicitly safe.
  *
  * Deliberately narrow: timeouts, aborts, ECONNREFUSED/DNS/TLS failures, and HTTP error
- * statuses (returned as Response, never thrown) are NOT retried. Mid-stream SSE resets are
- * out of scope — the response has already resolved by then.
+ * statuses (returned as Response, never thrown) are NOT retried. A reset after the response
+ * head is out of scope here, because the response has already resolved by then; the Responses
+ * transport asks the same question at that stage through the shared resend gate.
  *
  * MUST stay a leaf module: imports nothing from server.ts or adapters (kiro-retry imports
  * the shared abort helpers from here).
  */
 import { clearableDeadline } from "./abort";
+import { redactSecretString } from "./redact";
 
 /**
  * Responses the origin may already be executing. RFC 9110 §9.2.2 forbids an intermediary
@@ -96,6 +98,55 @@ export function isReplayRefusalCode(code: unknown): boolean {
 /** Client-facing status for {@link UPSTREAM_RESET_REPLAY_REFUSED_CODE}. */
 export const REPLAY_REFUSED_STATUS = 429;
 
+/**
+ * The header every surface attaches to a replay refusal, and its only accepted value.
+ *
+ * Dropping `Retry-After` is necessary and not sufficient. The Stainless-generated clients --
+ * `openai` and `anthropic` for both Python and Node, which is what most callers of this proxy
+ * actually are -- decide from a status table (408, 409, 429 and every 5xx) and compute their own
+ * backoff when no wait is named, so a 429 with no header is still resent. `x-should-retry` is
+ * the one signal each of them reads BEFORE that table, and `"false"` is the exact string they
+ * compare against.
+ */
+export const REPLAY_REFUSAL_NO_RETRY_HEADER = "x-should-retry";
+export const REPLAY_REFUSAL_NO_RETRY_VALUE = "false";
+
+/** Spreadable form for the surfaces that build their headers as an object literal. */
+export const REPLAY_REFUSAL_CLIENT_HEADERS: Readonly<Record<string, string>> = Object.freeze({
+  [REPLAY_REFUSAL_NO_RETRY_HEADER]: REPLAY_REFUSAL_NO_RETRY_VALUE,
+});
+
+/**
+ * Apply the one client-facing retry policy a refusal carries: no wait, and no automatic resend.
+ *
+ * Kept as a single function rather than two rules each surface repeats, because the two halves
+ * are only correct together -- a surface that removed the wait but not the suppression still
+ * hands a retrying client a turn it may already have run.
+ */
+export function applyReplayRefusalClientHeaders(headers: Headers): void {
+  headers.delete("retry-after");
+  headers.set(REPLAY_REFUSAL_NO_RETRY_HEADER, REPLAY_REFUSAL_NO_RETRY_VALUE);
+}
+
+/**
+ * Mark a response that re-wraps a refusal as the same refusal.
+ *
+ * The verdict has to be a property of the result the surfaces pass around, because the thing it
+ * would otherwise be read from is the status, and 429 is exactly what a refusal and a real rate
+ * limit have in common. Every formatter between the helper that made the refusal and the client
+ * builds a new Response, so each of them restates the verdict rather than dropping it.
+ */
+export function retainReplayRefusal<T extends Response>(response: T): T {
+  markResponseNonReplayable(response);
+  markReplayRefusalResponse(response);
+  return response;
+}
+
+/** Carry the verdict from a response onto the one that replaces it. */
+export function carryReplayRefusal<T extends Response>(source: Response, rewrapped: T): T {
+  return isReplayRefusalResponse(source) ? retainReplayRefusal(rewrapped) : rewrapped;
+}
+
 // 1 initial + 2 retries: the pool may hold more than one stale socket.
 const RESET_RETRY_MAX_ATTEMPTS = 3;
 const RESET_RETRY_BASE_DELAY_MS = 150;
@@ -421,6 +472,20 @@ export interface ResetRetryOptions {
    * uncounted but UNCOUNTABLE: the callback existed on a type those call sites never reach.
    */
   onSendsConsumed?: (sends: number) => void;
+  /**
+   * Spend one operator-granted replacement for a pre-header reset this helper would otherwise
+   * refuse. Absent means no operator policy, which is the fail-closed answer.
+   *
+   * A callback rather than a count, and the difference is the whole point. A count handed to
+   * each leg of a request is a count each leg holds: a rotation leg, a refresh leg and a
+   * same-target 429 leg carry the same turn, so three numbers is three replacements of one
+   * possibly-executed inference. The callback draws on ONE allowance held by the logical
+   * request, which the post-header protocol gate draws on too.
+   *
+   * It never widens the send budget. A claimed replacement still has to fit inside
+   * `attempts`, exactly like every other send this leg makes.
+   */
+  claimAmbiguousResend?: () => boolean;
 }
 
 export interface TransientRetryOptions extends ResetRetryOptions {
@@ -494,6 +559,24 @@ export function applyUpstreamRecoveryInit<T extends RequestInit>(
   return { ...init, headers, keepalive: false };
 }
 
+/**
+ * The refusal this proxy returns for an ambiguous reset it will not replace. The WeakSet
+ * markers protect in-process recovery and the code survives JSON re-wrapping, so a combo or
+ * account-recovery layer downstream cannot read it as a replayable upstream fault. The raw
+ * exception is never exposed: it can carry credentials or request data.
+ */
+export function replayRefusalResponse(): Response {
+  const response = new Response(JSON.stringify({ error: {
+    type: "upstream_error",
+    code: UPSTREAM_RESET_REPLAY_REFUSED_CODE,
+    message: "The upstream connection closed before a response was received. The request may already have been processed; automatic replay was stopped.",
+  } }), {
+    status: REPLAY_REFUSED_STATUS,
+    headers: { "content-type": "application/json", ...REPLAY_REFUSAL_CLIENT_HEADERS },
+  });
+  return retainReplayRefusal(response);
+}
+
 /**
  * Run `doFetch` within one send budget. Connection-reset-shaped rejections are
  * terminal by default; only an explicitly replay-safe operation receives reset retries
@@ -511,6 +594,10 @@ export async function fetchWithResetRetry(
   if (attempts === 0) throw new SendBudgetExhaustedError(opts.label);
   let lastError: unknown;
   let sawReset = false;
+  // True once this leg has spent the request's operator allowance. From that point the leg can
+  // only settle as the refusal: a second send of a possibly-executed turn is already out, and
+  // handing the client anything it would retry compounds it.
+  let spentOperatorReplacement = false;
   for (let attempt = 0; attempt < attempts; attempt++) {
     if (opts.abortSignal?.aborted) throw abortError(opts.abortSignal);
     // Reported before the await, one physical send at a time: a send that rejects has still
@@ -522,31 +609,37 @@ export async function fetchWithResetRetry(
     } catch (err) {
       if (opts.abortSignal?.aborted) throw err;
       if (!isConnectionResetError(err)) {
+        // Whatever ended the leg, an operator replacement already went out, so the first send
+        // may have run the turn. Settle it as the refusal instead of throwing into a caller
+        // whose transport-failure path answers with a client-retryable 502.
+        if (spentOperatorReplacement) return replayRefusalResponse();
         // A reset that already reached the origin is credential-visible
         // evidence: keep it attached so the terminal rejection cannot be
         // downgraded to the pre-connection neutral class (#914 review).
         if (sawReset) throw new UpstreamRetryEvidenceError([], err, true);
         throw err;
       }
-      if (opts.replaySafe !== true) {
-        // Return evidence instead of throwing a generic transport error: outer catches
+      if (opts.replaySafe === true) {
+        // Repeating this operation cannot duplicate anything, so an exhausted budget rethrows
+        // and the caller's own error path takes over.
+        if (attempt === attempts - 1) throw err;
+      } else {
+        // The stage table refuses an ambiguous pre-header reset. The only thing that overrides
+        // it is an operator allowance, and claiming it here is what keeps the grant single --
+        // the post-header protocol gate spends the same counter for the same logical request.
+        // Return evidence rather than throwing a generic transport error: outer catches
         // otherwise turn it into a replayable 502 and a combo/account recovery resends it.
-        // The WeakSet protects in-process recovery; the code survives JSON re-wrapping.
-        // Never expose the raw exception, which can contain credentials or request data.
-        const response = new Response(JSON.stringify({ error: {
-          type: "upstream_error",
-          code: UPSTREAM_RESET_REPLAY_REFUSED_CODE,
-          message: "The upstream connection closed before a response was received. The request may already have been processed; automatic replay was stopped.",
-        } }), { status: REPLAY_REFUSED_STATUS, headers: { "content-type": "application/json" } });
-        markResponseNonReplayable(response);
-        markReplayRefusalResponse(response);
-        return response;
+        if (attempt + 1 >= attempts || opts.claimAmbiguousResend?.() !== true) {
+          return replayRefusalResponse();
+        }
+        spentOperatorReplacement = true;
       }
-      if (attempt === attempts - 1) throw err;
       sawReset = true;
       lastError = err;
       console.warn(
-        `[upstream-retry] connection reset${opts.label ? ` (${opts.label})` : ""} — retrying (${attempt + 2}/${attempts})`,
+        `[upstream-retry] connection reset${opts.label ? ` (${opts.label})` : ""} — ${
+          spentOperatorReplacement ? "replacing" : "retrying"
+        } (${attempt + 2}/${attempts})`,
       );
       await sleepWithAbort(retryBackoffDelayMs(attempt, {
         baseDelayMs: RESET_RETRY_BASE_DELAY_MS,
@@ -661,3 +754,61 @@ export async function fetchWithTransientRetry(
     opts.onSendsConsumed?.(sent);
   }
 }
+
+export type ProtocolSafeRefetch = (signal?: AbortSignal) => Promise<Response>;
+
+export interface ProtocolSafeRefetchOptions extends ResetRetryOptions {
+  /** The replacement must match the response contract already selected for the client. */
+  acceptResponse?: (response: Response) => boolean;
+  /**
+   * Spend the logical request's allowance, immediately before the replacement send.
+   *
+   * Asked here and not earlier so a failure this helper would refuse on its own terms -- a
+   * non-reset error, a cancelled caller, a spent send budget -- cannot drain the one
+   * replacement a later ambiguous reset was entitled to. False refuses the replacement.
+   */
+  authorize?: () => boolean;
+}
+
+/**
+ * Attempt ONE caller-authorized replacement of a stream that died after the response head.
+ *
+ * The caller owns the proof that nothing was observed -- it comes from protocol inspection,
+ * not from this module -- and owns the physical-send budget. What lives here is the part that
+ * is easy to get wrong: a replacement is only usable if it is a fresh, unlocked, unread body
+ * that matches the contract already promised to the client, and anything else has to be
+ * cancelled and the original failure preserved.
+ */
+export async function refetchAfterProtocolSafeReset(
+  doFetch: ProtocolSafeRefetch,
+  err: unknown,
+  opts: ProtocolSafeRefetchOptions = {},
+): Promise<Response | null> {
+  if (!isConnectionResetError(err) || opts.abortSignal?.aborted || opts.attempts === 0) return null;
+  const label = opts.label
+    ? " (" + redactSecretString(opts.label).replace(/[\r\n\u0000-\u001f\u007f]/g, "").slice(0, 128) + ")"
+    : "";
+  if (opts.authorize && !opts.authorize()) {
+    console.warn("[upstream-retry] post-header reset replacement refused" + label + "; preserving original stream error");
+    return null;
+  }
+  let replacement: Response;
+  try {
+    replacement = await doFetch(opts.abortSignal);
+  } catch {
+    console.warn("[upstream-retry] protocol-safe refetch failed" + label + "; preserving original stream error");
+    return null;
+  }
+  const body = replacement.body;
+  let accepted = !opts.abortSignal?.aborted && replacement.ok && body !== null
+    && !replacement.bodyUsed && !body.locked && !isNonReplayableResponse(replacement);
+  try { if (accepted && opts.acceptResponse) accepted = opts.acceptResponse(replacement); }
+  catch { accepted = false; }
+  if (!accepted || opts.abortSignal?.aborted || body?.locked) {
+    try { void body?.cancel().catch(() => {}); } catch { /* already locked or closed */ }
+    console.warn("[upstream-retry] protocol-safe refetch rejected" + label + "; preserving original stream error");
+    return null;
+  }
+  console.warn("[upstream-retry] pre-output Responses reset" + label + "; using one replacement stream");
+  return replacement;
+}
diff --git a/src/lib/winsw.ts b/src/lib/winsw.ts
index f1dc60ffbae..321e3ea8132 100644
--- a/src/lib/winsw.ts
+++ b/src/lib/winsw.ts
@@ -72,7 +72,7 @@ export interface WinswEntry {
   bun: string;
   /** Provenance of `bun`, resolved together with it so the two can never disagree. */
   bunRuntimeSource: BunRuntimeSource;
-  cli: string;
+  cli: string | null;
 }
 
 /**
@@ -118,7 +118,7 @@ export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = proces
   <name>OpenCodex Proxy (native)</name>
   <description>OpenCodex proxy running as a native Windows service (windowless, starts at boot).</description>
   <executable>${xmlEscape(entry.bun)}</executable>
-  <arguments>${xmlEscape(`"${entry.cli}" start --port ${safeListenPort}`)}</arguments>
+  <arguments>${xmlEscape(`${entry.cli ? `"${entry.cli}" ` : ""}start --port ${safeListenPort}`)}</arguments>
 ${envLines.join("\n")}
   <logpath>${xmlEscape(winswLogDir())}</logpath>
   <log mode="roll-by-size">
diff --git a/src/oauth/index.ts b/src/oauth/index.ts
index f33a6855c0b..5d8e00ef472 100644
--- a/src/oauth/index.ts
+++ b/src/oauth/index.ts
@@ -1273,6 +1273,29 @@ const OAUTH_RECONCILE_FIELDS: (keyof OcxProviderConfig)[] = [
 // existing rows through enrichProviderFromRegistry, which is fill-only and
 // preserves explicit saved values.
 
+/**
+ * Output-budget fields an OAuth preset may refresh but must never erase.
+ *
+ * These stay on the reconcile list so a preset that does declare a budget still
+ * refreshes the saved row. What changes is the other branch: when the preset
+ * declares nothing, the operator's value survives instead of being deleted.
+ *
+ * Without that, the fields behaved as if they could not be configured at all.
+ * No OAuth preset seeds either one, so the delete branch was the only branch
+ * these two ever took, and a hand-edited `defaultMaxOutputTokens` was gone
+ * before the first turn of the next startup — leaving the adapter's own
+ * fallback as the only reachable output cap (#5190).
+ *
+ * Scoped to the output budget on purpose. The input side (`contextWindow`,
+ * `modelContextWindows`) describes what the account's models are, which the
+ * preset and live discovery do own; an output budget is a spend decision the
+ * operator makes.
+ */
+const OAUTH_PRESERVE_WHEN_PRESET_UNSET: ReadonlySet<keyof OcxProviderConfig> = new Set([
+  "defaultMaxOutputTokens",
+  "modelMaxOutputTokens",
+]);
+
 const GOOGLE_ANTIGRAVITY_PROVIDER = "google-antigravity";
 const GOOGLE_ANTIGRAVITY_LIVE_DISCOVERY_VERSION = 2 as const;
 
@@ -1312,7 +1335,7 @@ function applyOAuthPresetCatalog(
     if (JSON.stringify(provider[field]) === JSON.stringify(preset[field])) continue;
     if (preset[field] !== undefined) {
       provider[field] = cloneProviderField(preset[field]) as never;
-    } else {
+    } else if (!OAUTH_PRESERVE_WHEN_PRESET_UNSET.has(field)) {
       delete provider[field];
     }
   }
diff --git a/src/oauth/login-cli.ts b/src/oauth/login-cli.ts
index 45db1af0ecf..a842affc9ca 100644
--- a/src/oauth/login-cli.ts
+++ b/src/oauth/login-cli.ts
@@ -2,6 +2,7 @@ import * as readline from "node:readline";
 import { modelSelectionGuidance } from "../cli/model-selection-guidance";
 import { initializeProviderModelSelection } from "../providers/initial-model-selection";
 import { openUrl } from "../lib/open-url";
+import { createBrowserLaunchReport } from "../lib/browser-launch-notice";
 import { loadConfig, saveConfig } from "../config";
 import { findLiveProxy } from "../server/proxy-liveness";
 import {
@@ -14,6 +15,41 @@ import type { OcxConfig, OcxProviderConfig } from "../types";
 import { configuredAdminToken } from "../lib/admin-secrets";
 import { codexAccountNamespaceProviderCollisionError } from "../codex/account-namespace-match";
 
+/**
+ * Seams a test drives in place of a browser, a terminal and a real provider. Production passes
+ * none of them.
+ *
+ * They exist because the thing worth proving here is an ORDER — that a browser which did not
+ * open is on screen before the question that assumes it did — and an order is only observable
+ * from something that records both events. Spawning a launcher and attaching to stdin to find
+ * that out would test the operating system instead.
+ */
+export interface LoginCliDeps {
+  runLogin?: typeof runLogin;
+  openUrl?: typeof openUrl;
+  warn?: (message: string) => void;
+  /** Ask one question, read one line. Defaults to a readline prompt that owns its own lifetime. */
+  ask?: (question: string) => Promise<string>;
+}
+
+/**
+ * Run `body` with a line reader, creating and closing a real one only when the caller did not
+ * supply its own. A readline interface attaches to stdin, so building one that nothing will ask
+ * a question keeps the process alive for no reason.
+ */
+async function withPrompt<T>(
+  supplied: ((question: string) => Promise<string>) | undefined,
+  body: (ask: (question: string) => Promise<string>) => Promise<T>,
+): Promise<T> {
+  if (supplied) return await body(supplied);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await body(question => new Promise<string>(resolve => rl.question(question, resolve)));
+  } finally {
+    rl.close();
+  }
+}
+
 const LIVE_RELOAD_PROVIDERS = new Set<string>([
   ...listOAuthProviders(),
   ...Object.keys(KEY_LOGIN_PROVIDERS),
@@ -83,7 +119,7 @@ export function loginUsageMessage(): string {
     + `  API-key login: ${Object.keys(KEY_LOGIN_PROVIDERS).join(", ")}`;
 }
 
-export async function handleLogin(provider?: string): Promise<void> {
+export async function handleLogin(provider?: string, deps: LoginCliDeps = {}): Promise<void> {
   const name = (provider ?? "").trim().toLowerCase();
   // A removed provider id reached through its alias still logs in — the merged
   // successor owns the flow. Warn rather than silently reroute so scripts and
@@ -91,30 +127,40 @@ export async function handleLogin(provider?: string): Promise<void> {
   const alias = DEPRECATED_OAUTH_PROVIDER_ALIASES[name];
   if (alias) {
     console.error(`${name} is deprecated; logging in as ${alias}`);
-    return handleOAuthLogin(alias);
+    return handleOAuthLogin(alias, deps);
   }
-  if (isPublicOAuthProvider(name)) return handleOAuthLogin(name);
-  if (isKeyLoginProvider(name)) return handleKeyLogin(name);
+  if (isPublicOAuthProvider(name)) return handleOAuthLogin(name, deps);
+  if (isKeyLoginProvider(name)) return handleKeyLogin(name, deps);
   console.error(loginUsageMessage());
   process.exit(1);
 }
 
-async function handleOAuthLogin(name: string): Promise<void> {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    await runLogin(name, {
+export async function handleOAuthLogin(name: string, deps: LoginCliDeps = {}): Promise<void> {
+  const login = deps.runLogin ?? runLogin;
+  const launch = deps.openUrl ?? openUrl;
+  const browser = createBrowserLaunchReport(deps.warn);
+  await withPrompt(deps.ask, async (ask) => {
+    await login(name, {
       onAuth: ({ url, instructions }) => {
         console.log(`\n🔐 Opening browser for ${name} login...\n${url}\n`);
         if (instructions) console.log(instructions);
-        openUrl(url);
+        // The controller does not await onAuth, so the launcher's answer cannot be reported from
+        // here — this returns long before it arrives. It reports itself instead, and the one
+        // thing that could collide with it waits below (#5261).
+        browser.track(launch(url));
       },
       onProgress: (m) => console.log(`   ${m}`),
-      onManualCodeInput: () =>
-        new Promise((res) => rl.question("Paste redirect URL or code (or wait for browser): ", res)),
+      onManualCodeInput: async () => {
+        // "or wait for browser" is a lie if nothing opened, and a warning printed after readline
+        // has drawn the prompt lands on the line the user is typing on.
+        await browser.settled();
+        return await ask("Paste redirect URL or code (or wait for browser): ");
+      },
     });
-  } finally {
-    rl.close();
-  }
+  });
+  // A device or polling provider never prompts, so nothing above waited on the launcher. It is
+  // still owed an answer before this claims the login worked.
+  await browser.settled();
   const reload = await notifyRunningProxyAfterOAuthLogin(name);
   console.log(`\n✅ Logged in to ${name}. Try: ocx sync`);
   for (const line of modelSelectionGuidance(name)) console.log(line);
@@ -192,8 +238,9 @@ export async function commitKeyLoginProvider(
   return mergedProvider;
 }
 
-async function handleKeyLogin(name: string): Promise<void> {
+export async function handleKeyLogin(name: string, deps: LoginCliDeps = {}): Promise<void> {
   const def = KEY_LOGIN_PROVIDERS[name];
+  const launch = deps.openUrl ?? openUrl;
   const preflightConfig = loadConfig();
   const namespaceCollision = codexAccountNamespaceProviderCollisionError(preflightConfig.codexAccountNamespaces, name);
   if (namespaceCollision) {
@@ -201,21 +248,25 @@ async function handleKeyLogin(name: string): Promise<void> {
     process.exit(1);
   }
   console.log(`\n🔑 ${def.label} — opening ${def.dashboardUrl} so you can create/copy an API key...`);
-  openUrl(def.dashboardUrl);
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  const key = (await new Promise<string>((res) => rl.question(`Paste your ${def.label} API key: `, res))).trim();
-  // Template URL with placeholders needs resolution before saving.
-  let baseUrl = def.baseUrl;
-  if (/\{[^}]*\}/.test(baseUrl)) {
-    const resolved = (await new Promise<string>((res) => rl.question(`Your endpoint URL (${baseUrl}): `, res))).trim();
-    if (!resolved) {
-      rl.close();
-      console.error("A resolved URL is required — replace the {placeholder} with your actual value.");
-      process.exit(1);
+  const browser = createBrowserLaunchReport(deps.warn);
+  browser.track(launch(def.dashboardUrl));
+  // The next question asks for a key the user gets FROM that page, so a page that never opened
+  // has to be on screen before the question rather than underneath it (#5261).
+  await browser.settled();
+  const { key, baseUrl } = await withPrompt(deps.ask, async (ask) => {
+    const entered = (await ask(`Paste your ${def.label} API key: `)).trim();
+    // Template URL with placeholders needs resolution before saving.
+    let resolvedBaseUrl = def.baseUrl;
+    if (/\{[^}]*\}/.test(resolvedBaseUrl)) {
+      const resolved = (await ask(`Your endpoint URL (${resolvedBaseUrl}): `)).trim();
+      if (!resolved) {
+        console.error("A resolved URL is required — replace the {placeholder} with your actual value.");
+        process.exit(1);
+      }
+      resolvedBaseUrl = resolved;
     }
-    baseUrl = resolved;
-  }
-  rl.close();
+    return { key: entered, baseUrl: resolvedBaseUrl };
+  });
   if (!key) {
     console.error("No key entered.");
     process.exit(1);
diff --git a/src/providers/api-key-resolve.ts b/src/providers/api-key-resolve.ts
new file mode 100644
index 00000000000..3b78418f98f
--- /dev/null
+++ b/src/providers/api-key-resolve.ts
@@ -0,0 +1,133 @@
+/**
+ * Read-path for provider key material: env references, keychain references, or the literal
+ * value.
+ *
+ * Leaf module on purpose: reasoning-metadata.ts imports resolveProviderApiKey() here so a
+ * learned-refusal identity can hash the same credential the wire sends. key-store.ts needs
+ * the ../config barrel for the write path (saveConfigPreservingClaudeCode), and importing it
+ * from reasoning-metadata would close the cycle the reasoning-metadata header warns about.
+ * resolveEnvValue comes from ../config/proxy-env for the same reason.
+ *
+ * `config.json` keeps only a reference (`keychain:<provider>` for the active key,
+ * `keychain:<provider>/<pool id>` for pool entries); the secret lives in the OS credential store
+ * under one service name. Reads are synchronous on purpose: `routedProviderConfig` and the
+ * quota/compaction/catalog callers are all sync, and `@napi-rs/keyring` ships a sync `Entry`.
+ *
+ * Policy: a reference that cannot be resolved fails closed (no key) and is warned once per
+ * account; nothing ever rewrites plaintext into config or its backups.
+ */
+import { createRequire } from "node:module";
+import { resolveEnvValue } from "../config/proxy-env";
+import type { OcxProviderConfig } from "../types";
+
+export const KEYCHAIN_REFERENCE_PREFIX = "keychain:";
+export const PROVIDER_KEYCHAIN_SERVICE = "opencodex.provider-api-key.v1";
+
+export interface ProviderKeychainEntry {
+  getPassword(): string | null;
+  setPassword(password: string): void;
+  deletePassword(): boolean;
+}
+
+export type ProviderKeychainEntryFactory = (service: string, account: string) => ProviderKeychainEntry;
+
+const nodeRequire = createRequire(import.meta.url);
+
+function defaultEntryFactory(service: string, account: string): ProviderKeychainEntry {
+  const { Entry } = nodeRequire("@napi-rs/keyring") as { Entry: new (s: string, a: string) => ProviderKeychainEntry };
+  return new Entry(service, account);
+}
+
+let entryFactory: ProviderKeychainEntryFactory = defaultEntryFactory;
+const resolvedCache = new Map<string, string>();
+const warnedAccounts = new Set<string>();
+
+/** Test seam: swap the OS entry for an in-memory one and drop caches. */
+export function setProviderKeychainEntryFactoryForTests(factory: ProviderKeychainEntryFactory | null): void {
+  entryFactory = factory ?? defaultEntryFactory;
+  resolvedCache.clear();
+  warnedAccounts.clear();
+}
+
+/** Write-path seam: a store/restore mutated secrets, so cached reads and warnings are stale. */
+export function invalidateResolvedProviderKeyCache(): void {
+  resolvedCache.clear();
+  warnedAccounts.clear();
+}
+
+export function isKeychainReference(value: string | undefined): value is string {
+  return typeof value === "string" && value.startsWith(KEYCHAIN_REFERENCE_PREFIX) && value.length > KEYCHAIN_REFERENCE_PREFIX.length;
+}
+
+export function keychainAccount(reference: string): string {
+  return reference.slice(KEYCHAIN_REFERENCE_PREFIX.length);
+}
+
+/**
+ * A reference belongs to `name` only when its account is that provider's own active account
+ * or one of its pool accounts. `storeProviderKeyInKeychain` writes exactly those two shapes,
+ * so anything else in a provider's config names another provider's secret.
+ */
+export function keychainReferenceBelongsToProvider(reference: string, name: string): boolean {
+  const account = keychainAccount(reference);
+  return account === name || account.startsWith(`${name}/`);
+}
+
+/** Entry for `account` under the provider-key service; read and write paths share the factory. */
+export function providerKeychainEntry(account: string): ProviderKeychainEntry {
+  return entryFactory(PROVIDER_KEYCHAIN_SERVICE, account);
+}
+
+function readKeychain(account: string): string | undefined {
+  const cached = resolvedCache.get(account);
+  if (cached !== undefined) return cached;
+  try {
+    const value = providerKeychainEntry(account).getPassword();
+    if (typeof value === "string" && value.trim()) {
+      resolvedCache.set(account, value);
+      return value;
+    }
+  } catch {
+    // fall through to the single warning below
+  }
+  if (!warnedAccounts.has(account)) {
+    warnedAccounts.add(account);
+    console.warn(`[opencodex] provider key reference keychain:${account} could not be read from the OS keychain; requests for this provider have no credential until the keychain is available (no plaintext fallback)`);
+  }
+  return undefined;
+}
+
+/**
+ * Single resolver for provider key material: env references, keychain references, or the
+ * literal value. Every request-time read of `apiKey` goes through here.
+ */
+export function resolveProviderApiKey(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  if (isKeychainReference(value)) return readKeychain(keychainAccount(value));
+  return resolveEnvValue(value);
+}
+
+export type ProviderKeyStoreKind = "keychain" | "env" | "file" | "none";
+
+export function providerKeyStoreKind(provider: Pick<OcxProviderConfig, "apiKey"> | undefined): ProviderKeyStoreKind {
+  const key = provider?.apiKey;
+  if (!key) return "none";
+  if (isKeychainReference(key)) return "keychain";
+  if (/^\$\{?\w+\}?$/.test(key)) return "env";
+  return "file";
+}
+
+/** Probe the OS keychain with a throwaway account: write, read back, delete. */
+export function probeProviderKeychain(): { available: true } | { available: false; reason: string } {
+  const account = `probe-${process.pid}-${Date.now()}`;
+  try {
+    const entry = providerKeychainEntry(account);
+    entry.setPassword("ok");
+    const back = entry.getPassword();
+    try { entry.deletePassword(); } catch { /* best effort */ }
+    if (back !== "ok") return { available: false, reason: "keychain read-back did not match" };
+    return { available: true };
+  } catch (error) {
+    return { available: false, reason: error instanceof Error ? error.message : "keychain unavailable" };
+  }
+}
diff --git a/src/providers/key-failover.ts b/src/providers/key-failover.ts
index e4552df141a..c96b555029b 100644
--- a/src/providers/key-failover.ts
+++ b/src/providers/key-failover.ts
@@ -13,7 +13,7 @@ import type { ProviderApiKeySelection } from "../types/provider";
 import { routedProviderConfig } from "../router";
 import { getProviderRegistryEntry } from "./registry";
 import { normalizedBaseUrl } from "./quota/vendor-probes-key";
-import type { OcxConfig, OcxProviderConfig, RateLimitRetryPolicy, TransientRetryPolicy } from "../types";
+import type { OcxConfig, OcxProviderConfig, RateLimitRetryPolicy, ResetReplayPolicy, TransientRetryPolicy } from "../types";
 import { OPENCODE_GO_SESSION_HEADER } from "./opencode-go-transport";
 import { resolveProviderTransport, type OcxProviderTransport } from "./xai-transport";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
@@ -326,6 +326,16 @@ const DEFAULT_TRANSIENT_RETRY = {
   attempts: 3,
 } as const satisfies Required<TransientRetryPolicy>;
 
+/**
+ * Default used when a provider opts in with a bare `retryOnReset: {}`: one replacement for
+ * the whole logical request. `replacements` counts duplicate inferences the operator accepts,
+ * not retries and not sends.
+ */
+const DEFAULT_RESET_REPLAY = {
+  enabled: true,
+  replacements: 1,
+} as const satisfies Required<ResetReplayPolicy>;
+
 /** Map<`${providerName}\0${keyId}`, KeyCooldown> */
 const keyCooldowns = new Map<string, KeyCooldown>();
 
@@ -616,6 +626,26 @@ export function transientRetryPolicyFor(
   };
 }
 
+/**
+ * Normalize a provider's `retryOnReset` policy, or return null when it is absent or explicitly
+ * disabled.
+ *
+ * No auth-mode gate: the canonical ChatGPT backend is `forward` auth and is the send this
+ * policy exists for. Whether a given REQUEST may be replaced is a per-body decision made in
+ * src/server/responses/reset-replay.ts, and how many replacements the request gets is the
+ * shared allowance on its execution budget. This function only reads the operator's intent.
+ */
+export function resetReplayPolicyFor(
+  provider: Pick<OcxProviderConfig, "retryOnReset">,
+): Required<ResetReplayPolicy> | null {
+  const policy = provider.retryOnReset;
+  if (!policy || policy.enabled === false) return null;
+  return {
+    enabled: policy.enabled ?? DEFAULT_RESET_REPLAY.enabled,
+    replacements: policy.replacements ?? DEFAULT_RESET_REPLAY.replacements,
+  };
+}
+
 /**
  * Wait before the next same-target replay: upstream Retry-After (seconds or HTTP-date) when
  * `respectRetryAfter` is on and the header parses, capped at `maxIntervalMs`; otherwise the
diff --git a/src/providers/key-store.ts b/src/providers/key-store.ts
index 614fd3372fa..428b018213f 100644
--- a/src/providers/key-store.ts
+++ b/src/providers/key-store.ts
@@ -1,7 +1,34 @@
-import { createRequire } from "node:module";
 import { resolveEnvValue, saveConfigPreservingClaudeCode } from "../config";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import type { ProviderRegistryEntry } from "./registry";
+import {
+  KEYCHAIN_REFERENCE_PREFIX,
+  invalidateResolvedProviderKeyCache,
+  isKeychainReference,
+  keychainAccount,
+  keychainReferenceBelongsToProvider,
+  probeProviderKeychain,
+  providerKeychainEntry,
+} from "./api-key-resolve";
+
+// The read-path (reference predicates, the OS entry factory, resolveProviderApiKey, the probe
+// and the kind classification) lives in ./api-key-resolve -- a leaf module that
+// reasoning-metadata can also import without pulling the ../config barrel into its
+// cycle-sensitive graph. Re-exported here so existing key-store consumers keep working.
+export {
+  KEYCHAIN_REFERENCE_PREFIX,
+  PROVIDER_KEYCHAIN_SERVICE,
+  isKeychainReference,
+  probeProviderKeychain,
+  providerKeyStoreKind,
+  resolveProviderApiKey,
+  setProviderKeychainEntryFactoryForTests,
+} from "./api-key-resolve";
+export type {
+  ProviderKeychainEntry,
+  ProviderKeychainEntryFactory,
+  ProviderKeyStoreKind,
+} from "./api-key-resolve";
 
 /** Shared with routing: a key-mode override is effective only while its key resolves. */
 export function providerUsesKeyAuthOverride(
@@ -27,109 +54,8 @@ export function providerUsesKeyAuthOverride(
  * (headless service, locked session) refuses rather than half-migrating.
  */
 
-export const KEYCHAIN_REFERENCE_PREFIX = "keychain:";
-export const PROVIDER_KEYCHAIN_SERVICE = "opencodex.provider-api-key.v1";
-
-export interface ProviderKeychainEntry {
-  getPassword(): string | null;
-  setPassword(password: string): void;
-  deletePassword(): boolean;
-}
-
-export type ProviderKeychainEntryFactory = (service: string, account: string) => ProviderKeychainEntry;
-
-const nodeRequire = createRequire(import.meta.url);
-
-function defaultEntryFactory(service: string, account: string): ProviderKeychainEntry {
-  const { Entry } = nodeRequire("@napi-rs/keyring") as { Entry: new (s: string, a: string) => ProviderKeychainEntry };
-  return new Entry(service, account);
-}
-
-let entryFactory: ProviderKeychainEntryFactory = defaultEntryFactory;
-const resolvedCache = new Map<string, string>();
-const warnedAccounts = new Set<string>();
-
-/** Test seam: swap the OS entry for an in-memory one and drop caches. */
-export function setProviderKeychainEntryFactoryForTests(factory: ProviderKeychainEntryFactory | null): void {
-  entryFactory = factory ?? defaultEntryFactory;
-  resolvedCache.clear();
-  warnedAccounts.clear();
-}
-
-export function isKeychainReference(value: string | undefined): value is string {
-  return typeof value === "string" && value.startsWith(KEYCHAIN_REFERENCE_PREFIX) && value.length > KEYCHAIN_REFERENCE_PREFIX.length;
-}
-
-function keychainAccount(reference: string): string {
-  return reference.slice(KEYCHAIN_REFERENCE_PREFIX.length);
-}
-
-/**
- * A reference belongs to `name` only when its account is that provider's own active account
- * or one of its pool accounts. `storeProviderKeyInKeychain` writes exactly those two shapes,
- * so anything else in a provider's config names another provider's secret.
- */
-function keychainReferenceBelongsToProvider(reference: string, name: string): boolean {
-  const account = keychainAccount(reference);
-  return account === name || account.startsWith(`${name}/`);
-}
-
-function readKeychain(account: string): string | undefined {
-  const cached = resolvedCache.get(account);
-  if (cached !== undefined) return cached;
-  try {
-    const value = entryFactory(PROVIDER_KEYCHAIN_SERVICE, account).getPassword();
-    if (typeof value === "string" && value.trim()) {
-      resolvedCache.set(account, value);
-      return value;
-    }
-  } catch {
-    // fall through to the single warning below
-  }
-  if (!warnedAccounts.has(account)) {
-    warnedAccounts.add(account);
-    console.warn(`[opencodex] provider key reference keychain:${account} could not be read from the OS keychain; requests for this provider have no credential until the keychain is available (no plaintext fallback)`);
-  }
-  return undefined;
-}
-
-/**
- * Single resolver for provider key material: env references, keychain references, or the
- * literal value. Every request-time read of `apiKey` goes through here.
- */
-export function resolveProviderApiKey(value: string | undefined): string | undefined {
-  if (!value) return undefined;
-  if (isKeychainReference(value)) return readKeychain(keychainAccount(value));
-  return resolveEnvValue(value);
-}
-
-export type ProviderKeyStoreKind = "keychain" | "env" | "file" | "none";
-
-export function providerKeyStoreKind(provider: Pick<OcxProviderConfig, "apiKey"> | undefined): ProviderKeyStoreKind {
-  const key = provider?.apiKey;
-  if (!key) return "none";
-  if (isKeychainReference(key)) return "keychain";
-  if (/^\$\{?\w+\}?$/.test(key)) return "env";
-  return "file";
-}
-
-/** Probe the OS keychain with a throwaway account: write, read back, delete. */
-export function probeProviderKeychain(): { available: true } | { available: false; reason: string } {
-  const account = `probe-${process.pid}-${Date.now()}`;
-  try {
-    const entry = entryFactory(PROVIDER_KEYCHAIN_SERVICE, account);
-    entry.setPassword("ok");
-    const back = entry.getPassword();
-    try { entry.deletePassword(); } catch { /* best effort */ }
-    if (back !== "ok") return { available: false, reason: "keychain read-back did not match" };
-    return { available: true };
-  } catch (error) {
-    return { available: false, reason: error instanceof Error ? error.message : "keychain unavailable" };
-  }
-}
-
 function writeVerified(account: string, secret: string): void {
-  const entry = entryFactory(PROVIDER_KEYCHAIN_SERVICE, account);
+  const entry = providerKeychainEntry(account);
   entry.setPassword(secret);
   if (entry.getPassword() !== secret) throw new Error(`keychain read-back mismatch for ${account}`);
 }
@@ -177,13 +103,12 @@ export function storeProviderKeyInKeychain(config: OcxConfig, name: string): { o
     }
   } catch (error) {
     for (const account of written) {
-      try { entryFactory(PROVIDER_KEYCHAIN_SERVICE, account).deletePassword(); } catch { /* best effort */ }
+      try { providerKeychainEntry(account).deletePassword(); } catch { /* best effort */ }
     }
     return { ok: false, error: `OS keychain write failed: ${error instanceof Error ? error.message : "unknown"}`, status: 503 };
   }
   for (const apply of planned) apply();
-  resolvedCache.clear();
-  warnedAccounts.clear();
+  invalidateResolvedProviderKeyCache();
   saveConfigPreservingClaudeCode(config);
   return { ok: true, moved: written.length };
 }
@@ -211,7 +136,7 @@ export function restoreProviderKeyFromKeychain(config: OcxConfig, name: string):
     const account = keychainAccount(ref);
     if (resolved.has(account)) continue;
     let value: string | null = null;
-    try { value = entryFactory(PROVIDER_KEYCHAIN_SERVICE, account).getPassword(); } catch { value = null; }
+    try { value = providerKeychainEntry(account).getPassword(); } catch { value = null; }
     if (!value) return { ok: false, error: `OS keychain has no readable secret for ${ref}; config left unchanged`, status: 503 };
     resolved.set(account, value);
   }
@@ -220,10 +145,9 @@ export function restoreProviderKeyFromKeychain(config: OcxConfig, name: string):
   }
   if (isKeychainReference(provider.apiKey)) provider.apiKey = resolved.get(keychainAccount(provider.apiKey))!;
   for (const account of resolved.keys()) {
-    try { entryFactory(PROVIDER_KEYCHAIN_SERVICE, account).deletePassword(); } catch { /* best effort */ }
+    try { providerKeychainEntry(account).deletePassword(); } catch { /* best effort */ }
   }
-  resolvedCache.clear();
-  warnedAccounts.clear();
+  invalidateResolvedProviderKeyCache();
   saveConfigPreservingClaudeCode(config);
   return { ok: true, restored: resolved.size };
 }
diff --git a/src/providers/model-rename-migration.ts b/src/providers/model-rename-migration.ts
index 0606fe3dcd9..0c66e803de3 100644
--- a/src/providers/model-rename-migration.ts
+++ b/src/providers/model-rename-migration.ts
@@ -45,6 +45,52 @@ export interface ModelRename {
    * but lose the reasoning picker entirely.
    */
   dropReasoningEffortMap?: boolean;
+  /**
+   * Remove both the retired id and its replacement from `noReasoningModels`.
+   *
+   * Use this only when the rename also marks a capability change: carrying the old
+   * no-reasoning classification onto a newly adjustable alias would keep the picker
+   * disabled after the model id itself was repaired.
+   */
+  dropNoReasoningModels?: boolean;
+  /** Refresh exact registry defaults already saved under the replacement id. */
+  targetSeedRefresh?: {
+    contextWindow?: { from: number; to: number };
+    reasoning?: {
+      fromEfforts: readonly string[];
+      toEfforts: readonly string[];
+      defaultEffort: string;
+      effortMap: Readonly<Record<string, string>>;
+    };
+  };
+}
+
+const KIMI_K28_ALIAS = "kimi-for-coding";
+const KIMI_RETIRED_CODING_IDS = [
+  "kimi-k2.7-code",
+  "kimi-k2.7-code-highspeed",
+  "kimi-k2.6",
+  "kimi-k2.5",
+] as const;
+const KIMI_K28_TARGET_SEED_REFRESH: NonNullable<ModelRename["targetSeedRefresh"]> = {
+  contextWindow: { from: 262_144, to: 1_048_576 },
+  reasoning: {
+    fromEfforts: [],
+    toEfforts: ["low", "high", "max"],
+    defaultEffort: "max",
+    effortMap: { none: "none", low: "low", medium: "high", high: "high", xhigh: "max", max: "max" },
+  },
+};
+
+function kimiCodingRenames(provider: "kimi" | "kimi-code", endpoint: string): ModelRename[] {
+  return KIMI_RETIRED_CODING_IDS.map(from => ({
+    provider,
+    from,
+    to: KIMI_K28_ALIAS,
+    reason: `Moonshot retired the k2.x coding ids from the ${endpoint}; kimi-for-coding is the stable alias the endpoint still serves`,
+    dropNoReasoningModels: true,
+    targetSeedRefresh: KIMI_K28_TARGET_SEED_REFRESH,
+  }));
 }
 
 /**
@@ -65,6 +111,14 @@ export const MODEL_RENAMES: readonly ModelRename[] = [
     to: "qwen3.8-max",
     reason: "Alibaba shipped Qwen3.8-Max as stable and documents the preview endpoint as liable to be taken offline once preview concludes",
   },
+  // Kimi coding renames. Moonshot retired the k2.x ids from the subscription/coding
+  // endpoint when K2.8 Preview shipped (live /coding/v1/models lists only
+  // kimi-for-coding[-highspeed], k3, k3-256k); kimi-for-coding is the stable alias the
+  // endpoint still serves and currently routes to K2.8 Preview. The registry picker no
+  // longer seeds the retired ids, so a saved defaultModel naming one is a dead selection
+  // rather than a merely outdated one.
+  ...kimiCodingRenames("kimi", "subscription endpoint after K2.8 Preview shipped"),
+  ...kimiCodingRenames("kimi-code", "coding endpoint after K2.8 Preview shipped"),
   // Antigravity Flash generations. Google takes the previous Flash model off Cloud Code
   // Assist almost immediately when the next ships, so a saved 3.6 (or older 3.5) id is a
   // dead selection rather than a merely outdated one. Routing already redirects these ids
@@ -133,6 +187,18 @@ function renameInList(value: unknown, from: string, to: string): string[] | null
   return next;
 }
 
+function dropRenamedIdsFromList(
+  value: unknown,
+  from: string,
+  to: string,
+  dropStaleTarget: boolean,
+): string[] | null {
+  if (!Array.isArray(value)) return null;
+  const hasRetired = value.includes(from);
+  if (!hasRetired && !(dropStaleTarget && value.includes(to))) return null;
+  return value.filter(entry => typeof entry === "string" && entry !== from && entry !== to);
+}
+
 function renameInRecord(value: unknown, from: string, to: string): Record<string, unknown> | null {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const record = value as Record<string, unknown>;
@@ -160,6 +226,42 @@ function dropFromRecord(value: unknown, from: string): Record<string, unknown> |
   return next;
 }
 
+function sameStringArray(value: unknown, expected: readonly string[]): boolean {
+  return Array.isArray(value)
+    && value.length === expected.length
+    && value.every((entry, index) => entry === expected[index]);
+}
+
+function targetReasoningMatchesStaleSeed(row: Record<string, unknown>, rename: ModelRename): boolean {
+  const reasoning = rename.targetSeedRefresh?.reasoning;
+  const efforts = row.modelReasoningEfforts as Record<string, unknown> | undefined;
+  return !!reasoning && !!efforts && sameStringArray(efforts[rename.to], reasoning.fromEfforts);
+}
+
+/** Refresh only exact defaults emitted by the previous registry; preserve user overrides. */
+function refreshTargetSeed(row: Record<string, unknown>, rename: ModelRename): boolean {
+  const refresh = rename.targetSeedRefresh;
+  if (!refresh) return false;
+  let changed = false;
+
+  const windows = row.modelContextWindows as Record<string, unknown> | undefined;
+  if (windows && refresh.contextWindow && windows[rename.to] === refresh.contextWindow.from) {
+    windows[rename.to] = refresh.contextWindow.to;
+    changed = true;
+  }
+
+  const reasoning = refresh.reasoning;
+  const efforts = row.modelReasoningEfforts as Record<string, unknown> | undefined;
+  if (!reasoning || !efforts || !sameStringArray(efforts[rename.to], reasoning.fromEfforts)) return changed;
+  efforts[rename.to] = [...reasoning.toEfforts];
+
+  const defaults = (row.modelDefaultReasoningEfforts ??= {}) as Record<string, unknown>;
+  if (!(rename.to in defaults)) defaults[rename.to] = reasoning.defaultEffort;
+  const maps = (row.modelReasoningEffortMap ??= {}) as Record<string, unknown>;
+  if (!(rename.to in maps)) maps[rename.to] = { ...reasoning.effortMap };
+  return true;
+}
+
 /**
  * `provider/model` rows in the top-level `disabledModels` list.
  *
@@ -281,7 +383,14 @@ export function projectModelRenames(
     let touched = false;
     for (const field of MODEL_ID_LISTS) {
       if (isRegistryResidue(seed, field, row[field], rename)) continue;
-      const next = renameInList(row[field], rename.from, rename.to);
+      const next = rename.dropNoReasoningModels && field === "noReasoningModels"
+        ? dropRenamedIdsFromList(
+          row[field],
+          rename.from,
+          rename.to,
+          targetReasoningMatchesStaleSeed(row, rename),
+        )
+        : renameInList(row[field], rename.from, rename.to);
       if (!next) continue;
       row[field] = next;
       touched = true;
@@ -300,6 +409,7 @@ export function projectModelRenames(
       touched = true;
     }
     if (renameDisabledModels(config, rename)) touched = true;
+    if (touched && refreshTargetSeed(row, rename)) touched = true;
 
     if (touched) {
       changed = true;
diff --git a/src/providers/quota/vendor-probes-key.ts b/src/providers/quota/vendor-probes-key.ts
index 08544bc3c2c..6c44162ea43 100644
--- a/src/providers/quota/vendor-probes-key.ts
+++ b/src/providers/quota/vendor-probes-key.ts
@@ -1,6 +1,8 @@
 import { resolveProviderApiKey } from "../key-store";
 import { getProviderRegistryEntry, registryEntryForProviderDestination } from "../registry";
 import { isCanonicalOllamaCloudUrl } from "../../adapters/ollama-native-url";
+import { providerEgressFetchInit, resolveProviderEgress } from "../../lib/provider-egress";
+import { configuredOutboundFetch } from "../../lib/proxy-env";
 import { QUOTA_JSON_READ_FAILURE, asRecord, normalizePercent, normalizeResetAt, readQuotaJson, REQUEST_TIMEOUT_MS, toFiniteNumber } from "../quota-wire";
 import {
   AUTHORITATIVE_EMPTY_QUOTA,
@@ -15,6 +17,12 @@ import { getTokenForAccountQuotaProbe } from "./account-cache";
 import type { AccountQuotaMode, ProviderQuota, ProviderQuotaCreditsUsd } from "../quota-types";
 import type { OcxProviderConfig } from "../../types";
 
+// A quota probe must use the provider's inference route so it neither reports a false healthy path nor leaks a key through another exit.
+async function quotaFetch(providerName: string, config: OcxProviderConfig, url: string, init: RequestInit): Promise<Response> {
+  const egress = resolveProviderEgress({ providerName, provider: config, url });
+  return configuredOutboundFetch(url, { ...init, ...providerEgressFetchInit(egress) });
+}
+
 const KIMI_CODE_BASE_URL = "https://api.kimi.com/coding/v1";
 const KIMI_CODE_USAGE_URL = `${KIMI_CODE_BASE_URL}/usages`;
 const COMMAND_CODE_BASE_URL = "https://api.commandcode.ai";
@@ -144,10 +152,10 @@ async function fetchA6apiQuota(provider: string, config: OcxProviderConfig): Pro
   if (!apiKey) return null;
   const headers = { Accept: "application/json", Authorization: `Bearer ${apiKey}` } as const;
   const [subscriptionResponse, tokenResponse] = await Promise.all([
-    fetch(`${A6API_BASE_URL}/dashboard/billing/subscription`, {
+    quotaFetch(provider, config, `${A6API_BASE_URL}/dashboard/billing/subscription`, {
       headers, redirect: "error", signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
     }),
-    fetch(`${A6API_BASE_URL}/api/usage/token/`, {
+    quotaFetch(provider, config, `${A6API_BASE_URL}/api/usage/token/`, {
       headers, redirect: "error", signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
     }),
   ]);
@@ -241,7 +249,7 @@ async function fetchOpenCodeGoQuota(provider: string, config: OcxProviderConfig)
   if (!isCanonicalOpenCodeGoBaseUrl(config.baseUrl)) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const response = await fetch(OPENCODE_GO_USAGE_URL, {
+  const response = await quotaFetch(provider, config, OPENCODE_GO_USAGE_URL, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -287,7 +295,7 @@ async function fetchOpenRouterQuota(provider: string, config: OcxProviderConfig)
   if (!isCanonicalOpenRouterBaseUrl(config.baseUrl)) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const response = await fetch(`${OPENROUTER_BASE_URL}/key`, {
+  const response = await quotaFetch(provider, config, `${OPENROUTER_BASE_URL}/key`, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -337,7 +345,7 @@ async function fetchDeepSeekQuota(provider: string, config: OcxProviderConfig):
   if (!isCanonicalDeepSeekBaseUrl(config.baseUrl)) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const response = await fetch(`${DEEPSEEK_BASE_URL}/user/balance`, {
+  const response = await quotaFetch(provider, config, `${DEEPSEEK_BASE_URL}/user/balance`, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -382,7 +390,7 @@ async function fetchClineQuota(provider: string, config: OcxProviderConfig): Pro
   if (!isCanonicalClineBaseUrl(config.baseUrl)) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const response = await fetch(`${CLINE_BASE_URL}/api/v1/users/me/plan/usage-limits`, {
+  const response = await quotaFetch(provider, config, `${CLINE_BASE_URL}/api/v1/users/me/plan/usage-limits`, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -480,7 +488,7 @@ async function fetchOllamaCloudQuota(provider: string, config: OcxProviderConfig
   if (!isCanonicalOllamaCloudBaseUrl(effectiveBaseUrl)) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const response = await fetch(OLLAMA_CLOUD_USAGE_URL, {
+  const response = await quotaFetch(provider, config, OLLAMA_CLOUD_USAGE_URL, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -604,7 +612,7 @@ async function fetchZaiQuota(provider: string, config: OcxProviderConfig): Promi
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
   const authorization = monitorHost === ZAI_CN_BASE_URL ? apiKey : `Bearer ${apiKey}`;
-  const response = await fetch(`${monitorHost}/api/monitor/usage/quota/limit`, {
+  const response = await quotaFetch(provider, config, `${monitorHost}/api/monitor/usage/quota/limit`, {
     headers: { Accept: "application/json", Authorization: authorization },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -652,7 +660,7 @@ async function fetchMinimaxQuota(provider: string, config: OcxProviderConfig): P
   if (!apiKey) return null;
   const cnHost = normalizedBaseUrl(config.baseUrl)?.startsWith("https://api.minimaxi.com");
   const remainsUrl = cnHost ? "https://api.minimaxi.com/v1/token_plan/remains" : MINIMAX_REMAINS_URL;
-  const response = await fetch(remainsUrl, {
+  const response = await quotaFetch(provider, config, remainsUrl, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -695,7 +703,7 @@ async function fetchMoonshotQuota(provider: string, config: OcxProviderConfig):
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
   const host = normalizedBaseUrl(config.baseUrl)?.startsWith("https://api.moonshot.cn") ? "https://api.moonshot.cn/v1" : MOONSHOT_BASE_URL;
-  const response = await fetch(`${host}/users/me/balance`, {
+  const response = await quotaFetch(provider, config, `${host}/users/me/balance`, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -738,7 +746,7 @@ async function fetchVeniceQuota(provider: string, config: OcxProviderConfig): Pr
   if (!isCanonicalVeniceBaseUrl(config.baseUrl)) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const response = await fetch(`${VENICE_BASE_URL}/billing/balance`, {
+  const response = await quotaFetch(provider, config, `${VENICE_BASE_URL}/billing/balance`, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -781,7 +789,7 @@ async function fetchSyntheticQuota(provider: string, config: OcxProviderConfig):
   if (!isCanonicalSyntheticBaseUrl(config.baseUrl)) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const response = await fetch(`${SYNTHETIC_BASE_URL}/quotas`, {
+  const response = await quotaFetch(provider, config, `${SYNTHETIC_BASE_URL}/quotas`, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -831,7 +839,7 @@ async function fetchDeepInfraQuota(provider: string, config: OcxProviderConfig):
   if (!isCanonicalDeepInfraBaseUrl(config.baseUrl)) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const response = await fetch(`${DEEPINFRA_BASE_URL}/payment/checklist?compute_owed=true`, {
+  const response = await quotaFetch(provider, config, `${DEEPINFRA_BASE_URL}/payment/checklist?compute_owed=true`, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -873,7 +881,7 @@ async function fetchNeuralwattQuota(provider: string, config: OcxProviderConfig)
   if (!isCanonicalNeuralwattBaseUrl(config.baseUrl)) return null;
   const apiKey = resolveProviderApiKey(config.apiKey)?.trim();
   if (!apiKey) return null;
-  const response = await fetch(`${NEURALWATT_BASE_URL}/quota`, {
+  const response = await quotaFetch(provider, config, `${NEURALWATT_BASE_URL}/quota`, {
     headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -1050,7 +1058,7 @@ export async function fetchKimiQuota(provider: string, config: OcxProviderConfig
   // Never release credentials to a user-edited or lookalike provider host.
   if (!isCanonicalKimiCodeBaseUrl(config.baseUrl)) return null;
   if (!accessToken) return null;
-  const response = await fetch(KIMI_CODE_USAGE_URL, {
+  const response = await quotaFetch(provider, config, KIMI_CODE_USAGE_URL, {
     headers: { Accept: "application/json", Authorization: `Bearer ${accessToken}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -1077,9 +1085,14 @@ function parseCommandCodeWindow(value: unknown): { percent: number; resetAt?: nu
 }
 
 /** Soft-fail GET returning a parsed record, or null when unavailable. */
-async function fetchCommandCodeJson(url: string, bearer: string): Promise<Record<string, unknown> | null> {
+async function fetchCommandCodeJson(
+  provider: string,
+  config: OcxProviderConfig,
+  url: string,
+  bearer: string,
+): Promise<Record<string, unknown> | null> {
   try {
-    const response = await fetch(url, {
+    const response = await quotaFetch(provider, config, url, {
       headers: { Accept: "application/json", Authorization: `Bearer ${bearer}` },
       redirect: "error",
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -1097,12 +1110,14 @@ async function fetchCommandCodeJson(url: string, bearer: string): Promise<Record
  * pools' billing cycle, and `currentPeriodEnd` becomes expiresAt.
  */
 async function fetchCommandCodeSpend(
+  provider: string,
+  config: OcxProviderConfig,
   bearer: string,
   credits: Record<string, unknown> | null,
   orgQuery: string,
 ): Promise<ProviderQuotaCreditsUsd | undefined> {
   if (!credits) return undefined;
-  const subscriptionBody = await fetchCommandCodeJson(`${COMMAND_CODE_SUBSCRIPTIONS_URL}${orgQuery}`, bearer);
+  const subscriptionBody = await fetchCommandCodeJson(provider, config, `${COMMAND_CODE_SUBSCRIPTIONS_URL}${orgQuery}`, bearer);
   const subscription = asRecord(subscriptionBody?.data) ?? subscriptionBody;
   const periodStart = typeof subscription?.currentPeriodStart === "string" ? subscription.currentPeriodStart.trim() : "";
   // Unscoped /usage/summary is lifetime spend; mixing it with current-cycle
@@ -1110,7 +1125,7 @@ async function fetchCommandCodeSpend(
   if (!periodStart) return undefined;
   const sinceQuery = `${orgQuery ? "&" : "?"}since=${encodeURIComponent(periodStart)}`;
   const expiresAt = normalizeResetAt(subscription?.currentPeriodEnd);
-  const summaryBody = await fetchCommandCodeJson(`${COMMAND_CODE_USAGE_URL}${orgQuery}${sinceQuery}`, bearer);
+  const summaryBody = await fetchCommandCodeJson(provider, config, `${COMMAND_CODE_USAGE_URL}${orgQuery}${sinceQuery}`, bearer);
   const summary = asRecord(summaryBody?.data) ?? summaryBody;
   const used = toFiniteNumber(summary?.totalCost) ?? toFiniteNumber(summary?.totalMonthlyCredits);
   if (used === undefined || used < 0) return undefined;
@@ -1161,12 +1176,12 @@ export async function fetchCommandCodeQuota(provider: string, config: OcxProvide
   // Never release credentials to a user-edited or lookalike provider host.
   if (!isCanonicalCommandCodeBaseUrl(config.baseUrl)) return null;
   if (!bearer) return null;
-  const whoamiBody = await fetchCommandCodeJson(COMMAND_CODE_WHOAMI_URL, bearer);
+  const whoamiBody = await fetchCommandCodeJson(provider, config, COMMAND_CODE_WHOAMI_URL, bearer);
   const whoami = asRecord(whoamiBody?.data) ?? whoamiBody;
   const org = asRecord(whoami?.org);
   const orgId = typeof org?.id === "string" && org.id.trim() ? org.id.trim() : null;
   const orgQuery = orgId ? `?orgId=${encodeURIComponent(orgId)}` : "";
-  const response = await fetch(`${COMMAND_CODE_CREDITS_URL}${orgQuery}`, {
+  const response = await quotaFetch(provider, config, `${COMMAND_CODE_CREDITS_URL}${orgQuery}`, {
     headers: { Accept: "application/json", Authorization: `Bearer ${bearer}` },
     redirect: "error",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -1183,7 +1198,7 @@ export async function fetchCommandCodeQuota(provider: string, config: OcxProvide
   if (!credits && !limits) return null;
   const fiveHour = parseCommandCodeWindow(limits?.fiveHour);
   const weekly = parseCommandCodeWindow(limits?.weekly);
-  const creditsUsd = await fetchCommandCodeSpend(bearer, credits, orgQuery);
+  const creditsUsd = await fetchCommandCodeSpend(provider, config, bearer, credits, orgQuery);
   const quota: ProviderQuota = {
     ...(fiveHour ? {
       fiveHourPercent: fiveHour.percent,
diff --git a/src/providers/reasoning-metadata.ts b/src/providers/reasoning-metadata.ts
index 25b312eced8..f22ef8363ea 100644
--- a/src/providers/reasoning-metadata.ts
+++ b/src/providers/reasoning-metadata.ts
@@ -18,6 +18,7 @@
  * entitlement gap (muse-spark max needs an active Muse Code subscription) costs one rejected
  * request instead of failing every turn that selects that rung.
  */
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 // Leaf modules on purpose: this file is imported from reasoning-effort.ts, which combos/types.ts
@@ -26,6 +27,7 @@ import { join } from "node:path";
 import { atomicWriteFile } from "../config/atomic-write";
 import { getConfigDir } from "../config/paths";
 import type { OcxProviderConfig } from "../types";
+import { resolveProviderApiKey } from "./api-key-resolve";
 
 const FILENAME = "reasoning-metadata-cache.json";
 const SUPPORT_FILENAME = "reasoning-support-cache.json";
@@ -87,7 +89,7 @@ interface MetadataSnapshot {
 }
 
 interface SupportSnapshot {
-  version: 1;
+  version: 2;
   rows: Record<string, { effort: string; at: number; evidence?: string }>;
 }
 
@@ -159,11 +161,31 @@ function modelLadderValue(
   return undefined;
 }
 
-/** Opaque row key: providerKey|modelId|effort. None of the three may contain a pipe. */
-const KEY_SEP = "|";
+/**
+ * Bind learned capability to the credential that supplied the evidence. A digest keeps the
+ * credential itself out of the persisted cache while remaining stable across restarts and key
+ * selection. Providers without key-auth identity may use metadata, but cannot teach the cache.
+ *
+ * The hash input is the resolved wire credential, not the configured expression: the catalog
+ * path carries the raw config string in apiKey (a keychain:/env reference stays unresolved
+ * there), while the request path carries the resolved secret in apiKey and the configured
+ * expression in _apiKeyAttempt.reference. The request path hashes apiKey exactly as routed --
+ * the reference is only provenance, and re-resolving it at record time could read a credential
+ * rotated since the request was served. The catalog path resolves the configured expression,
+ * so both sides still bind learned refusals to the same wire credential, and a rotation behind
+ * a stable reference starts clean instead of inheriting the previous credential's refusals.
+ */
+function credentialIdentity(provider: OcxProviderConfig): string | undefined {
+  const resolved = provider._apiKeyAttempt?.reference !== undefined
+    ? provider.apiKey
+    : resolveProviderApiKey(provider.apiKey);
+  if (typeof resolved !== "string" || resolved.length === 0) return undefined;
+  return createHash("sha256").update(resolved).digest("hex");
+}
 
-function supportKey(providerKey: string, modelId: string, effort: string): string {
-  return providerKey + KEY_SEP + modelId + KEY_SEP + effort;
+/** JSON encoding avoids delimiter ambiguity in provider, model, and effort identifiers. */
+function supportKey(providerKey: string, credential: string, modelId: string, effort: string): string {
+  return JSON.stringify([providerKey, credential, modelId, effort]);
 }
 
 function loadSnapshot(): MetadataSnapshot | null {
@@ -220,7 +242,9 @@ function loadSupport(): Map<string, number> {
   }
   const rows = new Map<string, number>();
   const parsed = readJsonFile<SupportSnapshot>(SUPPORT_FILENAME);
-  if (parsed && parsed.version === 1 && parsed.rows && typeof parsed.rows === "object") {
+  // Version 1 rows had no credential identity and are deliberately invalidated: accepting them
+  // would preserve destination-wide refusals written by a lower-entitlement account.
+  if (parsed && parsed.version === 2 && parsed.rows && typeof parsed.rows === "object") {
     for (const [key, row] of Object.entries(parsed.rows)) {
       if (!row || typeof row.at !== "number") continue;
       if (nowMs - row.at > SUPPORT_TTL_MS) continue;
@@ -273,8 +297,9 @@ export function metadataDeclaresType(provider: OcxProviderConfig, modelId: strin
 
 export function isReasoningEffortLearnedUnsupported(provider: OcxProviderConfig, modelId: string, effort: string): boolean {
   const key = metadataProviderKey(provider);
-  if (!key) return false;
-  return loadSupport().has(supportKey(key, modelId, effort));
+  const credential = credentialIdentity(provider);
+  if (!key || !credential) return false;
+  return loadSupport().has(supportKey(key, credential, modelId, effort));
 }
 
 /**
@@ -291,10 +316,11 @@ export function dropLearnedUnsupportedReasoningEfforts(
 ): string[] {
   if (efforts.length === 0) return [...efforts];
   const key = metadataProviderKey(provider);
-  if (!key) return [...efforts];
+  const credential = credentialIdentity(provider);
+  if (!key || !credential) return [...efforts];
   const support = loadSupport();
   if (support.size === 0) return [...efforts];
-  const kept = efforts.filter(effort => !support.has(supportKey(key, modelId, effort)));
+  const kept = efforts.filter(effort => !support.has(supportKey(key, credential, modelId, effort)));
   return kept.length === 0 ? [...efforts] : kept;
 }
 
@@ -334,8 +360,9 @@ export function recordUnsupportedReasoningEffort(
   evidence?: string,
 ): boolean {
   const key = metadataProviderKey(provider);
-  if (!key || !effort) return false;
-  const rowKey = supportKey(key, modelId, effort);
+  const credential = credentialIdentity(provider);
+  if (!key || !credential || !effort) return false;
+  const rowKey = supportKey(key, credential, modelId, effort);
   const rows = loadSupport();
   if (rows.has(rowKey)) return false;
   rows.set(rowKey, Date.now());
@@ -346,15 +373,14 @@ export function recordUnsupportedReasoningEffort(
     try {
       const out: SupportSnapshot["rows"] = {};
       for (const [rowKey, at] of rows) {
-        const parts = rowKey.split(KEY_SEP);
         const evidenceText = supportEvidence.get(rowKey);
         out[rowKey] = {
-          effort: parts[2] ?? "",
+          effort: JSON.parse(rowKey)[3] ?? "",
           at,
           ...(evidenceText ? { evidence: evidenceText } : {}),
         };
       }
-      atomicWriteFile(join(getConfigDir(), SUPPORT_FILENAME), JSON.stringify({ version: 1, rows: out }) + "\n");
+      atomicWriteFile(join(getConfigDir(), SUPPORT_FILENAME), JSON.stringify({ version: 2, rows: out }) + "\n");
     } catch {
       // Best-effort persistence only.
     }
@@ -371,11 +397,10 @@ export function flushReasoningSupportCache(): void {
     const rows = loadSupport();
     const out: SupportSnapshot["rows"] = {};
     for (const [rowKey, at] of rows) {
-      const parts = rowKey.split(KEY_SEP);
       const evidenceText = supportEvidence.get(rowKey);
-      out[rowKey] = { effort: parts[2] ?? "", at, ...(evidenceText ? { evidence: evidenceText } : {}) };
+      out[rowKey] = { effort: JSON.parse(rowKey)[3] ?? "", at, ...(evidenceText ? { evidence: evidenceText } : {}) };
     }
-    atomicWriteFile(join(getConfigDir(), SUPPORT_FILENAME), JSON.stringify({ version: 1, rows: out }) + "\n");
+    atomicWriteFile(join(getConfigDir(), SUPPORT_FILENAME), JSON.stringify({ version: 2, rows: out }) + "\n");
   } catch {
     // Best-effort persistence only.
   }
diff --git a/src/providers/registry/entries-core.ts b/src/providers/registry/entries-core.ts
index f16f9f15687..3a956081ddc 100644
--- a/src/providers/registry/entries-core.ts
+++ b/src/providers/registry/entries-core.ts
@@ -55,7 +55,7 @@ import {
   deepseekThinkingEffortsFor,
   deepseekReasoningMapFor,
   KIMI_K3_STANDARD_CONTEXT_WINDOW,
-  KIMI_CODING_MODELS,
+  KIMI_CODING_LIVE_MODELS,
   KIMI_THINKING_MODELS,
   KIMI_CODING_NO_REASONING_MODELS,
   KIMI_CODING_K3_REASONING_EFFORTS,
@@ -444,8 +444,14 @@ export const PROVIDER_REGISTRY_CORE: readonly ProviderRegistryEntry[] = [
     oauthId: "kimi",
     jawcodeBundle: "moonshot",
     note: "Log in with your Kimi account",
-    models: KIMI_CODING_MODELS,
-    defaultModel: "kimi-k2.7-code",
+    // 260921: the retired k2.x ids stay out of the picker — live /coding/v1/models lists
+    // only kimi-for-coding[-highspeed], k3, k3-256k. Saved rows still naming kimi-k2.7-code
+    // are repaired by MODEL_RENAMES in model-rename-migration.ts.
+    models: KIMI_CODING_LIVE_MODELS,
+    // 260921: kimi-k2.7-code was retired from the subscription endpoint (live /models lists
+    // only kimi-for-coding[-highspeed], k3, k3-256k). The kimi-for-coding alias is the
+    // stable ID and currently routes to K2.8 Preview.
+    defaultModel: "kimi-for-coding",
     modelContextWindows: KIMI_CODING_MODEL_CONTEXT_WINDOWS,
     modelInputModalities: KIMI_CODING_MODEL_INPUT_MODALITIES,
     // K3 accepts low/high/max; Codex aliases are normalized by the model-scoped wire map.
@@ -1258,4 +1264,3 @@ export const PROVIDER_REGISTRY_CORE: readonly ProviderRegistryEntry[] = [
     note: "Serverless Inference subscription API. Live discovery exposes only kimi-k2-instruct because Vultr documents it as the sole tool-calling model.",
   },
 ];
-
diff --git a/src/providers/registry/entries-extended.ts b/src/providers/registry/entries-extended.ts
index a3ffe393c67..3dc0ff10b46 100644
--- a/src/providers/registry/entries-extended.ts
+++ b/src/providers/registry/entries-extended.ts
@@ -72,10 +72,10 @@ import {
   VOLCENGINE_PLAN_TEXT_ONLY_MODELS,
   ALIBABA_INTL_TOKEN_PLAN_INPUT_MODALITIES,
   KIMI_API_MODELS,
-  KIMI_CODING_MODELS,
   KIMI_THINKING_MODELS,
   KIMI_CODING_NO_REASONING_MODELS,
   KIMI_API_NO_REASONING_MODELS,
+  KIMI_CODING_LIVE_MODELS,
   KIMI_CODING_REASONING_EFFORTS,
   KIMI_CODING_DEFAULT_REASONING_EFFORTS,
   KIMI_CODING_REASONING_EFFORT_MAPS,
@@ -102,6 +102,11 @@ import {
   OPPER_MODEL_CONTEXT_WINDOWS,
   OPPER_MODEL_MAX_OUTPUT_TOKENS,
   OPPER_MODEL_INPUT_MODALITIES,
+  STEPFUN_MODELS,
+  STEPFUN_MODEL_CONTEXT_WINDOWS,
+  STEPFUN_MODEL_INPUT_MODALITIES,
+  STEPFUN_NO_VISION_MODELS,
+  STEPFUN_REASONING_EFFORTS,
 } from "./model-seeds";
 
 export const PROVIDER_REGISTRY_EXTENDED: readonly ProviderRegistryEntry[] = [
@@ -1008,13 +1013,17 @@ export const PROVIDER_REGISTRY_EXTENDED: readonly ProviderRegistryEntry[] = [
   },
   {
     id: "kimi-code", label: "Kimi (coding)", baseUrl: "https://api.kimi.com/coding/v1", adapter: "openai-chat", authKind: "key",
-    dashboardUrl: "https://platform.moonshot.cn/console/api-keys", defaultModel: "kimi-k2.7-code",
+    // 260921: kimi-k2.7-code was retired from the coding endpoint; the kimi-for-coding alias
+    // is the stable ID and currently routes to K2.8 Preview (same as the OAuth preset).
+    dashboardUrl: "https://platform.moonshot.cn/console/api-keys", defaultModel: "kimi-for-coding",
     modelSuffixBracketStrip: true,
     // API-key form of the same Kimi Code Plan transport; keep cache affinity identical to OAuth.
     promptCacheKey: true,
     // Keep Responses tool-result adjacency aligned with the OAuth preset (#4726).
     requiresAdjacentResponsesToolResults: true,
-    models: KIMI_CODING_MODELS,
+    // 260921: same live-id picker as the OAuth preset — the retired k2.x ids are repaired
+    // in saved configs by MODEL_RENAMES, not offered on fresh installs.
+    models: KIMI_CODING_LIVE_MODELS,
     modelContextWindows: KIMI_CODING_MODEL_CONTEXT_WINDOWS,
     modelInputModalities: KIMI_CODING_MODEL_INPUT_MODALITIES,
     noReasoningModels: KIMI_CODING_NO_REASONING_MODELS,
@@ -1361,5 +1370,21 @@ export const PROVIDER_REGISTRY_EXTENDED: readonly ProviderRegistryEntry[] = [
     noVisionModels: CODEBUDDY_CN_NO_VISION_MODELS,
     note: "Official CodeBuddy Code CLI (Tencent Cloud), China/internal environment. Uses the documented CODEBUDDY_API_KEY + headless CLI surface; never reads desktop sessions or private console endpoints. Region-isolated from codebuddy (Global); credentials are never exchanged across regions. v1 disables CLI tools (--tools \"\"): text/reasoning only for now. Requires `npm i -g @tencent-ai/codebuddy-code`. AUP/routing authorization flagged for maintainer security review.",
   },
+  {
+    id: "stepfun",
+    label: "StepFun",
+    baseUrl: "https://api.stepfun.com/v1",
+    adapter: "openai-chat",
+    authKind: "key",
+    dashboardUrl: "https://platform.stepfun.com",
+    defaultModel: "step-5-preview",
+    models: STEPFUN_MODELS,
+    liveModels: true,
+    preserveCustomDestination: true,
+    modelContextWindows: STEPFUN_MODEL_CONTEXT_WINDOWS,
+    modelInputModalities: STEPFUN_MODEL_INPUT_MODALITIES,
+    noVisionModels: STEPFUN_NO_VISION_MODELS,
+    reasoningEfforts: STEPFUN_REASONING_EFFORTS,
+    note: "StepFun (阶跃星辰) official OpenAI-compatible API.",
+  },
 ];
-
diff --git a/src/providers/registry/model-seeds.ts b/src/providers/registry/model-seeds.ts
index a1d9661395a..c5b672581da 100644
--- a/src/providers/registry/model-seeds.ts
+++ b/src/providers/registry/model-seeds.ts
@@ -637,16 +637,33 @@ export const ALIBABA_TOKEN_PLAN_PRESERVE_REASONING = [
 // entitlement tiers. Bare `k3` advertises the Moderato 256K ceiling; the local `[1m]`
 // alias advertises Allegretto's 1M ceiling and is stripped before the upstream request.
 // The separately billed Moonshot API uses `kimi-k3`.
+// 260921: `k3-256k` is the same K3 served under the explicit ceiling id (verified live
+// 260921: same 988-token scaffold and identity answer as bare `k3` on the same input).
 // Evidence: https://www.kimi.com/code/docs/en/kimi-code/models.html
 //           https://www.kimi.com/code/docs/en/kimi-code/error-reference.html
 export const KIMI_K3_STANDARD_CONTEXT_WINDOW = 262_144;
 export const KIMI_K3_1M_CONTEXT_WINDOW = 1_048_576;
-export const KIMI_CODING_K3_MODELS = ["k3", "k3[1m]"];
+export const KIMI_CODING_K3_MODELS = ["k3", "k3[1m]", "k3-256k"];
+// 260921 Kimi K2.8: `kimi-for-coding` is the stable subscription alias Moonshot re-points
+// at each coding release. Live GET /coding/v1/models lists only kimi-for-coding[-highspeed],
+// k3, k3-256k — the k2.x ids are retired from the subscription endpoint. Since K2.8 Preview
+// the alias serves an adjustable low/high/max thinking ladder (same wire map as k3) and a
+// 1M context ceiling. Verified live 260921: 350K-token request accepted; upstream rejects
+// with "model token limit: 1048576" beyond that.
+// Evidence: https://www.kimi.com/code/docs/en/kimi-code/models.html
+export const KIMI_CODING_K28_MODELS = ["kimi-for-coding"];
+export const KIMI_CODING_LIVE_MODELS = [...KIMI_CODING_K3_MODELS, ...KIMI_CODING_K28_MODELS];
+export const KIMI_CODING_ADJUSTABLE_THINKING_MODELS = [...KIMI_CODING_LIVE_MODELS];
 export const KIMI_LEGACY_API_MODELS = ["kimi-k2.7-code", "kimi-k2.7-code-highspeed", "kimi-k2.6", "kimi-k2.5"];
 export const KIMI_API_MODELS = ["kimi-k3", ...KIMI_LEGACY_API_MODELS];
-export const KIMI_CODING_MODELS = [...KIMI_CODING_K3_MODELS, ...KIMI_LEGACY_API_MODELS, "kimi-for-coding"];
-export const KIMI_THINKING_MODELS = KIMI_CODING_MODELS;
-export const KIMI_CODING_NO_REASONING_MODELS = KIMI_CODING_MODELS.filter(id => !KIMI_CODING_K3_MODELS.includes(id));
+// Every kimi coding preset record - picker, context windows, locked-parameter lists -
+// derives from the live ids only. seeding a retired id in a metadata list would re-arm
+// the model-rename migration on every boot (#5066): the list holds the retired id but
+// not the live alias, so the residue guard cannot skip it. The retired ids survive only
+// in KIMI_LEGACY_API_MODELS (moonshot platform API records); model-rename-migration
+// repairs saved rows still naming them.
+export const KIMI_THINKING_MODELS = KIMI_CODING_LIVE_MODELS;
+export const KIMI_CODING_NO_REASONING_MODELS = KIMI_CODING_LIVE_MODELS.filter(id => !KIMI_CODING_ADJUSTABLE_THINKING_MODELS.includes(id));
 export const KIMI_API_NO_REASONING_MODELS = KIMI_API_MODELS.filter(id => id !== "kimi-k3");
 export const KIMI_CODING_K3_REASONING_EFFORTS = ["low", "high", "max"];
 export const KIMI_CODING_K3_REASONING_EFFORT_MAP: Record<string, string> = {
@@ -658,19 +675,19 @@ export const KIMI_CODING_K3_REASONING_EFFORT_MAP: Record<string, string> = {
   max: "max",
 };
 export const KIMI_CODING_REASONING_EFFORTS = Object.fromEntries(
-  KIMI_CODING_MODELS.map(id => [id, KIMI_CODING_K3_MODELS.includes(id) ? KIMI_CODING_K3_REASONING_EFFORTS : []]),
+  KIMI_CODING_LIVE_MODELS.map(id => [id, KIMI_CODING_ADJUSTABLE_THINKING_MODELS.includes(id) ? KIMI_CODING_K3_REASONING_EFFORTS : []]),
 );
 export const KIMI_CODING_DEFAULT_REASONING_EFFORTS = Object.fromEntries(
-  KIMI_CODING_K3_MODELS.map(id => [id, "max"]),
+  KIMI_CODING_ADJUSTABLE_THINKING_MODELS.map(id => [id, "max"]),
 );
 export const KIMI_CODING_REASONING_EFFORT_MAPS = Object.fromEntries(
-  KIMI_CODING_K3_MODELS.map(id => [id, KIMI_CODING_K3_REASONING_EFFORT_MAP]),
+  KIMI_CODING_ADJUSTABLE_THINKING_MODELS.map(id => [id, KIMI_CODING_K3_REASONING_EFFORT_MAP]),
 );
 export const KIMI_API_REASONING_EFFORTS = Object.fromEntries(
   KIMI_API_MODELS.map(id => [id, id === "kimi-k3" ? ["max"] : []]),
 );
-export const KIMI_LOCKED_PARAMETER_MODELS = KIMI_CODING_MODELS;
-export const KIMI_AUTO_TOOL_CHOICE_ONLY_MODELS = ["kimi-k2.7-code", "kimi-k2.7-code-highspeed", "kimi-for-coding"];
+export const KIMI_LOCKED_PARAMETER_MODELS = KIMI_CODING_LIVE_MODELS;
+export const KIMI_AUTO_TOOL_CHOICE_ONLY_MODELS = ["kimi-for-coding"];
 export const KIMI_API_MODEL_CONTEXT_WINDOWS: Record<string, number> = Object.fromEntries(
   KIMI_API_MODELS.map(id => [id, id === "kimi-k3" ? KIMI_K3_1M_CONTEXT_WINDOW : 262_144]),
 );
@@ -758,10 +775,10 @@ export const NVIDIA_NIM_NO_VISION_MODELS = [
   "poolside/laguna-xs-2.1", "z-ai/glm-5.3", "z-ai/glm-5.2",
 ];
 export const KIMI_CODING_MODEL_CONTEXT_WINDOWS: Record<string, number> = Object.fromEntries(
-  KIMI_CODING_MODELS.map(id => [id, id === "k3[1m]" ? KIMI_K3_1M_CONTEXT_WINDOW : KIMI_K3_STANDARD_CONTEXT_WINDOW]),
+  KIMI_CODING_LIVE_MODELS.map(id => [id, (id === "k3[1m]" || KIMI_CODING_K28_MODELS.includes(id)) ? KIMI_K3_1M_CONTEXT_WINDOW : KIMI_K3_STANDARD_CONTEXT_WINDOW]),
 );
 export const KIMI_CODING_MODEL_INPUT_MODALITIES = Object.fromEntries(
-  KIMI_CODING_K3_MODELS.map(id => [id, ["text", "image"]]),
+  KIMI_CODING_ADJUSTABLE_THINKING_MODELS.map(id => [id, ["text", "image"]]),
 );
 export const NEURALWATT_REASONING_HISTORY_MODELS = [
   "glm-5.3", "glm-5.3-short", "glm-5.3-flash",
@@ -1026,3 +1043,25 @@ export const OPPER_TEXT_ONLY_MODELS = ["deepseek-v4-pro", "kimi-k3"];
 export const OPPER_MODEL_INPUT_MODALITIES: Record<string, string[]> = Object.fromEntries(
   OPPER_MODELS.map(id => [id, OPPER_TEXT_ONLY_MODELS.includes(id) ? ["text"] : ["text", "image"]]),
 );
+
+export const STEPFUN_MODELS = [
+  "step-5-preview",
+  "step-3.5-flash",
+  "step-3.7-flash",
+];
+
+export const STEPFUN_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  "step-5-preview": 1_000_000,
+  "step-3.5-flash": 256_000,
+  "step-3.7-flash": 256_000,
+};
+
+export const STEPFUN_MODEL_INPUT_MODALITIES: Record<string, string[]> = {
+  "step-5-preview": ["text", "image"],
+  "step-3.5-flash": ["text"],
+  "step-3.7-flash": ["text", "image"],
+};
+
+export const STEPFUN_NO_VISION_MODELS = ["step-3.5-flash"];
+
+export const STEPFUN_REASONING_EFFORTS = ["low", "medium", "high"];
diff --git a/src/providers/xai-transport.ts b/src/providers/xai-transport.ts
index e005abdf4e6..76582b07298 100644
--- a/src/providers/xai-transport.ts
+++ b/src/providers/xai-transport.ts
@@ -1,5 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import type { OcxProviderConfig } from "../types";
+import { isEgressTransparentExecutor, markEgressTransparentExecutor } from "../lib/provider-egress";
+import { configuredOutboundFetch } from "../lib/proxy-env";
 import { resolveGithubCopilotTransport } from "./github-copilot-transport";
 
 export const XAI_GROK_CLI_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
@@ -156,9 +158,18 @@ export function resolveProviderTransport(
   // transient retries reuse one id so the upstream can dedupe them. A rotated key resolves a
   // fresh transport, which gets its own id.
   const requestId = configuredRequestId ?? randomUUID();
-  const baseFetch = provider.fetch ?? globalThis.fetch;
+  // Without a configured executor the default routes through `configuredOutboundFetch` rather
+  // than the bare global fetch, so a per-provider SOCKS5 route reaches the SOCKS transport.
+  // Bare Bun fetch ignores a socks5 value, which would have sent the request unproxied while
+  // the configuration named a proxy.
+  const baseFetch = provider.fetch
+    ?? markEgressTransparentExecutor(((input, init) => configuredOutboundFetch(input, init)) as typeof globalThis.fetch);
   const attemptFetch = ((input, init) =>
     baseFetch(input, withGeneratedRequestId(init, requestId, stableHeaders))) as typeof globalThis.fetch;
+  // This wrapper only adds a header and forwards the init, so it carries a request-scoped proxy
+  // option through to whatever it wraps — but only if what it wraps carries it too. A
+  // configured executor owns its own routing and is not assumed to.
+  if (isEgressTransparentExecutor(baseFetch)) markEgressTransparentExecutor(attemptFetch);
 
   return {
     ...provider,
diff --git a/src/reasoning-effort.ts b/src/reasoning-effort.ts
index d97c96db996..a29ce1888e8 100644
--- a/src/reasoning-effort.ts
+++ b/src/reasoning-effort.ts
@@ -12,6 +12,14 @@ export const CODEX_REASONING_LEVELS: { effort: string; description: string }[] =
   { effort: "ultra", description: "Maximum reasoning with automatic task delegation" },
 ];
 
+/**
+ * One canonical rung. Catalog writers that hold a partially populated ladder derive their
+ * element type from this instead of restating `{ effort?: string }`: those restatements
+ * silently excluded `description`, so pushing a canonical rung into them is a type error
+ * that only surfaced once an unrelated import cycle through this module was broken.
+ */
+export type CodexReasoningLevel = (typeof CODEX_REASONING_LEVELS)[number];
+
 const CODEX_REASONING_ORDER = CODEX_REASONING_LEVELS.map(l => l.effort);
 const CODEX_REASONING_SET = new Set(CODEX_REASONING_ORDER);
 
diff --git a/src/responses/function-call-compat.ts b/src/responses/function-call-compat.ts
index c4888cf1f7a..fc26675dc16 100644
--- a/src/responses/function-call-compat.ts
+++ b/src/responses/function-call-compat.ts
@@ -33,6 +33,38 @@ function namespaceOf(value: unknown): string | undefined {
   return typeof value === "string" && value !== "functions" ? value : undefined;
 }
 
+/**
+ * Repair one provider spelling drift for Codex's flat shell bridge.
+ *
+ * This is schema-bound rather than a general alias: `input` is also a legitimate
+ * argument name for arbitrary caller and MCP tools. Only the exact bare
+ * `exec_command` declaration can establish that its sole string input has one faithful
+ * reading as the required string `cmd` member.
+ */
+function repairExecCommandInput(
+  argumentsText: string,
+  schema: FunctionCallRepairSchema,
+): string {
+  if (schema.namespace !== undefined || schema.name !== "exec_command") return argumentsText;
+  const parameters = schema.parameters;
+  if (!isObject(parameters) || parameters.type !== "object"
+    || !Array.isArray(parameters.required) || !parameters.required.includes("cmd")
+    || !isObject(parameters.properties) || !isObject(parameters.properties.cmd)
+    || parameters.properties.cmd.type !== "string") return argumentsText;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(argumentsText);
+  } catch {
+    return argumentsText;
+  }
+  if (!isObject(parsed)) return argumentsText;
+  const keys = Object.keys(parsed);
+  if (keys.length !== 1 || keys[0] !== "input" || typeof parsed.input !== "string") {
+    return argumentsText;
+  }
+  return JSON.stringify({ cmd: parsed.input });
+}
+
 function selectorAllows(
   selector: unknown,
   lowered: unknown,
@@ -131,7 +163,12 @@ function repairItem(item: unknown, schemas: FunctionCallRepairSchemas, completed
       if (unsafe) return item;
     } catch { return item; }
   }
-  const argumentsText = coerceIntegerToolArguments(raw || "{}", schema.parameters, schema.namespace ? undefined : schema.name);
+  const integerRepaired = coerceIntegerToolArguments(
+    raw || "{}",
+    schema.parameters,
+    schema.namespace ? undefined : schema.name,
+  );
+  const argumentsText = repairExecCommandInput(integerRepaired, schema);
   return argumentsText === raw ? item : { ...item, arguments: argumentsText };
 }
 
diff --git a/src/responses/inline-document.ts b/src/responses/inline-document.ts
new file mode 100644
index 00000000000..208d3f84d02
--- /dev/null
+++ b/src/responses/inline-document.ts
@@ -0,0 +1,58 @@
+import type { OcxDocumentContent } from "../types";
+
+const DATA_URL = /^data:([^;,]+)((?:;[^;,]*)*),(.*)$/s;
+const BASE64_PAYLOAD = /^[A-Za-z0-9+/]+={0,2}$/;
+
+/** The one marker vocabulary for an attached document, derived from what the part knows. */
+export function inlineDocumentMarker(filename: string | undefined): string {
+  return filename !== undefined && filename.length > 0 ? `[document: ${filename}]` : "[document]";
+}
+
+/**
+ * An inline document part from a `data:` URL, or `undefined` when there are no usable bytes.
+ *
+ * A reference with no payload — a `file_id`, a bare filename — is deliberately not a document:
+ * there is nothing to carry, and minting a part for it would claim an attachment the request
+ * never contained. Those keep the marker path they already had.
+ */
+export function inlineDocumentFromDataUrl(
+  fileData: string | undefined,
+  filename: string | undefined,
+): OcxDocumentContent | undefined {
+  if (typeof fileData !== "string" || fileData.length === 0) return undefined;
+  const match = DATA_URL.exec(fileData);
+  if (!match) return undefined;
+  const mediaType = match[1]!;
+  const payload = match[3]!;
+  if (!hasBase64Parameter(match[2] ?? "") || !BASE64_PAYLOAD.test(payload)) return undefined;
+  return {
+    type: "document",
+    text: inlineDocumentMarker(filename),
+    mediaType,
+    data: payload,
+    ...(filename !== undefined && filename.length > 0 ? { filename } : {}),
+  };
+}
+
+/** The `data:` URL spelling of a document part, for wires whose counterpart takes one. */
+export function inlineDocumentDataUrl(part: OcxDocumentContent): string {
+  return `data:${part.mediaType};base64,${part.data}`;
+}
+
+/**
+ * Whether this string is a `data:` URL this module would actually decode.
+ *
+ * The media-type scanner and this parser have to agree exactly. A looser scanner would exempt an
+ * attachment from the untranslated-media refusal that the parser then reduces to a marker, which
+ * is the silent drop the refusal exists to prevent. `;base64` must be a whole parameter token,
+ * not a substring of one: `;notbase64,` and `;x=base64,` are not base64 payloads.
+ */
+export function isInlineDocumentDataUrl(value: unknown): boolean {
+  if (typeof value !== "string" || value.length === 0) return false;
+  const match = DATA_URL.exec(value);
+  return match !== null && hasBase64Parameter(match[2] ?? "") && BASE64_PAYLOAD.test(match[3]!);
+}
+
+function hasBase64Parameter(parameters: string): boolean {
+  return parameters.split(";").includes("base64");
+}
diff --git a/src/responses/input-media.ts b/src/responses/input-media.ts
index 43f8db583ec..be4909198e9 100644
--- a/src/responses/input-media.ts
+++ b/src/responses/input-media.ts
@@ -1,3 +1,5 @@
+import { isInlineDocumentDataUrl } from "./inline-document";
+
 /** Input kinds for which the normalized request has no lossless content carrier. */
 export type UntranslatedInputMedia = "audio" | "file";
 
@@ -7,20 +9,47 @@ function isRecord(value: unknown): value is RecordValue {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-function mediaKind(value: unknown): UntranslatedInputMedia | undefined {
+/**
+ * Whether the position being scanned has a converter that builds a document part.
+ *
+ * Only user content does. A tool output, a system or assistant message, and a Chat `developer`
+ * message are all flattened to text by their converters, so exempting an attachment there would
+ * turn today's explicit refusal into the silent drop this scanner exists to prevent.
+ */
+type CarrierPosition = "user-content" | "flattened";
+
+function mediaKind(value: unknown, position: CarrierPosition): UntranslatedInputMedia | undefined {
   if (!isRecord(value)) return undefined;
   if (value.type === "input_audio" || value.type === "audio") return "audio";
-  if (value.type === "input_file" || value.type === "file" || value.type === "document") return "file";
+  if (value.type === "input_file" || value.type === "file" || value.type === "document") {
+    // A document that carries its own bytes has a lossless carrier in user content, so refusing
+    // it there would reject the very request #5212 exists to preserve. A reference with no
+    // payload has none anywhere: translated adapters cannot dereference a file_id or a remote
+    // source.
+    return position === "user-content" && carriesInlineDocumentBytes(value) ? undefined : "file";
+  }
   // A file-id-only image is not pixels: translated adapters cannot dereference it.
   if (value.type === "input_image" && typeof value.file_id === "string" && value.file_id.length > 0
       && !(typeof value.image_url === "string" && value.image_url.length > 0)) return "file";
   return undefined;
 }
 
-function contentMedia(content: unknown): UntranslatedInputMedia | undefined {
+/** Presence of a base64 payload only. No payload is read, decoded, copied or returned. */
+function carriesInlineDocumentBytes(value: RecordValue): boolean {
+  if (isInlineDocumentDataUrl(value.file_data)) return true;
+  // Chat Completions nests the payload under `file`.
+  if (isRecord(value.file) && isInlineDocumentDataUrl(value.file.file_data)) return true;
+  // Anthropic nests it under a base64 `source`.
+  return isRecord(value.source)
+    && value.source.type === "base64"
+    && typeof value.source.data === "string"
+    && value.source.data.length > 0;
+}
+
+function contentMedia(content: unknown, position: CarrierPosition): UntranslatedInputMedia | undefined {
   if (!Array.isArray(content)) return undefined;
   for (const part of content) {
-    const kind = mediaKind(part);
+    const kind = mediaKind(part, position);
     if (kind) return kind;
   }
   return undefined;
@@ -35,13 +64,16 @@ export function untranslatedResponsesInputMedia(body: unknown): UntranslatedInpu
   if (!isRecord(body) || !Array.isArray(body.input)) return undefined;
   for (const item of body.input) {
     if (!isRecord(item)) continue;
-    const direct = mediaKind(item);
+    const direct = mediaKind(item, "flattened");
     if (direct) return direct;
     if (item.type === "function_call_output" || item.type === "custom_tool_call_output") {
-      const kind = contentMedia(item.output);
+      const kind = contentMedia(item.output, "flattened");
       if (kind) return kind;
     } else if (item.type === "message" || item.type === undefined) {
-      const kind = contentMedia(item.content);
+      // `inputContentParts` runs for user and developer messages only; a system message is
+      // flattened to text by the parser.
+      const role = item.role;
+      const kind = contentMedia(item.content, role === "user" || role === "developer" ? "user-content" : "flattened");
       if (kind) return kind;
     }
   }
@@ -53,7 +85,9 @@ export function untranslatedChatInputMedia(body: unknown): UntranslatedInputMedi
   if (!isRecord(body) || !Array.isArray(body.messages)) return undefined;
   for (const message of body.messages) {
     if (!isRecord(message)) continue;
-    const kind = contentMedia(message.content);
+    // Only the `user` branch of the Chat projection builds content blocks. `system`,
+    // `developer`, `assistant` and `tool` all reduce their content to a string.
+    const kind = contentMedia(message.content, message.role === "user" ? "user-content" : "flattened");
     if (kind) return kind;
   }
   return undefined;
diff --git a/src/responses/muse-tool-name-alias.ts b/src/responses/muse-tool-name-alias.ts
index 1569c5785de..0208be86ba1 100644
--- a/src/responses/muse-tool-name-alias.ts
+++ b/src/responses/muse-tool-name-alias.ts
@@ -8,6 +8,25 @@ const MUSE_SAFE_NAME = /^[a-zA-Z0-9_-]+$/;
 
 export type MuseToolNameAliases = ReadonlyMap<string, string>;
 
+/**
+ * Final wire name for an identity before the Muse length rewrite.
+ *
+ * The alias map is request-local and already narrowed by `tool_choice`. Returning undefined for
+ * a contradictory map keeps downstream identity checks fail-closed instead of choosing one alias.
+ */
+export function museWireNameForOriginal(
+  originalName: string,
+  aliases: MuseToolNameAliases,
+): string | undefined {
+  let wireName: string | undefined;
+  for (const [candidate, original] of aliases) {
+    if (original !== originalName) continue;
+    if (wireName !== undefined && wireName !== candidate) return undefined;
+    wireName = candidate;
+  }
+  return wireName ?? originalName;
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
diff --git a/src/responses/parser-content.ts b/src/responses/parser-content.ts
index 7675a42f7e8..00b174320ca 100644
--- a/src/responses/parser-content.ts
+++ b/src/responses/parser-content.ts
@@ -1,4 +1,5 @@
 import type { OcxContentPart, OcxTextContent } from "../types";
+import { inlineDocumentFromDataUrl } from "./inline-document";
 
 export function isObj(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -90,8 +91,13 @@ export function inputContentParts(blocks: unknown): string | OcxContentPart[] {
       if (fileId) {
         parts.push({ type: "text", text: `[file: ${fileId}]` });
       } else if (fileData) {
-        // Inline file_data is often large base64. Preserve only its presence and name, never bytes.
-        parts.push({ type: "text", text: filename ? `[file: ${filename}]` : "[file: inline data]" });
+        // Inline bytes used to be reduced to a name here, which meant no adapter could forward
+        // the attachment even to a target that has a representation for it, and a title-only
+        // forward came back as a confident answer about a document the model never saw (#5212).
+        // The marker survives on the part for every wire that still cannot carry one. Bytes with
+        // no declared media type are not decodable into a document and keep the marker they had.
+        const document = inlineDocumentFromDataUrl(fileData, filename);
+        parts.push(document ?? { type: "text", text: filename ? `[file: ${filename}]` : "[file: inline data]" });
       }
       // A bare filename is not a file resource in the Responses schema, so omit it rather than
       // fabricating a "[file: ...]" marker for an attachment that was never sent.
diff --git a/src/responses/parser-tools.ts b/src/responses/parser-tools.ts
index 8812b0bbe66..763b061c8f6 100644
--- a/src/responses/parser-tools.ts
+++ b/src/responses/parser-tools.ts
@@ -61,6 +61,9 @@ export function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined
       parameters: normalizeParameters(t.parameters),
     };
     if (t.strict !== undefined) tool.strict = t.strict as boolean;
+    if (Array.isArray(t.allowed_callers)) {
+      tool.allowedCallers = (t.allowed_callers as unknown[]).filter((c): c is string => typeof c === "string");
+    }
     if (namespace) tool.namespace = namespace;
     out.push(tool);
   };
diff --git a/src/responses/parser.ts b/src/responses/parser.ts
index 396f2170b2e..51bb36f5245 100644
--- a/src/responses/parser.ts
+++ b/src/responses/parser.ts
@@ -245,7 +245,9 @@ export function parseRequest(
           case "system": {
             pendingReasoning.length = 0;
             const text = inputContentParts(msg.content);
-            const flat = typeof text === "string" ? text : text.map(p => (p.type === "text" ? p.text : "")).join("");
+            const flat = typeof text === "string"
+              ? text
+              : text.map(p => (p.type === "text" || p.type === "document" ? p.text : "")).join("");
             if (flat.length > 0) systemPrompt.push(flat);
             break;
           }
diff --git a/src/responses/schema.ts b/src/responses/schema.ts
index fced1a9e6e2..556bc9fd978 100644
--- a/src/responses/schema.ts
+++ b/src/responses/schema.ts
@@ -122,6 +122,9 @@ export const toolSchema = z.object({
   description: z.string().optional(),
   parameters: z.record(z.string(), z.unknown()).optional(),
   strict: z.boolean().optional(),
+  // Unknown keys are stripped here, so a field the parser is expected to read has to be
+  // declared: an undeclared allowed_callers never reached buildTools at all (#5210).
+  allowed_callers: z.array(z.string()).optional(),
 });
 
 const builtinToolSchema = z.object({ type: z.string() }).loose();
diff --git a/src/server/admission-model-scope.ts b/src/server/admission-model-scope.ts
new file mode 100644
index 00000000000..9390d2c3f34
--- /dev/null
+++ b/src/server/admission-model-scope.ts
@@ -0,0 +1,219 @@
+import type { DataPlaneAdmission } from "./auth-cors";
+import type { OcxApiKeyEntry, OcxConfig } from "../types";
+
+/**
+ * Per-admission-key model and provider scope.
+ *
+ * A hub that serves several clients with their own `ocx_data_…` keys needs a
+ * mail or cron key to be unable to spend a coding key's Grok or Claude quota.
+ * Hub-level model selection cannot express that: it hides a model from
+ * everyone or from no one (#5049).
+ *
+ * Two rules decide what this is and is not:
+ *
+ * A scope names DESTINATIONS, not selectors. It is evaluated against the
+ * resolved route — the provider and model a turn will actually bill — never
+ * against the string the client sent. A client-supplied label is not a
+ * permission subject: alias resolution, a combo pick, a policy fallback and a
+ * compaction override all rewrite that string, so a scope checked before them
+ * would authorize one destination and reach another.
+ *
+ * A scope is never management authority. It narrows which models an inference
+ * key may call and grants nothing else; reading or editing a scope stays on
+ * the management credential.
+ */
+export interface AdmissionModelScope {
+  /** Resolved provider names this key may reach. Empty means every provider. */
+  readonly providers: readonly string[];
+  /** Resolved destinations this key may reach. Empty means every model. */
+  readonly models: readonly string[];
+}
+
+/** The resolved destination a scope decision is made about. */
+export interface ScopedRoute {
+  readonly providerName: string;
+  readonly modelId: string;
+}
+
+const normalize = (value: string): string => value.trim().toLowerCase();
+
+/** Does this scope admit this provider on its own terms? */
+function providerAllowedByScope(scope: AdmissionModelScope, providerName: string): boolean {
+  return scope.providers.length === 0 || scope.providers.includes(normalize(providerName));
+}
+
+function normalizedList(values: readonly string[] | undefined): readonly string[] {
+  if (!Array.isArray(values)) return [];
+  const seen = new Set<string>();
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const normalized = normalize(value);
+    if (normalized) seen.add(normalized);
+  }
+  return [...seen];
+}
+
+/** Read the scope a stored key declares. An entry with neither list is unrestricted. */
+export function admissionModelScopeOf(entry: Pick<OcxApiKeyEntry, "allowedProviders" | "allowedModels">): AdmissionModelScope | undefined {
+  const providers = normalizedList(entry.allowedProviders);
+  const models = normalizedList(entry.allowedModels);
+  return providers.length === 0 && models.length === 0 ? undefined : { providers, models };
+}
+
+/**
+ * The scope that applies to one request, or undefined when nothing is scoped.
+ *
+ * Only a configured key carries a scope. The environment token and loopback
+ * admission have no stored record to attach one to, so they stay unrestricted;
+ * an operator who wants them narrowed issues a configured key instead.
+ */
+export function resolveAdmissionModelScope(
+  config: Pick<OcxConfig, "apiKeys">,
+  admission: DataPlaneAdmission | undefined,
+): AdmissionModelScope | undefined {
+  if (!admission || admission.kind !== "configured") return undefined;
+  const entry = (config.apiKeys ?? []).find(key => key.id === admission.keyId);
+  return entry ? admissionModelScopeOf(entry) : undefined;
+}
+
+/**
+ * Does this scope admit this resolved destination?
+ *
+ * The two lists are independent conditions and both must hold when both are
+ * declared: a key allowed one provider and one model may not reach that
+ * model on a different provider, which is what a combo child or a policy
+ * fallback would otherwise do while the requested selector stayed the same.
+ *
+ * A model entry matches the bare resolved model id or the fully qualified
+ * `provider/model` form, so an operator can scope one model everywhere or
+ * pin it to a single provider without a second field.
+ */
+export function routeAllowedByScope(
+  scope: AdmissionModelScope | undefined,
+  route: ScopedRoute,
+): boolean {
+  if (!scope) return true;
+  const model = normalize(route.modelId);
+  if (!providerAllowedByScope(scope, route.providerName)) return false;
+  if (scope.models.length === 0) return true;
+  return scope.models.includes(model) || scope.models.includes(normalize(route.providerName) + "/" + model);
+}
+
+/**
+ * A request that asked for a destination its key may not reach.
+ *
+ * Carries the selector the client sent rather than the destination it resolved
+ * to: the caller needs to know which of its own requests was refused, and a
+ * key that may not reach a provider has no business learning that an alias it
+ * named points there. The resolved destination goes to the server log.
+ */
+export class AdmissionModelDeniedError extends Error {
+  readonly requestedModel: string;
+  readonly deniedProvider: string;
+  readonly deniedModel: string;
+  constructor(requestedModel: string, route: ScopedRoute) {
+    super("model " + requestedModel + " is not allowed for this API key");
+    this.name = "AdmissionModelDeniedError";
+    this.requestedModel = requestedModel;
+    this.deniedProvider = route.providerName;
+    this.deniedModel = route.modelId;
+  }
+}
+
+/** Stable wire type for a scope refusal. */
+export const MODEL_NOT_ALLOWED_FOR_KEY = "model_not_allowed_for_key";
+
+/**
+ * How a refusal names a destination whose model nobody stated.
+ *
+ * This is message vocabulary, never a model id. It is not compared against
+ * `allowedModels`, so an operator who copies it out of a refusal into a list
+ * cannot grant "whatever the upstream picks" — the one destination a model list
+ * is unable to describe.
+ */
+export const UNNAMED_DESTINATION_MODEL = "(unnamed)";
+
+/** The HTTP body a scope refusal returns. 403: authenticated, not permitted. */
+export function admissionModelDeniedBody(error: AdmissionModelDeniedError): {
+  error: { type: string; message: string; model: string };
+} {
+  return {
+    error: {
+      type: MODEL_NOT_ALLOWED_FOR_KEY,
+      message: error.message,
+      model: error.requestedModel,
+    },
+  };
+}
+
+/**
+ * The refusal a scoped request gets: 403, not 404.
+ *
+ * The key authenticated; it simply may not reach this destination. Reporting
+ * "not found" instead would tell a client its credential is wrong and invite
+ * it to retry with another, and would make an operator's own denial
+ * indistinguishable from a typo in the model name.
+ */
+export function admissionModelDeniedResponse(error: AdmissionModelDeniedError): Response {
+  return new Response(JSON.stringify(admissionModelDeniedBody(error)), {
+    status: 403,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+/**
+ * Refuse a resolved destination this key may not reach.
+ *
+ * Every request-path site that produces or re-produces a route calls this, so
+ * the direct name, an alias, a combo child, a policy or subagent fallback and
+ * a compaction override are all checked at the point they become concrete
+ * rather than once at the front door.
+ */
+export function assertRouteAllowedByScope(
+  scope: AdmissionModelScope | undefined,
+  requestedModel: string,
+  route: ScopedRoute,
+): void {
+  if (!routeAllowedByScope(scope, route)) {
+    throw new AdmissionModelDeniedError(requestedModel, route);
+  }
+}
+
+/**
+ * The refusal a non-routed data-plane surface returns, or undefined when the
+ * destination is permitted.
+ *
+ * The Responses path resolves a route inside a try/catch and throws from the
+ * point the destination becomes concrete. The endpoints beside it -- images,
+ * audio, voice and the search relay -- have no router and no such boundary:
+ * each picks its own upstream inline and returns a Response. This is the same
+ * predicate against the same kind of resolved destination, shaped for that
+ * control flow, so a key that may not reach a provider is refused identically
+ * whichever surface it asked through.
+ *
+ * `destination.modelId` is undefined when nobody named the model this request
+ * will run: the relay copies the body and the upstream picks, or a voice join
+ * attaches to a call this process never recorded. A key with a model list is
+ * then refused, because no entry in that list can describe the destination; a
+ * key scoped only by provider is judged on the provider alone.
+ */
+export function admissionScopeDenial(
+  config: Pick<OcxConfig, "apiKeys">,
+  admission: DataPlaneAdmission | undefined,
+  requestedModel: string | undefined,
+  destination: { readonly providerName: string; readonly modelId: string | undefined },
+): Response | undefined {
+  const scope = resolveAdmissionModelScope(config, admission);
+  if (!scope) return undefined;
+  const allowed = destination.modelId === undefined
+    ? providerAllowedByScope(scope, destination.providerName) && scope.models.length === 0
+    : routeAllowedByScope(scope, { providerName: destination.providerName, modelId: destination.modelId });
+  if (allowed) return undefined;
+  return admissionModelDeniedResponse(new AdmissionModelDeniedError(
+    requestedModel ?? UNNAMED_DESTINATION_MODEL,
+    {
+      providerName: destination.providerName,
+      modelId: destination.modelId ?? UNNAMED_DESTINATION_MODEL,
+    },
+  ));
+}
diff --git a/src/server/audio-live.ts b/src/server/audio-live.ts
index 2f429ace694..ac3491d4110 100644
--- a/src/server/audio-live.ts
+++ b/src/server/audio-live.ts
@@ -11,7 +11,8 @@ import { LIVE_AUDIO_MODEL, resolveAudioUpstream, type AudioUpstream } from "./au
 import { registerTurn, unregisterTurn } from "./lifecycle";
 import {
   backendJsonBodyFromApiMultipart, buildLiveSidebandUpstreamWsUrl, forwardLiveUrl, keyedLiveUrl,
-  LIVE_CLIENT_PROTOCOL_HEADERS, LIVE_REQUEST_MAX_BYTES, LIVE_RESPONSE_MAX_BYTES, readBodyCapped,
+  LIVE_CLIENT_PROTOCOL_HEADERS, LIVE_REQUEST_MAX_BYTES, LIVE_RESPONSE_MAX_BYTES, liveSidebandModel,
+  readBodyCapped,
   type LiveSidebandTarget,
 } from "./live";
 import { LIVE_CALL_TTL_MS, LiveCallBindings, upstreamLiveCallId } from "./live-call-bindings";
@@ -115,6 +116,8 @@ export async function handleExternalLive(
       owner: options.client.owner, upstreamCallId: callId,
       joinStyle: frameless ? "frameless-path" : "realtime-query",
       providerName: relay.providerName,
+      // A join carries no model of its own; this is the one the call settled on.
+      model,
       accountId: context ? context.kind === "main" ? callerOwned ? undefined : MAIN_CODEX_ACCOUNT_ID : context.accountId : undefined,
       chatgptAccountId: new Headers(relay.headers).get("chatgpt-account-id") ?? undefined,
       keyedCredentialDigest: relay.keyed ? createHash("sha256").update(new Headers(relay.headers).get("authorization") ?? "").digest("hex") : undefined,
@@ -150,13 +153,16 @@ export async function resolveExternalLiveSocket(
   }
   let upstreamTarget = binding ? { style: binding.joinStyle, callId: binding.upstreamCallId } as LiveSidebandTarget : target;
   const frameless = upstreamTarget.style === "frameless-path" || upstreamTarget.style === "frameless-standalone";
-  let model = LIVE_AUDIO_MODEL;
   if (upstreamTarget.style === "frameless-standalone") {
     const query = new URLSearchParams(upstreamTarget.query);
     if (!query.has("model") || query.get("model") === "gpt-live-1") query.set("model", LIVE_AUDIO_MODEL);
-    model = query.get("model") ?? LIVE_AUDIO_MODEL;
     upstreamTarget = { ...upstreamTarget, query: query.toString() };
   }
+  // What this socket will actually run: the model a bound call settled on when
+  // this same key created it, or the one a standalone session forwards in its
+  // own query. Reading only the Frameless query left a Realtime standalone
+  // socket judged as the default while its query carried another model.
+  const model = binding?.model ?? liveSidebandModel(upstreamTarget) ?? LIVE_AUDIO_MODEL;
   const relay = await resolveAudioUpstream(client.headers, config, log, {
     admission: client.admission, model, lease: options.lease,
     signal: options.signal,
diff --git a/src/server/audio-upstream.ts b/src/server/audio-upstream.ts
index fa8bc4e9e7d..cefeaee2665 100644
--- a/src/server/audio-upstream.ts
+++ b/src/server/audio-upstream.ts
@@ -14,6 +14,7 @@ import { formatCodexProviderForLog } from "../codex/routing";
 import type { AdmissionLease } from "../lib/admission";
 import { captureExplicitOpenAiCallerAuth, resolveFirstUsableOpenAiSidecar, selectOpenAiImagesProvider } from "../providers/openai-sidecar";
 import type { OcxConfig } from "../types";
+import { admissionScopeDenial } from "./admission-model-scope";
 import {
   isProxyAdmissionSecret,
   resolveDataPlaneAdmissionSecret,
@@ -119,6 +120,18 @@ export async function resolveAudioUpstream(
         return formatErrorResponse(401, "authentication_error", "Selected audio account is unavailable");
       }
       validateForwardAdmissionCredential(selected, config);
+      // Every audio surface — file transcription, the dictation socket, voice
+      // call-create and the sideband join — resolves its upstream here, and
+      // `options.model` is the model that upstream will run, not a selector the
+      // caller can rewrite afterwards. One check therefore covers all of them.
+      const forwardDenial = admissionScopeDenial(config, options.admission, options.model, {
+        providerName: candidate.providerName,
+        modelId: options.model,
+      });
+      if (forwardDenial) {
+        releaseCodexAuthContextProbeLease(context);
+        return forwardDenial;
+      }
       log.provider = formatCodexProviderForLog(candidate.providerName, context.accountId, config);
       log.model = options.model;
       return {
@@ -136,6 +149,11 @@ export async function resolveAudioUpstream(
       const selected = new Headers(provider.headers);
       selected.set("authorization", `Bearer ${apiKey}`);
       validateForwardAdmissionCredential(selected, config);
+      const keyedDenial = admissionScopeDenial(config, options.admission, options.model, {
+        providerName,
+        modelId: options.model,
+      });
+      if (keyedDenial) return keyedDenial;
       log.provider = providerName;
       log.model = options.model;
       return {
diff --git a/src/server/auth-cors.ts b/src/server/auth-cors.ts
index c8f53c861ae..a0ef077dd5d 100644
--- a/src/server/auth-cors.ts
+++ b/src/server/auth-cors.ts
@@ -11,6 +11,7 @@ import {
   providerWebSearchBridgeConfigError,
   requestPacingConfigError,
   retryOn429PolicyConfigError,
+  retryOnResetPolicyConfigError,
   sanitizeModelCostsForDisplay,
 } from "../config";
 import {
@@ -29,6 +30,7 @@ import {
   upstreamHttpVersionConfigError,
 } from "../config/provider-validation";
 import { providerDestinationConfigError } from "../lib/destination-policy";
+import { providerEgressConfigError } from "../lib/provider-egress";
 import { redactSecretString } from "../lib/redact";
 import { DECLARABLE_HOSTED_TOOL_TYPES } from "../responses/hosted-tool-policy";
 import { effectiveGoogleMode, getProviderRegistryEntry, providerCodexAccountMode, providerMatchesRegistryTransport, registryEntryForProviderDestination } from "../providers/registry";
@@ -722,6 +724,10 @@ export function providerManagementConfigError(
     delete canonicalCandidate.modelCosts;
     // requestPacing is a user-owned transport overlay, not part of the canonical seed.
     delete canonicalCandidate.requestPacing;
+    // retryOnReset is the same kind of overlay: it tunes how this provider's own Responses
+    // sends recover, not what the canonical forward seed is. Validated below
+    // (retryOnResetPolicyConfigError).
+    delete canonicalCandidate.retryOnReset;
     // Context windows are the same kind of user-owned overlay as requestPacing: the operator
     // narrowing what their own native rows advertise. They can only ever LOWER the measured
     // window (see nativeOpenAiContextWindow), so admitting them cannot widen what the proxy
@@ -768,6 +774,10 @@ export function providerManagementConfigError(
     // it before it reaches the management API response.
     return `provider ${JSON.stringify(redactSecretString(name))} ${retryOn429Error}`;
   }
+  const retryOnResetError = retryOnResetPolicyConfigError(raw.retryOnReset);
+  if (retryOnResetError) {
+    return `provider ${JSON.stringify(redactSecretString(name))} ${retryOnResetError}`;
+  }
   const requestPacingError = requestPacingConfigError(raw.requestPacing);
   if (requestPacingError) {
     return `provider ${JSON.stringify(redactSecretString(name))} ${requestPacingError}`;
@@ -780,6 +790,13 @@ export function providerManagementConfigError(
   if (upstreamHttpVersionError) {
     return `provider ${JSON.stringify(redactSecretString(name))} ${upstreamHttpVersionError}`;
   }
+  // Per-provider egress shares one definition with the transports and the config loader, so a
+  // value the dashboard accepts is one a request can actually leave by. The message never
+  // echoes the value: a proxy URL routinely embeds `user:password@`.
+  const egressError = providerEgressConfigError(typed);
+  if (egressError) {
+    return `provider ${JSON.stringify(redactSecretString(name))} ${egressError}`;
+  }
   const modelCostsError = providerModelCostsConfigError(raw.modelCosts);
   if (modelCostsError) {
     // The provider name is caller-controlled and can be token-shaped; redact and JSON-escape
@@ -947,6 +964,13 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   decodesNativeCompactionBlobs: "editor",
   allowEncryptedV2AgentTasks: "editor",
   allowPrivateNetwork: "editor",
+  // A proxy URL routinely embeds `user:password@`, so it never reaches the dashboard DTO and
+  // the editor may not write it. `ocx config set` and the config file remain the way to set
+  // it, which is the same boundary `apiKey` sits behind and for the same reason.
+  proxy: "redacted",
+  // A bypass list names destinations, carries no credential, and is only meaningful next to a
+  // route the operator can already see.
+  noProxy: "editor",
   upstreamHttpVersion: "editor",
   upstreamWebsocket: "editor",
   directGeminiWireRenames: "editor",
@@ -1024,6 +1048,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   pinParallelToolCallsFalse: "editor",
   terminalContinuationGuard: "editor",
   openaiChatEofTolerance: "editor",
+  foldDeveloperRoleToSystem: "editor",
   promptCacheKey: "editor",
   chatServiceTier: "editor",
   responsesItemIdRepair: "editor",
@@ -1033,6 +1058,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   showThinkingSummary: "editor",
   retryOn429: "editor",
   transientRetryOn5xx: "editor",
+  retryOnReset: "editor",
   reasoningSplitModels: "editor",
   reasoningDetailsModels: "editor",
   thinkingToggleModels: "editor",
diff --git a/src/server/chat-completions.ts b/src/server/chat-completions.ts
index 8a611e70e4b..3cb6c9a3798 100644
--- a/src/server/chat-completions.ts
+++ b/src/server/chat-completions.ts
@@ -22,6 +22,15 @@ import {
 import { classifyError, cyberPolicyErrorType, CYBER_POLICY_ERROR_CODE, isCyberPolicyCode } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
 import { resolveClientRetryAfter } from "../lib/retry-after";
+import {
+  applyReplayRefusalClientHeaders,
+  isReplayRefusalCode,
+  isReplayRefusalResponse,
+  REPLAY_REFUSAL_CLIENT_HEADERS,
+  REPLAY_REFUSED_STATUS,
+  retainReplayRefusal,
+  UPSTREAM_RESET_REPLAY_REFUSED_CODE,
+} from "../lib/upstream-retry";
 import { estimateTokens } from "../lib/token-estimate";
 import { captureRouteStaticPolicy, NoEligiblePolicyCandidateError, UnknownRoutingPolicyError, routeModel } from "../router";
 import { evidenceFromBody } from "../routing/request-evidence";
@@ -46,6 +55,12 @@ import { providerConsumesCallerAuthorization } from "../providers/caller-authori
 import { captureExplicitOpenAiCallerAuth } from "../providers/openai-sidecar";
 import { captureCallerDirectAuth } from "../providers/caller-authorization";
 import type { AdmissionLease } from "../lib/admission";
+import {
+  admissionModelDeniedResponse,
+  AdmissionModelDeniedError,
+  assertRouteAllowedByScope,
+  resolveAdmissionModelScope,
+} from "./admission-model-scope";
 import type { DataPlaneAdmission } from "./auth-cors";
 import { tryClaimNativeMainProfileForTurn } from "../codex/native-main-admission";
 import {
@@ -150,6 +165,10 @@ async function handleChatCompletionsWithBudget(
   let chatNativeRoute: ReturnType<typeof routeModel> | null = null;
   try {
     const route = routeModel(config, chatBody.model as string, evidenceFromBody(chatBody));
+    // The native Chat lane sends without re-entering the Responses path, so it
+    // has to apply the key's scope itself. Translated traffic is checked where
+    // every rewrite converges instead.
+    assertRouteAllowedByScope(resolveAdmissionModelScope(config, logIds?.admission), requestedModel, route);
     // Preserve the routed destination for Go recognition, then settle the wire before
     // deriving protocol-scoped affinity. Recognition must not inspect the flipped adapter.
     const routedProvider = route.provider;
@@ -182,6 +201,11 @@ async function handleChatCompletionsWithBudget(
     // effort, failover, and per-attempt telemetry run before any native Chat send.
     if (!route.combo && !effortRow && isNativeChatRouteEligible(route, chatBody, config)) chatNativeRoute = route;
   } catch (err) {
+    if (err instanceof AdmissionModelDeniedError) {
+      logCtx.requestedModel = requestedModel;
+      if (logIds) addFinalRequestLog(logIds.requestId, logIds.start, logCtx, 403, { closeReason: "non_stream" });
+      return admissionModelDeniedResponse(err);
+    }
     if (err instanceof UnknownRoutingPolicyError) {
       logCtx.requestedModel = requestedModel;
       if (logIds) addFinalRequestLog(logIds.requestId, logIds.start, logCtx, 404, { closeReason: "non_stream" });
@@ -404,9 +428,19 @@ async function handleChatCompletionsWithBudget(
           : "invalid_request_error"),
       message,
     );
+    // The same verdict the native Chat surface reads, from the same two places: the response
+    // this wrapper still holds, and the code a body kept through an intermediate formatter.
+    // Not the status -- a refusal and a real rate limit are both 429, which is the whole
+    // reason this surface used to report one as the other.
+    const replayRefusal = isReplayRefusalResponse(upstream) || isReplayRefusalCode(upstreamCode);
     if (isCyberPolicyCode(upstreamCode) || classified.code === CYBER_POLICY_ERROR_CODE) {
       classified.code = CYBER_POLICY_ERROR_CODE;
       classified.type = cyberPolicyErrorType(upstreamType);
+    } else if (replayRefusal) {
+      // 429 classifies as a rate limit, which already carries a code, so the empty-code branch
+      // below could never restore this one -- the translated client was told the provider
+      // throttled the turn, and handed a two-second wait to send it again.
+      classified.code = UPSTREAM_RESET_REPLAY_REFUSED_CODE;
     } else if (upstreamCode === "model_not_found") {
       // Structured model_not_found must win over classifyError's generic remaps.
       classified.code = "model_not_found";
@@ -414,8 +448,10 @@ async function handleChatCompletionsWithBudget(
     } else if (upstreamCode !== undefined && upstreamCode !== null && classified.code == null) {
       classified.code = upstreamCode;
     }
-    const status = isCyberPolicyCode(classified.code) ? 400 : upstream.status;
-    const retryAfter = isCyberPolicyCode(classified.code)
+    const status = isCyberPolicyCode(classified.code) ? 400
+      : replayRefusal ? REPLAY_REFUSED_STATUS
+      : upstream.status;
+    const retryAfter = isCyberPolicyCode(classified.code) || replayRefusal
       ? undefined
       : resolveClientRetryAfter({
         status: upstream.status,
@@ -434,9 +470,12 @@ async function handleChatCompletionsWithBudget(
       headers: {
         "Content-Type": "application/json",
         ...(retryAfter ? { "Retry-After": retryAfter } : {}),
+        ...(replayRefusal ? REPLAY_REFUSAL_CLIENT_HEADERS : {}),
       },
     });
+    if (replayRefusal) retainReplayRefusal(rewritten);
     return logIds
+      // Deferred logging re-wraps this response and carries the verdict with it.
       ? responseWithDeferredRequestLog(rewritten, logIds.requestId, logIds.start, logCtx)
       : rewritten;
   }
@@ -503,11 +542,25 @@ async function handleChatCompletionsWithBudget(
     } else if (isCyberPolicyCode(error?.code) || classified.code === CYBER_POLICY_ERROR_CODE) {
       classified.code = CYBER_POLICY_ERROR_CODE;
       classified.type = cyberPolicyErrorType(error?.type);
+    } else if (isReplayRefusalCode(error?.code)) {
+      // The refusal can also arrive as a failed Responses envelope rather than a non-2xx.
+      // Reporting that as the 502 below would invite the four resends the refusal prevents.
+      classified.code = UPSTREAM_RESET_REPLAY_REFUSED_CODE;
     } else if (error?.code === "model_not_found") {
       // Same deliberate preserve as the non-OK path: structured code beats generic classify.
       classified.code = "model_not_found";
       classified.type = "invalid_request_error";
     }
+    if (isReplayRefusalCode(classified.code)) {
+      const refusal = chatCompletionsErrorResponse(
+        REPLAY_REFUSED_STATUS, message, classified.type, classified.code,
+      );
+      const headers = new Headers(refusal.headers);
+      applyReplayRefusalClientHeaders(headers);
+      return finishJson(retainReplayRefusal(
+        new Response(refusal.body, { status: refusal.status, headers }),
+      ));
+    }
     return finishJson(chatCompletionsErrorResponse(
       classified.code === "translation_buffer_limit"
         ? 502
diff --git a/src/server/chat-native.ts b/src/server/chat-native.ts
index 69361aa9f93..71ef323ebf5 100644
--- a/src/server/chat-native.ts
+++ b/src/server/chat-native.ts
@@ -29,6 +29,9 @@ import {
   isReplayRefusalCode,
   isReplayRefusalResponse,
   prepareSameTarget429Wait,
+  REPLAY_REFUSAL_CLIENT_HEADERS,
+  REPLAY_REFUSED_STATUS,
+  retainReplayRefusal,
   type UpstreamSendRecovery,
   UPSTREAM_RESET_REPLAY_REFUSED_CODE,
 } from "../lib/upstream-retry";
@@ -359,6 +362,11 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
                   applyUpstreamRecoveryInit({
                     ...init, method: request.method, headers, body: request.body,
                   }, transportRecovery),
+                  // Reselection can replace the provider transport and the wire shape, so the
+                  // egress route is bound to the provider this send actually uses. Omitting it
+                  // here would let a provider transport bypass its configured route entirely,
+                  // because that transport wins over the executor that carries the binding.
+                  { providerName: route.providerName, provider: activeProvider },
                 );
                 if (!dispatched.ok) await recordKeyAttemptFailure(logCtx, dispatched, init.signal ?? upstream.signal);
                 return dispatched;
@@ -492,10 +500,13 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
           : response.status >= 500 ? "server_error" : "invalid_request_error"),
       clientMessage,
     );
+    // The verdict is read once, from the response that carries it and from the code a
+    // re-wrapped body kept -- never from the status, which a real rate limit shares.
+    const replayRefusal = isReplayRefusalResponse(response) || isReplayRefusalCode(upstreamCode);
     if (isCyberPolicyCode(upstreamCode) || classified.code === CYBER_POLICY_ERROR_CODE) {
       classified.code = CYBER_POLICY_ERROR_CODE;
       classified.type = cyberPolicyErrorType(upstreamType);
-    } else if (isReplayRefusalResponse(response) || isReplayRefusalCode(upstreamCode)) {
+    } else if (replayRefusal) {
       // 429 classifies as a rate limit and a rate limit already carries a code, so the branch
       // below -- which only fills an EMPTY code -- could never restore this one. Without it the
       // client is told the provider throttled the turn, when what happened is that this proxy
@@ -507,11 +518,13 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
     } else if (upstreamCode !== undefined && upstreamCode !== null && classified.code == null) {
       classified.code = upstreamCode;
     }
-    const status = isCyberPolicyCode(classified.code) ? 400 : response.status;
+    const status = isCyberPolicyCode(classified.code) ? 400
+      : replayRefusal ? REPLAY_REFUSED_STATUS
+      : response.status;
     // A refusal this proxy made has no wait to report. Synthesizing one here would hand the
     // client the default two-second retry for a rate limit that never happened, which is the
     // duplicate send the refusal exists to prevent.
-    const retryAfter = isCyberPolicyCode(classified.code) || isReplayRefusalCode(classified.code)
+    const retryAfter = isCyberPolicyCode(classified.code) || replayRefusal
       ? undefined
       : resolveClientRetryAfter({
         status: response.status,
@@ -519,13 +532,15 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
         upstreamRetryAfter: response.headers.get("retry-after"),
       });
     finishLog(status, classified.message);
-    return new Response(JSON.stringify(chatCompletionsErrorBody(status, classified.message, classified.type, classified.code)), {
+    const rewritten = new Response(JSON.stringify(chatCompletionsErrorBody(status, classified.message, classified.type, classified.code)), {
       status,
       headers: {
         "Content-Type": "application/json",
         ...(retryAfter ? { "Retry-After": retryAfter } : {}),
+        ...(replayRefusal ? REPLAY_REFUSAL_CLIENT_HEADERS : {}),
       },
     });
+    return replayRefusal ? retainReplayRefusal(rewritten) : rewritten;
   }
 
   const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
diff --git a/src/server/claude-messages.ts b/src/server/claude-messages.ts
index b73199dd15a..93c9318d4b1 100644
--- a/src/server/claude-messages.ts
+++ b/src/server/claude-messages.ts
@@ -7,6 +7,12 @@
  * unchanged. The Responses output (SSE or JSON) is converted back to Anthropic shape.
  */
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
+import {
+  admissionModelDeniedResponse,
+  AdmissionModelDeniedError,
+  assertRouteAllowedByScope,
+  resolveAdmissionModelScope,
+} from "./admission-model-scope";
 import { jsonUtf8Bytes } from "../lib/json-byte-size";
 import { sseFieldValue } from "../lib/sse-decoder";
 import { enforceAnthropicImageLimits, sniffImageDimensions } from "../adapters/anthropic-image-guard";
@@ -18,7 +24,14 @@ import { recordDesktopRequest } from "../claude/desktop-health";
 import { stripOneMillionMarker } from "../claude/context-windows";
 import { captureClaudeInbound } from "../claude/inbound-debug";
 import { analyzeClaudeCompatibility, isClaudeCompatibilityMode } from "../claude/compatibility";
-import { isTransientUpstreamStatus } from "../lib/upstream-retry";
+import {
+  applyReplayRefusalClientHeaders,
+  carryReplayRefusal,
+  isReplayRefusalResponse,
+  isTransientUpstreamStatus,
+  REPLAY_REFUSED_STATUS,
+  UPSTREAM_RESET_REPLAY_REFUSED_CODE,
+} from "../lib/upstream-retry";
 import { resolveClientRetryAfter } from "../lib/retry-after";
 import {
   anthropicErrorBody,
@@ -815,6 +828,13 @@ async function handleClaudeMessagesWithBudget(
   // verified live 2026-07-11). Strip them for that route; routed providers keep them.
   try {
     const route = routeModel(config, internalBody.model as string, evidenceFromBody(internalBody));
+    // Same reason as the native Chat lane: this route can be sent from here, so
+    // the key's scope is applied before the wire is settled.
+    assertRouteAllowedByScope(
+      resolveAdmissionModelScope(config, logIds?.admission),
+      String(internalBody.model ?? ""),
+      route,
+    );
     // Settle the wire once so the sampling decision below reads the effective
     // adapter rather than the provider-wide default (#404).
     route.staticPolicy = captureRouteStaticPolicy(
@@ -847,6 +867,11 @@ async function handleClaudeMessagesWithBudget(
       if (ladder !== undefined && ladder.length === 0) delete internalBody.reasoning;
     }
   } catch (err) {
+    if (err instanceof AdmissionModelDeniedError) {
+      logCtx.requestedModel = requestedModel;
+      if (logIds) addFinalRequestLog(logIds.requestId, logIds.start, logCtx, 403, { closeReason: "non_stream" });
+      return admissionModelDeniedResponse(err);
+    }
     if (err instanceof UnknownRoutingPolicyError) {
       logCtx.requestedModel = requestedModel;
       if (logIds) addFinalRequestLog(logIds.requestId, logIds.start, logCtx, 404, { closeReason: "non_stream" });
@@ -961,6 +986,9 @@ async function handleClaudeMessagesWithBudget(
   const response = logIds ? responseWithDeferredRequestLog(upstream, logIds.requestId, logIds.start, logCtx) : upstream;
 
   if (!response.ok) {
+    // Read the shared provenance verdict before consuming and re-wrapping the body. A refusal
+    // and an ordinary provider rate limit are both 429, so the status cannot distinguish them.
+    const replayRefusal = isReplayRefusalResponse(response);
     // Re-shape the OpenAI-style error envelope into the Anthropic one, preserving status.
     let message = `upstream error (${response.status})`;
     try {
@@ -975,14 +1003,16 @@ async function handleClaudeMessagesWithBudget(
       }
     } catch { /* keep fallback message */ }
     const upstreamRetryAfter = response.headers.get("retry-after");
-    const retryAfter = resolveClientRetryAfter({
-      status: response.status,
-      message,
-      upstreamRetryAfter,
-    })
-      // Instant-retry "0" is a valid client directive but rejected by cooldown parsers.
-      // Preserve it so it still wins over the transient "2" fallback (claude-529 mapping).
-      ?? (upstreamRetryAfter?.trim() === "0" ? "0" : undefined);
+    const retryAfter = replayRefusal
+      ? undefined
+      : resolveClientRetryAfter({
+          status: response.status,
+          message,
+          upstreamRetryAfter,
+        })
+        // Instant-retry "0" is a valid client directive but rejected by cooldown parsers.
+        // Preserve it so it still wins over the transient "2" fallback (claude-529 mapping).
+        ?? (upstreamRetryAfter?.trim() === "0" ? "0" : undefined);
     // Transient upstream 5xx (already retried pre-stream, 010): reclassify as Anthropic
     // 529 overloaded_error so the Claude Code client applies its built-in backoff retry
     // instead of dying on a fatal api_error (260716 sol-builder incident). The request
@@ -993,16 +1023,24 @@ async function handleClaudeMessagesWithBudget(
     const nativeMainFence = response.status === 503
       && upstreamRetryAfter?.trim() === "1"
       && message === CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE;
-    const transient = !nativeMainFence && isTransientUpstreamStatus(response.status);
-    const outStatus = nativeMainFence ? 503 : transient ? 529 : response.status;
-    const out = new Response(JSON.stringify(anthropicErrorBody(outStatus, message)), {
+    const transient = !replayRefusal && !nativeMainFence && isTransientUpstreamStatus(response.status);
+    const outStatus = replayRefusal
+      ? REPLAY_REFUSED_STATUS
+      : nativeMainFence ? 503 : transient ? 529 : response.status;
+    const outHeaders = new Headers({ "Content-Type": "application/json" });
+    if (retryAfter) outHeaders.set("Retry-After", retryAfter);
+    else if (transient) outHeaders.set("Retry-After", "2");
+    if (replayRefusal) applyReplayRefusalClientHeaders(outHeaders);
+    const out = new Response(JSON.stringify(anthropicErrorBody(
+      outStatus,
+      message,
+      undefined,
+      replayRefusal ? UPSTREAM_RESET_REPLAY_REFUSED_CODE : undefined,
+    )), {
       status: outStatus,
-      headers: {
-        "Content-Type": "application/json",
-        ...(retryAfter ? { "Retry-After": retryAfter } : (transient ? { "Retry-After": "2" } : {})),
-      },
+      headers: outHeaders,
     });
-    return out;
+    return carryReplayRefusal(response, out);
   }
 
   const contentType = response.headers.get("content-type") ?? "";
diff --git a/src/server/grok-responses-snapshot-repair.ts b/src/server/grok-responses-snapshot-repair.ts
index a667f44e551..57d95ed4273 100644
--- a/src/server/grok-responses-snapshot-repair.ts
+++ b/src/server/grok-responses-snapshot-repair.ts
@@ -1,8 +1,13 @@
 /** Strict terminal reconstruction selected by the Grok compatibility marker. */
 import type { TranslatorBudget } from "../lib/translator-budget";
 import { MAX_COMPLETED_OUTPUT_ITEMS, MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES } from "./relay";
-import { sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
+import { replaceSseDataPayload, sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
 import { isPlainObject, jsonBlock, type RetainedOutputItem } from "./responses-snapshot-codec";
+import {
+  requestToolScope,
+  type RequestToolScope,
+  type RequestToolScopeCorrespondence,
+} from "./responses-request-tool-scope";
 
 type SparseTerminalOpenItem = {
   type: string;
@@ -16,6 +21,20 @@ type SparseTerminalCompletedItem = RetainedOutputItem & {
 
 const MAX_GROK_OPEN_ITEM_IDENTITY_BYTES = MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES;
 
+/** Terminal event this repair publishes when it refused to reconstruct a call faithfully. */
+export const GROK_REFUSED_TERMINAL_EVENT_TYPE = "response.incomplete";
+
+/** `incomplete_details.reason` carried by that terminal. */
+export const GROK_FORBIDDEN_TOOL_CALL_REASON = "forbidden_tool_call";
+
+/** An upstream-supplied name reaches the terminal message; keep it bounded. */
+const MAX_REPORTED_TOOL_NAME_CHARS = 100;
+
+export function forbiddenToolCallMessage(name: string): string {
+  return `routed provider called "${name.slice(0, MAX_REPORTED_TOOL_NAME_CHARS)}", `
+    + "which this request's tool selection excludes; the reconstructed output omits that call";
+}
+
 const GROK_TERMINAL_OUTPUT_ITEM_TYPES = new Set([
   "message",
   "reasoning",
@@ -167,6 +186,45 @@ function plausibleGrokOpenItem(
   };
 }
 
+/**
+ * Publish the refusal on the terminal itself rather than as a silent omission.
+ *
+ * The ordinary reconstruction replaces only the data payload's `output`, so its event name still
+ * describes the payload. A refusal does not: the turn no longer completed the way the upstream
+ * said it did, so the event line moves with the status instead of leaving a client to read a
+ * clean finish off an unchanged `event: response.completed`.
+ */
+function refusedTerminalBlock(
+  block: string,
+  parsed: Record<string, unknown>,
+  response: Record<string, unknown>,
+  output: readonly Record<string, unknown>[],
+  refusedName: string | undefined,
+): string {
+  const payload = JSON.stringify({
+    ...parsed,
+    type: GROK_REFUSED_TERMINAL_EVENT_TYPE,
+    response: {
+      ...response,
+      status: "incomplete",
+      output,
+      incomplete_details: {
+        reason: GROK_FORBIDDEN_TOOL_CALL_REASON,
+        ...(refusedName === undefined ? {} : { message: forbiddenToolCallMessage(refusedName) }),
+      },
+    },
+  });
+  const rewritten = replaceSseDataPayload(block, payload);
+  const newline = block.includes("\r\n") ? "\r\n" : "\n";
+  let eventRewritten = false;
+  const lines = rewritten.split(/\r?\n/).map(line => {
+    if (eventRewritten || !line.startsWith("event:")) return line;
+    eventRewritten = true;
+    return `event: ${GROK_REFUSED_TERMINAL_EVENT_TYPE}`;
+  });
+  return lines.join(newline);
+}
+
 /**
  * Narrow client repair for grok-build's Responses consumer.
  *
@@ -176,12 +234,26 @@ function plausibleGrokOpenItem(
  * empty output. Reconstruct only from real, unique, contiguous, bounded done
  * events whose raw semantics are already valid. Any ambiguity stays byte-level
  * fail-closed; the provider-opt-in snapshot repair above is unchanged.
+ *
+ * The terminal this publishes is one the upstream never sent, so it carries only what the final
+ * outbound request still authorized. A client call outside that request's tool selection is left
+ * out and the terminal says so explicitly. The declaration guard downstream answers the other
+ * half of the question — whether a name was declared at all — and keeps policing the raw stream,
+ * which this rewrite never edits.
  */
 export function createGrokResponsesSparseTerminalBlockRewrite(
   budget?: TranslatorBudget,
+  outboundRequestBody?: unknown,
+  toolIdentityCorrespondence?: RequestToolScopeCorrespondence,
 ): SseBlockRewrite {
+  const toolScope: RequestToolScope | undefined = requestToolScope(
+    outboundRequestBody,
+    toolIdentityCorrespondence,
+  );
   const openItems = new Map<number, SparseTerminalOpenItem>();
   const completedItems = new Map<number, SparseTerminalCompletedItem>();
+  const withheldIndices = new Set<number>();
+  let withheldToolName: string | undefined;
   let aggregateItemBytes = 0;
   let aggregateOpenItemBytes = 0;
   let tainted = false;
@@ -194,6 +266,8 @@ export function createGrokResponsesSparseTerminalBlockRewrite(
     }
     openItems.clear();
     completedItems.clear();
+    withheldIndices.clear();
+    withheldToolName = undefined;
     aggregateItemBytes = 0;
     aggregateOpenItemBytes = 0;
     hasVisibleOutput = false;
@@ -217,7 +291,7 @@ export function createGrokResponsesSparseTerminalBlockRewrite(
     if (tainted) return;
     const sourceBytes = Buffer.byteLength(JSON.stringify(item), "utf8");
     if (sourceBytes > MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES
-      || completedItems.size >= MAX_COMPLETED_OUTPUT_ITEMS
+      || completedItems.size + withheldIndices.size >= MAX_COMPLETED_OUTPUT_ITEMS
       || aggregateItemBytes + sourceBytes > MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES) {
       taintAndRelease();
       return;
@@ -228,6 +302,24 @@ export function createGrokResponsesSparseTerminalBlockRewrite(
     hasVisibleOutput = hasVisibleOutput || visibleToGrok;
   };
 
+  /**
+   * Record the position of a call this request forbade without retaining the item.
+   *
+   * Only the offending item is dropped. Tainting here instead would discard the assistant text
+   * that arrived in the same turn and leave the client the empty terminal this repair exists to
+   * fix, which punishes the caller for the provider's overreach. The index is kept so the
+   * contiguity proof below still covers the whole output.
+   */
+  const withholdForbiddenCall = (index: number, name: string): void => {
+    if (tainted) return;
+    if (completedItems.size + withheldIndices.size >= MAX_COMPLETED_OUTPUT_ITEMS) {
+      taintAndRelease();
+      return;
+    }
+    withheldIndices.add(index);
+    withheldToolName ??= name.slice(0, MAX_REPORTED_TOOL_NAME_CHARS);
+  };
+
   const closeOpenItem = (index: number): void => {
     const open = openItems.get(index);
     if (!open) return;
@@ -265,6 +357,7 @@ export function createGrokResponsesSparseTerminalBlockRewrite(
       const open = isPlainObject(parsed.item) ? plausibleGrokOpenItem(parsed.item) : null;
       if (outputIndex === undefined || !open
         || openItems.has(outputIndex) || completedItems.has(outputIndex)
+        || withheldIndices.has(outputIndex)
         || openItems.size >= MAX_COMPLETED_OUTPUT_ITEMS) {
         taintAndRelease();
       } else if (!tainted) {
@@ -284,7 +377,8 @@ export function createGrokResponsesSparseTerminalBlockRewrite(
     if (type === "response.output_item.done") {
       const item = isPlainObject(parsed.item) ? parsed.item : null;
       const proof = item ? trustedGrokCompletedItem(item) : null;
-      if (outputIndex === undefined || !proof || completedItems.has(outputIndex)) {
+      if (outputIndex === undefined || !proof
+        || completedItems.has(outputIndex) || withheldIndices.has(outputIndex)) {
         taintAndRelease();
         return [block];
       }
@@ -295,7 +389,12 @@ export function createGrokResponsesSparseTerminalBlockRewrite(
         return [block];
       }
       closeOpenItem(outputIndex);
-      retainCompletedItem(outputIndex, item!, proof.visibleToGrok);
+      const forbidden = toolScope?.forbiddenClientToolCallName(item!);
+      if (forbidden === undefined) {
+        retainCompletedItem(outputIndex, item!, proof.visibleToGrok);
+      } else {
+        withholdForbiddenCall(outputIndex, forbidden);
+      }
       return [block];
     }
 
@@ -312,14 +411,18 @@ export function createGrokResponsesSparseTerminalBlockRewrite(
       const outputIsAuthoritative = Array.isArray(output) && output.length > 0;
       const outputIsSparse = !("output" in response)
         || (Array.isArray(output) && output.length === 0);
+      // A withheld call is a reason to publish on its own: the refusal has to reach the client
+      // even when nothing visible survived it, or the turn ends as an ordinary empty finish.
+      const refused = withheldIndices.size > 0;
       if (!outputIsAuthoritative && outputIsSparse && terminalStatusConsistent
-        && completedItems.size > 0 && openItems.size === 0 && hasVisibleOutput) {
+        && openItems.size === 0 && (hasVisibleOutput || refused)) {
         const ordered = [...completedItems.entries()].sort(([left], [right]) => left - right);
-        if (ordered.every(([index], position) => index === position)) {
-          out = jsonBlock({
-            ...parsed,
-            response: { ...response, output: ordered.map(([, retained]) => retained.item) },
-          });
+        const positions = [...completedItems.keys(), ...withheldIndices].sort((left, right) => left - right);
+        if (positions.length > 0 && positions.every((index, position) => index === position)) {
+          const rebuilt = ordered.map(([, retained]) => retained.item);
+          out = refused
+            ? refusedTerminalBlock(block, parsed, response, rebuilt, withheldToolName)
+            : jsonBlock({ ...parsed, response: { ...response, output: rebuilt } });
         }
       }
     }
@@ -330,4 +433,3 @@ export function createGrokResponsesSparseTerminalBlockRewrite(
   rewrite.dispose = reset;
   return rewrite;
 }
-
diff --git a/src/server/gui-freshness.ts b/src/server/gui-freshness.ts
new file mode 100644
index 00000000000..1d3c6b317d8
--- /dev/null
+++ b/src/server/gui-freshness.ts
@@ -0,0 +1,103 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Whether the served dashboard bundle predates the sources it was built from.
+ *
+ * The dashboard is a build artifact: `AGENTS.md` records that `gui/` is served from `gui/dist`,
+ * so a checkout that moves forward without `bun run build:gui` keeps serving the previous bundle.
+ * Nothing fails when that happens. The proxy answers, the page loads, and every feature added since
+ * the last build is simply absent — which reads as the feature being broken rather than unbuilt.
+ * A five-day-old bundle hid the entire menu-bar and widget section of the Usage page this way.
+ *
+ * This reports; it never rebuilds. A proxy that compiled a frontend while starting would trade a
+ * silent staleness for a slow, surprising start, and the rebuild belongs to whoever moved the
+ * checkout.
+ */
+export interface GuiBundleFreshness {
+  /** Absolute path of the served bundle, or null when no bundle was found. */
+  bundlePath: string | null;
+  /** Newest mtime under the bundle, in epoch milliseconds. */
+  bundleModifiedMs: number | null;
+  /** Newest mtime under the GUI sources, in epoch milliseconds. */
+  sourceModifiedMs: number | null;
+  /** True only when both sides are known and the sources are strictly newer. */
+  stale: boolean;
+}
+
+/** Directory entries that never carry meaningful build input or output timestamps. */
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".git", ".vite", ".cache"]);
+
+/**
+ * Newest mtime beneath `root`, or null when the tree is missing or empty.
+ *
+ * Walking is bounded by `maxEntries` because this runs on a status path: a pathological tree must
+ * cost a predictable amount rather than stalling the command that reports on it. Hitting the bound
+ * yields the newest value seen so far, which can only make the comparison more conservative.
+ */
+export function newestModifiedMs(root: string, maxEntries = 20_000): number | null {
+  if (!existsSync(root)) return null;
+  let newest: number | null = null;
+  let seen = 0;
+  const queue: string[] = [root];
+  while (queue.length > 0) {
+    const current = queue.pop()!;
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (seen >= maxEntries) return newest;
+      if (entry.isSymbolicLink()) continue;
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRECTORIES.has(entry.name)) continue;
+        queue.push(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      seen += 1;
+      try {
+        const mtime = statSync(full).mtimeMs;
+        if (newest === null || mtime > newest) newest = mtime;
+      } catch {
+        // A file that vanished mid-walk cannot make the bundle look fresher than it is.
+      }
+    }
+  }
+  return newest;
+}
+
+/**
+ * Compare the built bundle against its sources.
+ *
+ * Unknown is not stale. A packaged install has no `gui/src` beside it, and a missing bundle is a
+ * different condition with its own message elsewhere; neither should produce a rebuild warning.
+ */
+export function inspectGuiBundleFreshness(input: {
+  bundlePath: string | null;
+  sourcePath: string;
+}): GuiBundleFreshness {
+  const bundleModifiedMs = input.bundlePath === null ? null : newestModifiedMs(input.bundlePath);
+  const sourceModifiedMs = newestModifiedMs(input.sourcePath);
+  const stale = bundleModifiedMs !== null
+    && sourceModifiedMs !== null
+    && sourceModifiedMs > bundleModifiedMs;
+  return {
+    bundlePath: input.bundlePath,
+    bundleModifiedMs,
+    sourceModifiedMs,
+    stale,
+  };
+}
+
+/** Operator-facing lines for a stale bundle; empty when the bundle is current or unknown. */
+export function staleGuiBundleLines(freshness: GuiBundleFreshness): string[] {
+  if (!freshness.stale) return [];
+  return [
+    "Dashboard bundle is older than the GUI sources, so the page is missing everything built since.",
+    "Rebuild it with: bun run build:gui",
+  ];
+}
diff --git a/src/server/gui-static.ts b/src/server/gui-static.ts
index d128361c02b..3057dc748ee 100644
--- a/src/server/gui-static.ts
+++ b/src/server/gui-static.ts
@@ -2,15 +2,11 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { browserSecurityHeaders } from "./auth-cors";
 import type { GuiSessionBootstrap } from "./gui-session";
+import { packageVersion } from "../lib/package-version";
+import { isStandaloneBinary, standaloneRoot } from "../lib/standalone";
 
 /** opencodex version, read from the packaged package.json (same source as the server bootstrap). */
-const VERSION = (() => {
-  try {
-    return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version as string;
-  } catch {
-    return "0.0.0";
-  }
-})();
+const VERSION = packageVersion("0.0.0");
 
 const MIME_TYPES: Record<string, string> = {
   ".html": "text/html", ".js": "application/javascript", ".css": "text/css",
@@ -24,11 +20,13 @@ const MIME_TYPES: Record<string, string> = {
  */
 const HASHED_ASSET_PATTERN = /-[a-zA-Z0-9_-]{8,}\.[a-zA-Z0-9]+$/;
 
-function findGuiDist(): string | null {
+export function findGuiDist(): string | null {
   const candidates = [
+    process.env.OPENCODEX_GUI_DIST,
+    ...(isStandaloneBinary() ? [join(standaloneRoot(), "gui", "dist")] : []),
     join(import.meta.dir, "..", "..", "gui", "dist"),
     join(import.meta.dir, "..", "..", "..", "gui", "dist"),
-  ];
+  ].filter((candidate): candidate is string => Boolean(candidate));
   for (const c of candidates) {
     if (existsSync(join(c, "index.html"))) return c;
   }
diff --git a/src/server/images.ts b/src/server/images.ts
index cf9c4d516f3..fdf944b1c3f 100644
--- a/src/server/images.ts
+++ b/src/server/images.ts
@@ -33,6 +33,8 @@ import { selectProactiveApiKeyTransport } from "../providers/key-failover";
 import { getProviderRegistryEntry } from "../providers/registry";
 import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-decompress";
 import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "./auth-cors";
+import type { DataPlaneAdmission } from "./auth-cors";
+import { admissionScopeDenial } from "./admission-model-scope";
 import type { RequestLogContext } from "./request-log";
 import { codexLogAccountId, decodeRequestErrorResponse } from "./responses";
 import { getValidAccessToken, getOAuthCredentialProjectId } from "../oauth/index";
@@ -115,6 +117,18 @@ export async function readImageResponseBytes(
 }
 
 const CCA_IMAGE_MODEL = "gemini-3.1-flash-image";
+const XAI_IMAGE_BRIDGE_MODEL = "grok-imagine-image-quality";
+
+/**
+ * The model this request names, or undefined when it names none.
+ *
+ * An absent `model` is relayed as an absent `model`: the upstream picks, so
+ * there is no destination to echo and none a model list can allow.
+ */
+function requestedImageSelector(body: unknown): string | undefined {
+  const model = (body as { model?: unknown } | null)?.model;
+  return typeof model === "string" && model.trim() ? model : undefined;
+}
 
 /**
  * Google Gemini finishReasons that indicate a permanent content/safety block.
@@ -207,11 +221,21 @@ async function tryCcaImageGeneration(
   logCtx: RequestLogContext,
   signal: AbortSignal,
   endpoint: ImagesEndpoint,
+  admission: DataPlaneAdmission | undefined,
 ): Promise<Response | undefined> {
   if (endpoint !== "generations") return undefined;
   const provider = config.providers?.["google-antigravity"];
   if (!provider || provider.disabled) return undefined;
 
+  // The destination is decided here, not by the caller: this branch always
+  // bills Antigravity for CCA_IMAGE_MODEL whatever the body named. That is the
+  // pair a scoped key is held to.
+  const denial = admissionScopeDenial(config, admission, requestedImageSelector(body), {
+    providerName: "google-antigravity",
+    modelId: CCA_IMAGE_MODEL,
+  });
+  if (denial) return denial;
+
   const prompt = (body as { prompt?: unknown })?.prompt;
   if (typeof prompt !== "string" || !prompt.trim()) {
     return formatErrorResponse(400, "invalid_request_error", "prompt is required and must not be empty");
@@ -446,10 +470,20 @@ async function tryXaiImageRelay(
   logCtx: RequestLogContext,
   signal: AbortSignal | undefined,
   endpoint: ImagesEndpoint,
+  admission: DataPlaneAdmission | undefined,
 ): Promise<Response | undefined> {
   if (config.images?.bridgeEnabled !== true) return undefined;
   const found = findXaiProvider(config);
   if (!found) return undefined;
+  const bridgeModel = config.images?.bridgeModel ?? XAI_IMAGE_BRIDGE_MODEL;
+  // The bridge sends this request to the configured xAI provider and the bridge
+  // model regardless of the selector in the body, so that is what the key is
+  // checked against.
+  const denial = admissionScopeDenial(config, admission, requestedImageSelector(body), {
+    providerName: found.name,
+    modelId: bridgeModel,
+  });
+  if (denial) return denial;
   const obj = body && typeof body === "object" && !Array.isArray(body)
     ? body as Record<string, unknown>
     : {};
@@ -496,11 +530,11 @@ async function tryXaiImageRelay(
     }
     if (!token) return xaiImageAuthMissing();
     logCtx.provider = "xai";
-    logCtx.model = config.images?.bridgeModel ?? "grok-imagine-image-quality";
+    logCtx.model = bridgeModel;
     const result = await callXaiImages(
       {
         prompt,
-        model: logCtx.model,
+        model: bridgeModel,
         n,
         size,
         quality,
@@ -602,6 +636,7 @@ export async function handleImages(
   endpoint: ImagesEndpoint,
   logCtx: RequestLogContext,
   turnAdmissionLease?: AdmissionLease,
+  admission?: DataPlaneAdmission,
 ): Promise<Response> {
   let body: unknown;
   try {
@@ -616,7 +651,7 @@ export async function handleImages(
   // Explicit images.provider owns the route, including its validation errors.
   // Do not divert that selection to the xAI Imagine relay.
   if (config.images?.provider === undefined) {
-    const xaiRelay = await tryXaiImageRelay(body, config, logCtx, req.signal, endpoint);
+    const xaiRelay = await tryXaiImageRelay(body, config, logCtx, req.signal, endpoint, admission);
     if (xaiRelay) return xaiRelay;
   }
   if (candidates.error) {
@@ -641,7 +676,7 @@ export async function handleImages(
   const canUseOpenAiForward = !skipOpenAiForwardForAdmissionBearer && candidates.forwardCandidates.length > 0;
 
   if (!canUseOpenAiForward && !candidates.keyed) {
-    const ccaResponse = await tryCcaImageGeneration(body, config, logCtx, req.signal, endpoint);
+    const ccaResponse = await tryCcaImageGeneration(body, config, logCtx, req.signal, endpoint, admission);
     if (ccaResponse) return ccaResponse;
     // 400, not 5xx: codex retries every 5xx up to 5 total attempts, and this is a permanent
     // configuration state that must surface on the first attempt.
@@ -688,7 +723,20 @@ export async function handleImages(
 
   const headers: Record<string, string> = { "content-type": "application/json" };
   let url: string;
+  // Both relay branches copy the body upstream, so the destination is the
+  // provider chosen in that branch and the model the caller named. Each branch
+  // is checked as it is entered, before it resolves a credential or commits a
+  // key rotation, so a refused request spends nothing.
+  const relaySelector = requestedImageSelector(body);
   if (forward) {
+    const denial = admissionScopeDenial(config, admission, relaySelector, {
+      providerName: forward.providerName,
+      modelId: relaySelector,
+    });
+    if (denial) {
+      forward.releaseProbeLease?.();
+      return denial;
+    }
     const { provider } = forward;
     if (provider.headers) Object.assign(headers, provider.headers);
     for (const [name, value] of forward.headers) headers[name] = value;
@@ -697,13 +745,18 @@ export async function handleImages(
   } else if (forwardAuthError) {
     // Before surfacing the OpenAI auth failure, try CCA — the user may have a
     // valid Google Antigravity login even though their OpenAI pool is broken.
-    const ccaResponse = await tryCcaImageGeneration(body, config, logCtx, req.signal, endpoint);
+    const ccaResponse = await tryCcaImageGeneration(body, config, logCtx, req.signal, endpoint, admission);
     if (ccaResponse) return ccaResponse;
     // No CCA either: a configured OpenAI pool mode owns its authentication failure.
     // Do not hide a broken/expired pool behind separately billed API-key image generation.
     return forwardAuthError;
   } else if (candidates.keyed) {
     const { providerName } = candidates.keyed;
+    const denial = admissionScopeDenial(config, admission, relaySelector, {
+      providerName,
+      modelId: relaySelector,
+    });
+    if (denial) return denial;
     // The keyed image path builds its own URL and Authorization header and never enters
     // handleResponses, so the pre-dispatch key pick happens here.
     //
@@ -737,7 +790,7 @@ export async function handleImages(
     url = `${provider.baseUrl.replace(/\/v1\/?$/, "")}/v1/images/${endpoint}`;
   } else {
     // No usable OpenAI credential — try CCA before giving up.
-    const ccaResponse = await tryCcaImageGeneration(body, config, logCtx, req.signal, endpoint);
+    const ccaResponse = await tryCcaImageGeneration(body, config, logCtx, req.signal, endpoint, admission);
     if (ccaResponse) return ccaResponse;
     return formatErrorResponse(
       401,
diff --git a/src/server/index.ts b/src/server/index.ts
index af20051d9eb..61fbcec7d8a 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -69,11 +69,6 @@ import { runDevinProviderMergeStartupMigration } from "../providers/devin-provid
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { providerCodexAccountMode } from "../providers/registry";
 import type { StorageCleanupPolicy } from "../types";
-import {
-  MAX_CONFIGURABLE_INBOUND_BODY_BYTES,
-  MIN_CONFIGURABLE_INBOUND_BODY_BYTES,
-  resolveInboundBodyLimitBytes,
-} from "./request-decompress";
 import { MAIN_CODEX_ACCOUNT_ID } from "../codex/main-account";
 export {
   clearThreadAccountMap,
@@ -116,6 +111,7 @@ import {
   type RequestLogEntry,
 } from "./request-log";
 import { sessionLaneIdFromRequest } from "./request-log-conversation";
+import { setUsageLedgerRetention } from "./usage-ledger-retention";
 import { admitHttpWorkflowTurn, workflowDecisionRefusalResponse, type WorkflowRefusalLog } from "./workflow-refusal";
 export {
   addFinalRequestLog,
@@ -203,13 +199,15 @@ import {
 } from "../lib/package-tree-integrity";
 import { detectInstall } from "../update/index";
 import { createServeOptions, type ServerIngress } from "./index/serve-options";
-import { inspectStartupOwnership, setStartupCacheInvalidationWrite, warnAgentTaskRecoveryStartup, warnPlaintextV2AgentMessagesStartup, type StartServerDeps } from "./index/startup-warnings";
-import { acquireSpendLedgerServerLifecycle, type SpendLedgerServerLifecycle } from "./index/spend-ledger-lifecycle";
+import { createClaudeInterceptLifecycle } from "./index/claude-intercept-lifecycle";
+import { inspectStartupOwnership, resolveInboundBodyLimitWithWarning, setStartupCacheInvalidationWrite, warnAgentTaskRecoveryStartup, warnPlaintextV2AgentMessagesStartup, type StartServerDeps } from "./index/startup-warnings";
+import { acquireSpendLedgerServerLifecycle, recordFailedStartRollback, type SpendLedgerServerLifecycle } from "./index/spend-ledger-lifecycle";
+export { waitForFailedStartRollback } from "./index/spend-ledger-lifecycle";
 
 export function startServer(port?: number, deps: StartServerDeps = {}): Server<WsData> {
   const spendLedgerLifecycle = acquireSpendLedgerServerLifecycle(getConfigDir());
   try { return startServerWithSpendLedgerOwner(port, deps, spendLedgerLifecycle); }
-  catch (error) { spendLedgerLifecycle.releaseAfterFailedStart(); throw error; }
+  catch (error) { recordFailedStartRollback(error, spendLedgerLifecycle.releaseAfterFailedStart()); throw error; }
 }
 
 function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartServerDeps, spendLedgerLifecycle: SpendLedgerServerLifecycle): Server<WsData> {
@@ -307,6 +305,9 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
   enforceAppOwnedMemoryBudget();
   // Observe-only mode still journals physical sends, so every server owns before configuring.
   spendLedgerLifecycle.configure(config.spend);
+  // After ownership: a second server on the same home is refused above, so the process running
+  // this line is the only one appending to usage.jsonl and the only one that may compact it.
+  setUsageLedgerRetention(config.usageLedgerMaxBytes);
   registerCodexCooldownRecoveryProbeWorker(config);
   // Issue #42 Phase 3: opt-in archived auto-cleanup (default OFF). Unref'd hourly
   // tick for daily/weekly; startup evaluation is fire-and-forget after listen.
@@ -627,26 +628,13 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
   let server: Server<WsData>;
   let loopbackServer: Server<WsData> | null = null;
   let managementIngressServer: Server<WsData> | null = null;
-
-  // Resolved once, before any listener binds. The clamp is silent inside the resolver so it
-  // stays pure and per-request cheap; the operator is told here instead, once, because a
-  // config value that was quietly reduced is exactly the thing they would otherwise debug
-  // against the wrong limit.
-  const inboundBodyLimitBytes = resolveInboundBodyLimitBytes(config.maxInboundBodyBytes);
-  const requestedInboundBodyLimit = config.maxInboundBodyBytes;
-  if (requestedInboundBodyLimit !== undefined
-    && requestedInboundBodyLimit > 0
-    && requestedInboundBodyLimit !== inboundBodyLimitBytes) {
-    console.warn(
-      `[server] maxInboundBodyBytes=${requestedInboundBodyLimit} is outside the supported range `
-      + `[${MIN_CONFIGURABLE_INBOUND_BODY_BYTES}, ${MAX_CONFIGURABLE_INBOUND_BODY_BYTES}]; `
-      + `using ${inboundBodyLimitBytes} bytes.`,
-    );
-  }
+  const claudeIntercept = createClaudeInterceptLifecycle<WsData>();
+  const inboundBodyLimitBytes = resolveInboundBodyLimitWithWarning(config);
 
   function ingressForServer(requestServer: Server<WsData>): ServerIngress {
     if (requestServer === loopbackServer) return "unauthenticated-loopback";
     if (requestServer === managementIngressServer) return "hub-management";
+    if (claudeIntercept.ownsListener(requestServer)) return "claude-intercept";
     return "public";
   }
   let backgroundLifecycle: ReturnType<typeof acquireServerBackgroundLifecycle> | null = null;
@@ -748,6 +736,10 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
         throw new AuxiliaryListenerBindError("hub.managementIngress", managementIngressPort, "127.0.0.1", error);
       }
     }
+    claudeIntercept.start({
+      config, publicPort: server.port ?? listenPort, requestedPort: listenPort, maxRequestBodySize: inboundBodyLimitBytes,
+      dispatch: (req, requestServer) => serveOptions.fetch(req, requestServer),
+    });
   } catch (error) {
     unregisterQuotaAutoRefresh?.();
     userCostOverlayReconciler?.stop();
@@ -776,6 +768,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
           ...(managementIngressRef
             ? [() => managementIngressRef.stop(closeActiveConnections)]
             : []),
+          () => claudeIntercept.stop(),
           async () => { await remoteWorkspaceShutdown?.(); },
           async () => {
             try {
@@ -785,16 +778,16 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
             }
           },
         ],
-        async () => {
+        async listenersStopped => {
           try {
             await backgroundLifecycle.release();
             await releaseNativeMainStartupLifecycle(server);
           } finally {
             // icacls.exe from hardenConfigDir() holds the config dir open; a caller that
             // removes the dir right after stop() settles would hit EPERM/EBUSY on Windows
-            // otherwise. Runs even when an earlier release rejected — that rejection still
-            // propagates, but not before the child is drained.
-            try { spendLedgerLifecycle.release(); }
+            // otherwise. Config hardening still flushes when an earlier release rejects. The
+            // spend owner is retained when a listener stop failed because the socket may live.
+            try { if (listenersStopped) spendLedgerLifecycle.release(); }
             finally { await flushConfigDirHardening(startupConfigDir); }
           }
         },
diff --git a/src/server/index/claude-intercept-lifecycle.ts b/src/server/index/claude-intercept-lifecycle.ts
new file mode 100644
index 00000000000..f49bc49b988
--- /dev/null
+++ b/src/server/index/claude-intercept-lifecycle.ts
@@ -0,0 +1,49 @@
+import type { Server } from "bun";
+import {
+  startClaudeIntercept,
+  type ClaudeInterceptHandle,
+  type StartClaudeInterceptOptions,
+} from "../../claude/intercept/runtime";
+
+/**
+ * Owns the Claude intercept pair (CONNECT proxy + TLS listener) on behalf of `startServer`.
+ * The pair is an optional integration: a bind failure degrades to a warning, never to a
+ * startup failure, because every other client keeps working without it. `startServer` stays
+ * synchronous, so the start is fire-and-forget and `stop()` awaits whatever it produced.
+ */
+export interface ClaudeInterceptLifecycle<T> {
+  /** True once the TLS listener has bound and `requestServer` is it. */
+  ownsListener(requestServer: Server<T>): boolean;
+  start(options: StartClaudeInterceptOptions<T>): void;
+  stop(): Promise<void>;
+}
+
+export function createClaudeInterceptLifecycle<T>(): ClaudeInterceptLifecycle<T> {
+  let listener: Server<T> | null = null;
+  let pending: Promise<ClaudeInterceptHandle<T> | null> = Promise.resolve(null);
+  return {
+    ownsListener: requestServer => listener !== null && requestServer === listener,
+    start(options) {
+      const dispatch = options.dispatch;
+      pending = startClaudeIntercept<T>({
+        ...options,
+        dispatch: (req, requestServer) => {
+          listener ??= requestServer;
+          return dispatch(req, requestServer);
+        },
+      }).then(handle => {
+        if (handle) {
+          listener = handle.listener;
+          console.log(`🔐 Claude intercept proxy active on http://127.0.0.1:${handle.proxyPort} (CONNECT api.anthropic.com → local TLS)`);
+        }
+        return handle;
+      }).catch((error: unknown) => {
+        console.warn(`⚠ Claude intercept proxy could not start: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+      });
+    },
+    async stop() {
+      await (await pending)?.stop();
+    },
+  };
+}
diff --git a/src/server/index/serve-options.ts b/src/server/index/serve-options.ts
index 657f5f0b5b9..4e4eab84bc7 100644
--- a/src/server/index/serve-options.ts
+++ b/src/server/index/serve-options.ts
@@ -24,6 +24,7 @@ import {
 } from "./startup-warnings";
 
 import { remoteWorkspaceEnabled } from "../../remote-control/workspace-activation";
+import { isClaudeInterceptedPath } from "../../claude/intercept/listener";
 import { markActivity } from "../../lib/sidecar-tracker";
 import { knownModelIdsForProvider } from "../../router";
 import {
@@ -49,8 +50,8 @@ import { MAIN_CODEX_ACCOUNT_ID } from "../../codex/main-account";
 import {
   availableAccountGatedNativeModels,
   codexModelEntitlementStateForAccount,
-  resolveCodexModelEntitlements,
 } from "../../codex/model-entitlements";
+import { resolveAdmittedCodexModelEntitlements } from "../../codex/model-entitlement-admission";
 import { CatalogGatherBusyError } from "../../codex/catalog/provider-fetch";
 import {
   registerCodexWebSocket,
@@ -100,6 +101,7 @@ import {
   withCors,
   withManagementCors,
 } from "../auth-cors";
+import { resolveAdmissionModelScope, routeAllowedByScope } from "../admission-model-scope";
 import {
   disableResponsesRequestTimeout,
   handleResponses,
@@ -196,7 +198,16 @@ import { readyProtocolMetadata } from "../../remote/protocol";
 import { modelCapabilityFields } from "../models-capabilities";
 import { createWebsocketHandler } from "./websocket-handler";
 
-export type ServerIngress = "public" | "unauthenticated-loopback" | "hub-management";
+export type ServerIngress = "public" | "unauthenticated-loopback" | "hub-management" | "claude-intercept";
+
+/**
+ * Routes the Claude intercept TLS listener may reach. Everything else on that socket is relayed
+ * to the real upstream by the listener itself, so a request that lands here with another path
+ * is a bug, not a client — refuse it.
+ */
+export function claudeInterceptRouteAllowed(url: URL, req: Request): boolean {
+  return isClaudeInterceptedPath(url.pathname, req.method);
+}
 
 export interface ServeOptionsContext {
   readonly server: Server<WsData>;
@@ -300,12 +311,24 @@ export function createServeOptions(ctx: ServeOptionsContext) {
           config,
         );
       }
+      if (ingress === "claude-intercept" && !claudeInterceptRouteAllowed(codexCompatibleUrl(req.url), req)) {
+        return withCors(
+          formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${new URL(req.url).pathname}`),
+          req,
+          loopbackPolicy(),
+        );
+      }
       // Auth and CORS decisions below read `policy`, not `config`. For the public listener the
       // two are the same object, so its behaviour is unchanged; for the loopback listener the
       // view substitutes 127.0.0.1 as the bind address, which is what routes it through the
       // same code path a plain loopback bind has always taken — Host-header check included.
       // Routing, provider selection and response bodies keep using `config`.
-      const policy: RequestPolicyView = ingress === "unauthenticated-loopback" ? loopbackPolicy() : config;
+      // The Claude intercept listener is loopback by construction (the CONNECT proxy binds
+      // 127.0.0.1 and the request was rewritten onto a loopback origin), and its callers carry
+      // Anthropic credentials, not opencodex admission tokens — so it takes the loopback view too.
+      const policy: RequestPolicyView = ingress === "unauthenticated-loopback" || ingress === "claude-intercept"
+        ? loopbackPolicy()
+        : config;
       const url = codexCompatibleUrl(req.url);
       markActivity(`${req.method} ${url.pathname}`);
 
@@ -819,7 +842,13 @@ export function createServeOptions(ctx: ServeOptionsContext) {
             // Codex sends its own client_version on this request, and upstream filters the
             // entitlement roster by it. Passing it through is what stops an entitled account
             // being told it cannot use models a newer client can (#2886).
-            resolveCodexModelEntitlements(config, { clientVersion: url.searchParams.get("client_version") }),
+            // The request signal fences the credential phase too: a client that has already
+            // gone away must not keep a native-main token refresh alive, and its late result
+            // must not commit on behalf of a request that no longer exists.
+            resolveAdmittedCodexModelEntitlements(config, {
+              clientVersion: url.searchParams.get("client_version"),
+              signal: req.signal,
+            }),
           ]);
         } catch (error) {
           if (error instanceof CatalogGatherBusyError) {
@@ -1101,6 +1130,17 @@ export function createServeOptions(ctx: ServeOptionsContext) {
             return disabledModels.has(id) ? [] : [{ id, metadataId }];
           })
         );
+        // What a scoped key may see, filtered by the same predicate that refuses
+        // it on the data plane, so the catalog and the send path cannot disagree.
+        // This is a convenience, never the boundary: hiding a row only stops a
+        // client that reads the catalog first, which is why the refusal lives on
+        // the request path and this filter reuses it rather than replacing it.
+        // Filtering happens where the resolved provider and model are still in
+        // hand -- a published id is a selector, and re-resolving one here would
+        // re-run combo selection just to render a list.
+        const listScope = resolveAdmissionModelScope(config, admission);
+        const listAllows = (providerName: string, modelId: string): boolean =>
+          routeAllowedByScope(listScope, { providerName, modelId });
         // The projection is opt-in. Keep the default path free of Cursor install detection,
         // and resolve the bundle table once for the whole list rather than once per row.
         const effortRowsEnabled = config.cursorEffortRows === true;
@@ -1133,7 +1173,9 @@ export function createServeOptions(ctx: ServeOptionsContext) {
             effortRowKnownIds,
           ));
         };
-        const routedRows = await Promise.all(uniqueCatalogModelsForRawPublicList(goOrdered).map(async m => {
+        const routedRows = await Promise.all(uniqueCatalogModelsForRawPublicList(goOrdered)
+          .filter(m => listAllows(m.provider, m.id))
+          .map(async m => {
           // Same rule as the anthropic branch: with the global fast switch on, a client
           // that has no Fast toggle is offered the fast identity directly. An operator
           // alias is an explicit decision and still wins.
@@ -1180,8 +1222,12 @@ export function createServeOptions(ctx: ServeOptionsContext) {
           ));
         }));
         const data = [
-          ...visibleNatives.flatMap(id => expandedNativeModelRow(id)),
-          ...visibleAccountNatives.flatMap(({ id, metadataId }) => expandedNativeModelRow(id, metadataId)),
+          ...visibleNatives
+            .filter(id => listAllows(OPENAI_CODEX_PROVIDER_ID, id))
+            .flatMap(id => expandedNativeModelRow(id)),
+          ...visibleAccountNatives
+            .filter(({ metadataId }) => listAllows(OPENAI_CODEX_PROVIDER_ID, metadataId))
+            .flatMap(({ id, metadataId }) => expandedNativeModelRow(id, metadataId)),
           ...routedRows.flat(),
         ];
         return jsonResponse({ object: "list", data }, 200, req, policy);
@@ -1246,7 +1292,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
         };
         const endpoint = url.pathname.endsWith("/edits") ? "edits" as const : "generations" as const;
         return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
-          const response = await handleImages(req, config, endpoint, logCtx, turnAdmissionLease);
+          const response = await handleImages(req, config, endpoint, logCtx, turnAdmissionLease, admission);
           addFinalRequestLog(requestId, start, logCtx, response.status, response.status === 499 ? { closeReason: "client_cancel" } : undefined);
           return withCors(response, req, policy);
         }, { requestId, start, logCtx });
@@ -1534,7 +1580,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
         return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
           const response = audioClient
             ? await handleExternalLive(req, config, logCtx, { client: audioClient, lease: turnAdmissionLease, bindings: liveCallBindings })
-            : await handleLive(req, config, logCtx, turnAdmissionLease);
+            : await handleLive(req, config, logCtx, turnAdmissionLease, admission);
           addFinalRequestLog(
             requestId,
             start,
@@ -1609,7 +1655,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
             : liveSidebandTarget && audioClient
               ? await resolveExternalLiveSocket(audioClient, config, logCtx, liveSidebandTarget, { lease: turnAdmissionLease, bindings: liveCallBindings, signal: acquisition?.signal })
               : liveSidebandTarget
-                ? await resolveLiveSidebandUpgrade(req, config, logCtx, liveSidebandTarget, turnAdmissionLease)
+                ? await resolveLiveSidebandUpgrade(req, config, logCtx, liveSidebandTarget, turnAdmissionLease, admission)
                 : formatErrorResponse(401, "authentication_error", "opencodex API key required");
         } catch (error) {
           try { releaseAcquisition(); }
diff --git a/src/server/index/spend-ledger-lifecycle.ts b/src/server/index/spend-ledger-lifecycle.ts
index d7250642470..ddcc70a6a3b 100644
--- a/src/server/index/spend-ledger-lifecycle.ts
+++ b/src/server/index/spend-ledger-lifecycle.ts
@@ -8,11 +8,27 @@ import {
   spendPolicyFromConfig,
 } from "../../lib/spend-reservation-ledger";
 
+const failedStartRollbacks = new WeakMap<object, Promise<void>>();
+
+export function recordFailedStartRollback(error: unknown, rollback: Promise<void>): void {
+  if ((typeof error === "object" && error !== null) || typeof error === "function") {
+    failedStartRollbacks.set(error, rollback);
+  }
+}
+
+/** Keep an outer ownership lease until a synchronous start failure has closed every listener. */
+export function waitForFailedStartRollback(error: unknown): Promise<void> {
+  if ((typeof error === "object" && error !== null) || typeof error === "function") {
+    return failedStartRollbacks.get(error) ?? Promise.resolve();
+  }
+  return Promise.resolve();
+}
+
 export interface SpendLedgerServerLifecycle {
   configure(spend: OcxSpendConfig | undefined): void;
   track<T extends { stop(closeActiveConnections?: boolean): void | Promise<void> }>(server: T): T;
   release(): void;
-  releaseAfterFailedStart(): void;
+  releaseAfterFailedStart(): Promise<void>;
 }
 
 /** Acquire before config loading so every later startup failure has one rollback owner. */
@@ -39,28 +55,38 @@ export function acquireSpendLedgerServerLifecycle(configDir: string): SpendLedge
       return server;
     },
     release,
-    releaseAfterFailedStart(): void {
+    releaseAfterFailedStart(): Promise<void> {
       // Every listener that came up is stopped, newest first, and the lease is held until those
       // stops have actually SETTLED. Bun's Server.stop(true) returns a promise that resolves
       // once connections are closed, so discarding it handed the state directory back while a
       // listener could still be serving, which is the one thing single-writer ownership exists
       // to prevent.
       //
-      // This stays synchronous and returns void on purpose: startServer must not become async,
-      // so the wait is a continuation rather than an await. Rollback failures are contained
-      // because the startup error that brought us here is the one worth reporting.
+      // Listener shutdown starts synchronously, while the returned promise lets a caller that
+      // owns a broader mutation lease keep it until every close has settled. startServer itself
+      // remains synchronous. Rollback failures are reported beside the startup error by the
+      // outer ownership transaction, without claiming the listener is gone.
       const settling: Promise<unknown>[] = [];
+      const failures: unknown[] = [];
       for (const stop of failedStartStops.splice(0).reverse()) {
         try {
           const pending = stop();
           if (pending !== undefined) settling.push(Promise.resolve(pending));
-        } catch { /* a rollback failure must not replace the startup error that caused it */ }
+        } catch (failure) { failures.push(failure); }
       }
       const finish = (): void => {
         try { release(); } catch { /* same: the startup error is the one that matters */ }
       };
-      if (settling.length === 0) { finish(); return; }
-      void Promise.allSettled(settling).then(finish);
+      if (settling.length === 0) {
+        if (failures.length > 0) return Promise.reject(new AggregateError(failures, "failed-start listener rollback was uncertain"));
+        finish();
+        return Promise.resolve();
+      }
+      return Promise.allSettled(settling).then(results => {
+        for (const result of results) if (result.status === "rejected") failures.push(result.reason);
+        if (failures.length > 0) throw new AggregateError(failures, "failed-start listener rollback was uncertain");
+        finish();
+      });
     },
   };
 }
diff --git a/src/server/index/startup-warnings.ts b/src/server/index/startup-warnings.ts
index a29d3f6fcbf..76b9119f735 100644
--- a/src/server/index/startup-warnings.ts
+++ b/src/server/index/startup-warnings.ts
@@ -56,6 +56,11 @@ import {
   type PackageTreeIntegrityGuard,
 } from "../../lib/package-tree-integrity";
 import type { LiveSidebandWebSocketFactory } from "./live-sideband";
+import {
+  MAX_CONFIGURABLE_INBOUND_BODY_BYTES,
+  MIN_CONFIGURABLE_INBOUND_BODY_BYTES,
+  resolveInboundBodyLimitBytes,
+} from "../request-decompress";
 
 // GUI static serving extracted to ./server/gui-static. Re-exported below to keep the
 // "../src/server" import surface stable for tests/callers.
@@ -205,6 +210,25 @@ export function warnAgentTaskRecoveryStartup(config: {
   console.warn("   Recovered plaintext assignment data is retained only in a bounded, process-local in-memory cache; exact fidelity is not guaranteed and the path depends on undocumented backend behavior.");
 }
 
+/**
+ * Resolved once, before any listener binds. The clamp is silent inside the resolver so it
+ * stays pure and per-request cheap; the operator is told here instead, once, because a
+ * config value that was quietly reduced is exactly the thing they would otherwise debug
+ * against the wrong limit.
+ */
+export function resolveInboundBodyLimitWithWarning(config: { maxInboundBodyBytes?: number }): number {
+  const limit = resolveInboundBodyLimitBytes(config.maxInboundBodyBytes);
+  const requested = config.maxInboundBodyBytes;
+  if (requested !== undefined && requested > 0 && requested !== limit) {
+    console.warn(
+      `[server] maxInboundBodyBytes=${requested} is outside the supported range `
+      + `[${MIN_CONFIGURABLE_INBOUND_BODY_BYTES}, ${MAX_CONFIGURABLE_INBOUND_BODY_BYTES}]; `
+      + `using ${limit} bytes.`,
+    );
+  }
+  return limit;
+}
+
 export function warnPlaintextV2AgentMessagesStartup(config: { plaintextV2AgentMessages?: boolean }): void {
   if (config.plaintextV2AgentMessages !== true) return;
   console.warn("⚠️  Experimental plaintext V2 agent messages are enabled.");
diff --git a/src/server/lifecycle.ts b/src/server/lifecycle.ts
index c3ab23e641b..fc757cc0670 100644
--- a/src/server/lifecycle.ts
+++ b/src/server/lifecycle.ts
@@ -357,12 +357,12 @@ export function getServerListenPort(): number | undefined {
  *   caller sees the same result before a replacement binds the port. Swallowing it would let
  *   `drainAndShutdown` report success while a socket is still held.
  *
- * `always` runs after the listeners regardless of their outcome, and its own failure joins the
- * reported set rather than replacing it.
+ * `always` runs after the listeners regardless of their outcome and receives whether every
+ * listener stop succeeded. Its own failure joins the reported set rather than replacing it.
  */
 export async function runListenerShutdown(
   steps: Array<() => Promise<void>>,
-  always: () => Promise<void>,
+  always: (listenersStopped: boolean) => Promise<void>,
 ): Promise<void> {
   const failures: unknown[] = [];
   // Close admission and start connection-owner cleanup before waiting for any drain.
@@ -372,7 +372,7 @@ export async function runListenerShutdown(
     if (result.status === "rejected") failures.push(result.reason);
   }
   try {
-    await always();
+    await always(failures.length === 0);
   } catch (error) {
     failures.push(error);
   }
diff --git a/src/server/live-call-bindings.ts b/src/server/live-call-bindings.ts
index dd90e8aa434..d7400f5e913 100644
--- a/src/server/live-call-bindings.ts
+++ b/src/server/live-call-bindings.ts
@@ -9,6 +9,12 @@ export interface LiveCallBinding {
   upstreamCallId: string;
   joinStyle: "frameless-path" | "realtime-query";
   providerName: string;
+  /**
+   * The model this call settled on when it was created. A join names no model
+   * of its own, so this is what a per-key scope is judged against on reconnect
+   * — without it, a call created for one model could be rejoined as another.
+   */
+  model?: string;
   accountId?: string;
   chatgptAccountId?: string;
   keyedCredentialDigest?: string;
diff --git a/src/server/live.ts b/src/server/live.ts
index 62d818fb313..673e93ea8f2 100644
--- a/src/server/live.ts
+++ b/src/server/live.ts
@@ -44,7 +44,8 @@ import { cancelBodyOnAbort, signalWithTimeout } from "../lib/abort";
 import { sidecarEnter } from "../lib/sidecar-tracker";
 import type { OcxConfig } from "../types";
 import { resolveFirstUsableOpenAiSidecar, selectOpenAiImagesProvider } from "../providers/openai-sidecar";
-import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "./auth-cors";
+import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential, type DataPlaneAdmission } from "./auth-cors";
+import { admissionScopeDenial } from "./admission-model-scope";
 import type { RequestLogContext } from "./request-log";
 import { codexLogAccountId } from "./responses";
 import type { AdmissionLease } from "../lib/admission";
@@ -550,6 +551,62 @@ async function readRequestBodyCapped(req: Request, maxBytes: number): Promise<Ar
   }
 }
 
+/**
+ * Who is asking and for which live model, as far as a per-key scope is concerned.
+ *
+ * This path has no router to resolve a destination, so the model is read where
+ * the client states it — the call-create session, or a standalone socket's own
+ * query — and the provider is whichever OpenAI upstream this relay settles on.
+ * `model` is undefined when nobody stated one: a call-create that sends no
+ * session model, or a join onto a call this compatibility path never recorded.
+ */
+export interface LiveScopeDestination {
+  admission?: DataPlaneAdmission;
+  model: string | undefined;
+}
+
+/**
+ * The live model a call-create body names, or undefined when it names none.
+ *
+ * Both inbound shapes carry it at `session.model` — JSON directly, multipart in
+ * the `session` field — and this path relays the body upstream unchanged, so
+ * the string is the destination rather than a selector the proxy rewrites. A
+ * body that states nothing readable leaves the model to the upstream, which is
+ * a destination no model list can describe.
+ */
+export async function liveCallCreateModel(body: ArrayBuffer, contentType: string): Promise<string | undefined> {
+  try {
+    let session: unknown;
+    if (contentType.toLowerCase().includes("multipart/form-data")) {
+      const form = await new Response(body, { headers: { "content-type": contentType } }).formData();
+      const raw = form.get("session");
+      session = typeof raw === "string" ? JSON.parse(raw) : undefined;
+    } else {
+      session = (JSON.parse(new TextDecoder().decode(body)) as { session?: unknown } | null)?.session;
+    }
+    const model = (session as { model?: unknown } | null | undefined)?.model;
+    return typeof model === "string" && model.trim() ? model.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The model a sideband upgrade is for, or undefined when the request names none.
+ *
+ * A standalone session states it in the query it forwards. A join names nothing
+ * of its own: the call it attaches to chose a model at create time, and only a
+ * recorded binding can say which. This compatibility path keeps no such record,
+ * so a native join is undefined here and the external path in `audio-live.ts`
+ * supplies the model its binding stored.
+ */
+export function liveSidebandModel(target: LiveSidebandTarget): string | undefined {
+  if (target.style === "realtime-standalone" || target.style === "frameless-standalone") {
+    return new URLSearchParams(target.query).get("model")?.trim() || undefined;
+  }
+  return undefined;
+}
+
 /**
  * Resolve OpenAI/ChatGPT auth + headers for live HTTP or sideband WebSocket relays.
  * Shared by call-create and sideband so pool token override stays consistent.
@@ -559,6 +616,7 @@ export async function resolveLiveRelay(
   config: OcxConfig,
   logCtx: RequestLogContext,
   turnAdmissionLease?: AdmissionLease,
+  destination?: LiveScopeDestination,
 ): Promise<LiveRelayTarget | Response> {
   try {
     validateForwardAdmissionCredential(req.headers, config);
@@ -624,8 +682,22 @@ export async function resolveLiveRelay(
 
   // Client protocol headers first so provider/auth headers below always win on conflict.
   const headers: Record<string, string> = clientProtocolHeaders(req.headers);
+  const scopedModel = destination?.model;
   if (forward) {
     const { provider } = forward;
+    // The upstream is settled here and voice bills it for whatever model this
+    // request carries. Refuse before any of it is sent, and give back the probe
+    // lease the resolution took. A join states no model and this path keeps no
+    // record of the call it attaches to, so a key with a model list is refused
+    // there rather than admitted against an assumed default.
+    const denial = admissionScopeDenial(config, destination?.admission, scopedModel, {
+      providerName: forward.providerName,
+      modelId: scopedModel,
+    });
+    if (denial) {
+      forward.releaseProbeLease?.();
+      return denial;
+    }
     if (provider.headers) Object.assign(headers, provider.headers);
     for (const [name, value] of forward.headers) headers[name] = value;
     logCtx.model = "gpt-live";
@@ -640,6 +712,11 @@ export async function resolveLiveRelay(
   if (forwardAuthError) return forwardAuthError;
   if (candidates.keyed) {
     const { provider, apiKey, providerName } = candidates.keyed;
+    const denial = admissionScopeDenial(config, destination?.admission, scopedModel, {
+      providerName,
+      modelId: scopedModel,
+    });
+    if (denial) return denial;
     if (provider.headers) Object.assign(headers, provider.headers);
     headers.authorization = `Bearer ${apiKey}`;
     logCtx.provider = providerName;
@@ -663,13 +740,17 @@ export async function handleLive(
   config: OcxConfig,
   logCtx: RequestLogContext,
   turnAdmissionLease?: AdmissionLease,
+  admission?: DataPlaneAdmission,
 ): Promise<Response> {
   const inboundContentType = req.headers.get("content-type") ?? "application/octet-stream";
   const inboundBodyOrError = await readRequestBodyCapped(req, LIVE_REQUEST_MAX_BYTES);
   if (inboundBodyOrError instanceof Response) return inboundBodyOrError;
   const inboundBody = inboundBodyOrError;
 
-  const relay = await resolveLiveRelay(req, config, logCtx, turnAdmissionLease);
+  const relay = await resolveLiveRelay(req, config, logCtx, turnAdmissionLease, {
+    admission,
+    model: await liveCallCreateModel(inboundBody, inboundContentType),
+  });
   if (relay instanceof Response) return relay;
 
   const headers: Record<string, string> = { ...relay.headers };
@@ -766,8 +847,12 @@ export async function resolveLiveSidebandUpgrade(
   logCtx: RequestLogContext,
   target: LiveSidebandTarget,
   turnAdmissionLease?: AdmissionLease,
+  admission?: DataPlaneAdmission,
 ): Promise<{ headers: Record<string, string>; upstreamWsUrl: string; recordOutcome?: LiveRelayTarget["recordOutcome"] } | Response> {
-  const relay = await resolveLiveRelay(req, config, logCtx, turnAdmissionLease);
+  const relay = await resolveLiveRelay(req, config, logCtx, turnAdmissionLease, {
+    admission,
+    model: liveSidebandModel(target),
+  });
   if (relay instanceof Response) return relay;
   return {
     headers: relay.headers,
diff --git a/src/server/management-api.ts b/src/server/management-api.ts
index 7c8766367c2..63733717d9b 100644
--- a/src/server/management-api.ts
+++ b/src/server/management-api.ts
@@ -1,6 +1,5 @@
 import { remoteWorkspaceEnabled } from "../remote-control/workspace-activation";
 import { randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../codex/catalog";
 import { catalogModelSlug, invalidateCodexModelsCache, nativeContextLimits, nativeModelRows, uniqueCatalogModelsForPublicList } from "../codex/catalog";
 import {
@@ -71,6 +70,8 @@ import { handleOauthAccountRoutes } from "./management/oauth-account-routes";
 import { handleComboRoutes } from "./management/combo-routes";
 import { handleSystemRoutes } from "./management/system-routes";
 import { handleSidebarRoutes } from "./management/sidebar-routes";
+import { handleUsageTimelineRoutes } from "./management/usage-timeline-routes";
+import { handleCompanionRoutes } from "./management/companion-routes";
 import { handleCodexPromptRoutes } from "./management/codex-prompt-routes";
 import { handleIntegrationRoutes } from "./management/integration-routes";
 import { handleNativeIntegrationRoutes } from "./management/native-integration-routes";
@@ -84,15 +85,11 @@ import type { CatalogDisposition, ConvergeCodex } from "../codex/convergence-typ
 import { normalizeCatalogDisposition } from "../codex/catalog-refresh-status";
 import { managementBodyTooLargeResponse } from "./management/body";
 import { handleSessionRoutes } from "./management/session-routes";
+import { packageVersion } from "../lib/package-version";
 
 // installed npm version instead of a stale hardcode.
-export const VERSION = (() => {
-  try {
-    return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version as string;
-  } catch {
-    return "0.0.0";
-  }
-})();
+const MANAGEMENT_VERSION_FALLBACK = "0.0.0";
+export const VERSION = packageVersion(MANAGEMENT_VERSION_FALLBACK);
 
 const managementConvergenceBindings = new WeakMap<object, Readonly<{
   factory: (config: Readonly<OcxConfig>) => ConvergeCodex;
@@ -266,7 +263,7 @@ export async function handleManagementAPI(
     } catch { /* best-effort */ }
   }
   const ctx: ManagementContext = { req, url, config, deps, version: VERSION, principal, sessionControl, convergeCodexCatalog, syncClaudeAgentDefsBestEffort };
-  let routed: Response | null;
+  let routed: Response | null | undefined;
   try {
     routed = handleSessionRoutes(ctx)
     ??     (await handleRemoteWorkspaceRoutesOnDemand(ctx))
@@ -291,6 +288,8 @@ export async function handleManagementAPI(
     ??     (await handleComboRoutes(ctx))
     ??     (await handleSystemRoutes(ctx))
     ??     (await handleLabRoutesOnDemand(ctx))
+      ?? (await handleUsageTimelineRoutes(ctx))
+      ?? (await handleCompanionRoutes(ctx))
       ?? (await handleSidebarRoutes(ctx));
   } catch (error) {
     const tooLarge = managementBodyTooLargeResponse(error, req, config);
diff --git a/src/server/management/agent-settings-routes.ts b/src/server/management/agent-settings-routes.ts
index ef553702087..91976c144fd 100644
--- a/src/server/management/agent-settings-routes.ts
+++ b/src/server/management/agent-settings-routes.ts
@@ -131,6 +131,17 @@ function persistDesktopProfileField(
   return { ok: true };
 }
 
+async function persistDesktopModeField(
+  config: OcxConfig,
+  desktopMode: "first-party" | "gateway",
+): Promise<{ ok: true } | { ok: false; reason: "missing" | "invalid" | "conflict" }> {
+  const { recordClaudeDesktopMode } = await import("../../claude/desktop-first-party");
+  const outcome = mutatePersistedConfig(persisted => recordClaudeDesktopMode(persisted, desktopMode));
+  if (outcome.status === "unavailable") return { ok: false, reason: outcome.reason };
+  recordClaudeDesktopMode(config, desktopMode);
+  return { ok: true };
+}
+
 export function grokApplyFlightSnapshot(): { currentBytes: number; highWaterBytes: number; active: number } {
   return {
     currentBytes: grokApplyFlight?.bytes ?? 0,
@@ -1002,7 +1013,9 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   if (url.pathname === "/api/claude-desktop/apply" && req.method === "POST") {
     try {
       // #859: the CLI delegates here so the registry is built in the serving
-      // process. Accept an optional mode; default stays static for back-compat.
+      // process. `mode` selects the Desktop mode: `first-party` (default when the
+      // install has no gateway profile) or `gateway`; the legacy gateway shapes
+      // (static/hybrid/discovery) still select gateway with that library layout.
       let mode: "static" | "hybrid" | "discovery" = "static";
       let parsed: unknown;
       try {
@@ -1011,12 +1024,17 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         rethrowManagementBodyTooLarge(error);
         return jsonResponse({ error: "invalid JSON body" }, 400);
       }
+      const { resolveClaudeDesktopApplyMode, applyDesktopFirstParty, removeDesktopFirstParty } = await import("../../claude/desktop-first-party");
       const requested = (parsed as { mode?: unknown } | null)?.mode;
+      let desktopMode: "first-party" | "gateway" = resolveClaudeDesktopApplyMode(config);
       if (requested !== undefined) {
         if (requested === "static" || requested === "hybrid" || requested === "discovery") {
           mode = requested;
+          desktopMode = "gateway";
+        } else if (requested === "gateway" || requested === "first-party") {
+          desktopMode = requested;
         } else {
-          return jsonResponse({ error: "mode must be static, hybrid, or discovery" }, 400);
+          return jsonResponse({ error: "mode must be first-party, gateway, static, hybrid, or discovery" }, 400);
         }
       }
       // #859: a delegated CLI apply carries the profile it just saved — the
@@ -1032,6 +1050,63 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
           return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
         }
       }
+      if (desktopMode === "first-party") {
+        const { setIntegrationEnabled } = await import("../../codex/desired-state");
+        const desired = setIntegrationEnabled("claude-desktop", true);
+        if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
+        mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
+        // First-party replaces gateway: the two must never be active together.
+        const { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot } = await import("../../claude/desktop-3p");
+        const appliedFingerprint = config.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
+        const library = inspectDesktop3pConfigLibrary({ appliedFingerprint });
+        let gatewayRemoved = false;
+        if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
+          const removed = (deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint, replaceWhileEnabled: true });
+          if (!removed.ok) {
+            return jsonResponse({
+              error: removed.kind === "cleanup_incomplete"
+                ? "Claude Desktop now points at standard mode, but gateway credential cleanup is incomplete; first-party env was not applied."
+                : "The gateway profile could not be removed safely, so first-party mode was not applied.",
+              code: "claude_desktop_gateway_removal_failed",
+              reason: removed.reason ?? removed.kind,
+              ...(removed.residualPaths ? { residualPaths: removed.residualPaths } : {}),
+            }, removed.kind === "cleanup_incomplete" ? 500 : 409);
+          }
+          gatewayRemoved = removed.changed;
+        }
+        const applied = applyDesktopFirstParty(config);
+        if (!applied.ok) {
+          const { firstPartyRefusalMessage } = await import("./native-integration-routes");
+          return jsonResponse({
+            error: firstPartyRefusalMessage(applied.reason, applied.path),
+            code: "claude_desktop_first_party_refused",
+            reason: applied.reason,
+            path: applied.path,
+          }, applied.reason === "foreign_env" || applied.reason === "intercept_disabled" ? 409 : 500);
+        }
+        const modeSaved = await persistDesktopModeField(config, "first-party");
+        return jsonResponse({
+          ok: true,
+          mode: "first-party",
+          saved: modeSaved.ok,
+          applied: true,
+          changed: applied.changed || gatewayRemoved,
+          gatewayRemoved,
+          path: applied.path,
+          proxyPort: applied.proxyPort,
+          caCertPath: applied.env.NODE_EXTRA_CA_CERTS,
+          ...(modeSaved.ok ? {} : { warning: `First-party env was applied, but the mode marker was not saved (${modeSaved.reason}).` }),
+        });
+      }
+      // Gateway mode replaces first-party: the two must never be active together.
+      const firstPartyRemoved = removeDesktopFirstParty();
+      if (!firstPartyRemoved.ok) {
+        return jsonResponse({
+          error: `Claude Code settings could not be parsed (${firstPartyRemoved.path}); the first-party proxy env could not be removed before switching to gateway mode.`,
+          code: "claude_desktop_first_party_refused",
+          reason: firstPartyRemoved.reason,
+        }, 500);
+      }
       const { setIntegrationEnabled, claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
       const desired = setIntegrationEnabled("claude-desktop", true);
       if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
@@ -1083,6 +1158,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         nativeContextLimits(latest),
       );
       if (!result.written) return jsonResponse({ error: result.reason ?? "Claude Desktop apply failed", saved: true, path: result.path }, 500);
+      const modeSaved = await persistDesktopModeField(config, "gateway");
+      const modeWarning = modeSaved.ok ? undefined : `Claude Desktop was applied, but the gateway mode marker was not saved (${modeSaved.reason}).`;
       const { claudeDesktopPolicyWarning, probeClaudeDesktopPolicy } = await import("../../claude/desktop-policy");
       const policyState = (deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)({
         platform: deps.platform ?? process.platform,
@@ -1106,19 +1183,22 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
             fingerprint: result.fingerprint,
             warning: [
               `Claude Desktop was applied, but the applied marker was not saved (${marked.reason}).`,
+              modeWarning,
               policyWarning,
             ].filter(Boolean).join(" "),
           });
         }
       }
+      const warning = [modeWarning, policyWarning].filter(Boolean).join(" ");
       return jsonResponse({
         ok: true,
-        saved: true,
+        mode: "gateway",
+        saved: modeSaved.ok,
         applied: true,
         path: result.path,
         fingerprint: result.fingerprint,
         policyState,
-        ...(policyWarning ? { warning: policyWarning } : {}),
+        ...(warning ? { warning } : {}),
       });
     } catch (error) {
       rethrowManagementBodyTooLarge(error);
@@ -1131,21 +1211,39 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     try {
       const { claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
       const { inspectDesktop3pConfigLibrary } = await import("../../claude/desktop-3p");
+      const { resolveClaudeDesktopApplyMode, inspectDesktopFirstParty } = await import("../../claude/desktop-first-party");
+      const { getClaudeInterceptState } = await import("../../claude/intercept/runtime");
       const persisted = loadConfig();
       const savedFingerprint = persisted.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
       const observed = inspectDesktop3pConfigLibrary({ appliedFingerprint: savedFingerprint });
       const desiredEnabled = claudeDesktopIntegrationEnabled(persisted);
-      const applied = observed.kind === "gateway_ours" || observed.kind === "gateway_drifted";
+      const gatewayApplied = observed.kind === "gateway_ours" || observed.kind === "gateway_drifted";
+      // A gateway profile on disk is what Desktop actually runs, whatever the saved mode says.
+      const mode = gatewayApplied ? "gateway" : resolveClaudeDesktopApplyMode(persisted);
+      const firstPartySeen = inspectDesktopFirstParty(persisted);
+      const intercept = getClaudeInterceptState();
+      const firstParty = {
+        settingsState: firstPartySeen.settings.kind,
+        applied: firstPartySeen.applied,
+        stale: firstPartySeen.stale,
+        interceptEnabled: firstPartySeen.interceptEnabled,
+        interceptRunning: intercept !== null,
+        proxyPort: intercept?.proxyPort ?? firstPartySeen.proxyPort,
+        caCertPath: firstPartySeen.caCertPath,
+      };
+      const applied = mode === "first-party" ? firstPartySeen.applied : gatewayApplied;
       // "Needs update" is only meaningful while the integration is wanted. When the
       // durable switch is OFF, a leftover drifted profile is residue to clear — not
       // a stale apply the operator should refresh.
-      const stale = desiredEnabled && observed.kind === "gateway_drifted";
+      const stale = desiredEnabled && (mode === "first-party" ? firstPartySeen.stale : observed.kind === "gateway_drifted");
       const { getDesktopHealth } = await import("../../claude/desktop-health");
       const { claudeDesktopPolicyHealth, probeClaudeDesktopPolicy } = await import("../../claude/desktop-policy");
       const policyState = (deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)({
         platform: deps.platform ?? process.platform,
       });
-      const policy = claudeDesktopPolicyHealth(policyState);
+      // Managed-policy conflicts only matter for the gateway profile; first-party mode never
+      // touches Desktop's own configuration.
+      const policy = claudeDesktopPolicyHealth(mode === "first-party" ? "absent" : policyState);
       const health = {
         ...getDesktopHealth(),
         ok: policy.ok,
@@ -1153,14 +1251,19 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         policy,
       };
       const policyConflict = desiredEnabled && !policy.ok;
-      const baseDrift = desiredEnabled ? !applied || stale : applied || observed.kind === "unsafe";
+      const firstPartyResidue = mode === "gateway" && (firstPartySeen.applied || firstPartySeen.stale);
+      const baseDrift = desiredEnabled
+        ? !applied || stale || firstPartyResidue
+        : applied || gatewayApplied || firstPartySeen.applied || firstPartySeen.stale || observed.kind === "unsafe";
       const driftReason = policyConflict
         ? policy.state === "present" ? "managed_policy_present" : "managed_policy_unknown"
         : desiredEnabled
-          ? !applied ? "desired_on_not_current" : stale ? "profile_drift" : null
-          : applied ? "desired_off_gateway_selected" : null;
+          ? !applied ? "desired_on_not_current" : stale ? "profile_drift" : firstPartyResidue ? "first_party_residue" : null
+          : gatewayApplied ? "desired_off_gateway_selected" : firstPartySeen.applied || firstPartySeen.stale ? "desired_off_first_party_env" : null;
       return jsonResponse({
         desiredEnabled,
+        mode,
+        firstParty,
         installed: observed.kind !== "not_installed",
         observedKind: observed.kind,
         applied,
diff --git a/src/server/management/companion-routes.ts b/src/server/management/companion-routes.ts
new file mode 100644
index 00000000000..c33f7d9eac9
--- /dev/null
+++ b/src/server/management/companion-routes.ts
@@ -0,0 +1,76 @@
+import {
+  applyCompanionSettingsPatch,
+  DEFAULT_COMPANION_SETTINGS,
+  loadCompanionSettings,
+  saveCompanionSettings,
+} from "../../companion/settings";
+import { jsonResponse } from "../auth-cors";
+import { openUrl } from "../../lib/open-url";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import type { ManagementContext } from "./context";
+
+let companionPresence: { lastSeenAt: number; kind: "menuBar" | "desktop" } | null = null;
+
+export function resetCompanionPresenceForTests(): void {
+  companionPresence = null;
+}
+
+function response(): Response {
+  const loaded = loadCompanionSettings();
+  return jsonResponse({
+    settings: loaded.settings,
+    updatedAt: loaded.updatedAt,
+    defaults: DEFAULT_COMPANION_SETTINGS,
+    companion: companionPresence ?? { lastSeenAt: null },
+    ...(loaded.corrupt ? { corrupt: true } : {}),
+  });
+}
+
+export async function handleCompanionRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname === "/api/companion/open-in-browser" && ctx.req.method === "POST") {
+    let body: unknown;
+    try {
+      body = await readManagementJsonBody(ctx.req);
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      return jsonResponse({ error: "invalid path" }, 400, ctx.req, ctx.config);
+    }
+    const path = body && typeof body === "object" && !Array.isArray(body)
+      ? (body as { path?: unknown }).path
+      : undefined;
+    if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//") || path.length > 512) {
+      return jsonResponse({ error: "invalid path" }, 400, ctx.req, ctx.config);
+    }
+    const url = `http://127.0.0.1:${ctx.config.port}${path}`;
+    openUrl(url);
+    return jsonResponse({ ok: true, url }, 200, ctx.req, ctx.config);
+  }
+  if (ctx.url.pathname === "/api/companion/settings" && ctx.req.method === "GET") {
+    const userAgent = ctx.req.headers.get("user-agent") ?? "";
+    const kind = userAgent.startsWith("OpenCodexMenuBar/") ? "menuBar"
+      : userAgent.startsWith("OpenCodexDesktop/") ? "desktop"
+      : null;
+    if (kind) companionPresence = { lastSeenAt: Date.now(), kind };
+    return response();
+  }
+  if (ctx.url.pathname !== "/api/companion/settings" || ctx.req.method !== "PUT") return null;
+  let body: unknown;
+  try {
+    body = await readManagementJsonBody(ctx.req);
+  } catch (error) {
+    rethrowManagementBodyTooLarge(error);
+    return jsonResponse({ error: "invalid JSON body" }, 400, ctx.req, ctx.config);
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) return jsonResponse({ error: "invalid settings body" }, 400, ctx.req, ctx.config);
+  const input = body as { reset?: unknown; settings?: unknown };
+  if (input.reset === true) {
+    saveCompanionSettings(DEFAULT_COMPANION_SETTINGS);
+    return response();
+  }
+  if (!("settings" in input)) return jsonResponse({ error: "provide settings or reset:true" }, 400, ctx.req, ctx.config);
+  const current = loadCompanionSettings().settings;
+  const updated = applyCompanionSettingsPatch(current, input.settings);
+  if ("error" in updated) return jsonResponse(updated, 400, ctx.req, ctx.config);
+  saveCompanionSettings(updated);
+  return response();
+}
diff --git a/src/server/management/logs-usage-routes.ts b/src/server/management/logs-usage-routes.ts
index cd1e3ed3b0f..51bf12725ea 100644
--- a/src/server/management/logs-usage-routes.ts
+++ b/src/server/management/logs-usage-routes.ts
@@ -22,6 +22,7 @@ import {
   upsertOAuthProvider,
 } from "../../oauth";
 import { removeCredential } from "../../oauth/store";
+import { getFailureProjection } from "../../usage/failure-projection-cache";
 import { providerDestinationResolvedError } from "../../lib/destination-policy";
 import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
 import { deriveProviderPresets } from "../../providers/derive";
@@ -179,6 +180,24 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
   }
 
   if (url.pathname === "/api/usage" && req.method === "GET") {
+    // A sub-resource on the same route rather than a route of its own. It answers a different
+    // question -- which failures keep recurring, rather than what was spent -- and it costs a
+    // ledger scan, so it is opt-in: a dashboard asking for the usage summary must not pay for
+    // a projection it did not ask for.
+    if (url.searchParams.get("failures") === "1") {
+      const projection = await getFailureProjection();
+      return jsonResponse({
+        fingerprintVersion: projection.fingerprintVersion,
+        historyIncomplete: projection.historyIncomplete,
+        unattributedFailures: projection.unattributedFailures,
+        invalidTimestampFailures: projection.invalidTimestampFailures,
+        // Every field here is a closed roster member, a count or a timestamp. The scanner's
+        // checkpoint identity, the configured provider name, the model and the account label
+        // stay internal -- a grouping that promises to carry no content has to keep that
+        // promise at its boundary too.
+        failures: projection.groups,
+      });
+    }
     const range = parseRange(url.searchParams.get("range"));
     const surface = parseUsageSurface(url.searchParams.get("surface"));
     let window: UsageTimeWindow | undefined;
diff --git a/src/server/management/native-integration-routes.ts b/src/server/management/native-integration-routes.ts
index 56158bd162e..ae20731777a 100644
--- a/src/server/management/native-integration-routes.ts
+++ b/src/server/management/native-integration-routes.ts
@@ -18,13 +18,21 @@
  * 011 (Claude Code), 012 (Grok).
  */
 import { join } from "node:path";
-import { loadConfig, saveConfigPreservingClaudeCode } from "../../config";
+import { loadConfig, mutatePersistedConfig, saveConfigPreservingClaudeCode } from "../../config";
 import { readRuntimePort } from "../../config/process-state";
 import { desktopVisibleNativeSlugs, filterCatalogVisibleModels, nativeContextLimits } from "../../codex/catalog";
 import { getCodexHome } from "../../codex/paths";
 import { providerContextCap } from "../../providers/context-cap";
 import { OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
 import { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot, writeDesktop3pConfig } from "../../claude/desktop-3p";
+import {
+  applyDesktopFirstParty,
+  inspectDesktopFirstParty,
+  recordClaudeDesktopMode,
+  removeDesktopFirstParty,
+  resolveClaudeDesktopApplyMode,
+  type ClaudeDesktopMode,
+} from "../../claude/desktop-first-party";
 import { projectGrokCatalog } from "../../grok/catalog";
 import { injectGrokConfig, stripGrokConfig } from "../../grok/inject";
 import { inspectGrokConfig } from "../../grok/inspect";
@@ -47,7 +55,9 @@ export type NativeRefusalReason =
   | "write_failed"
   | "metadata_unreadable"
   | "cleanup_incomplete"
-  | "desired_state_changed";
+  | "desired_state_changed"
+  | "foreign_env"
+  | "intercept_disabled";
 
 export interface NativeStatus {
   clientId: NativeIntegrationClientId;
@@ -126,7 +136,7 @@ function desktopStatus(config: ManagementContext["config"]): NativeStatus {
   const seen = inspectDesktop3pConfigLibrary({
     appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null,
   });
-  const state: NativeStatus["state"] = seen.kind === "gateway_ours"
+  const gatewayState: NativeStatus["state"] = seen.kind === "gateway_ours"
     ? "current"
     : seen.kind === "unsafe" || seen.kind === "broken" ? "unsafe" : "absent";
   const disableBlocked = seen.kind === "unsafe" || seen.kind === "broken" || seen.kind === "foreign"
@@ -135,6 +145,14 @@ function desktopStatus(config: ManagementContext["config"]): NativeStatus {
         message: "Claude Desktop configuration cannot be changed safely.",
       }
     : null;
+  // First-party mode lives in Claude Code's settings.json, not in Desktop's library. A leftover
+  // gateway profile still counts as current (it is what Desktop is actually running).
+  const firstParty = resolveClaudeDesktopApplyMode(config) === "first-party" && gatewayState === "absent"
+    ? inspectDesktopFirstParty(config)
+    : null;
+  const state: NativeStatus["state"] = firstParty
+    ? firstParty.settings.kind === "unreadable" ? "unsafe" : firstParty.applied ? "current" : "absent"
+    : gatewayState;
   return {
     clientId: "claude-desktop",
     state,
@@ -599,6 +617,28 @@ async function handleGrokToggle(ctx: ManagementContext): Promise<Response> {
   }
 }
 
+export function firstPartyRefusalMessage(
+  reason: "intercept_disabled" | "ca_unavailable" | "unreadable" | "foreign_env",
+  path: string,
+): string {
+  switch (reason) {
+    case "intercept_disabled":
+      return "First-party mode needs the Claude intercept proxy, which is off in this configuration (claudeCode.intercept.enabled / client role). Use gateway mode instead.";
+    case "ca_unavailable":
+      return `The local intercept certificate could not be created (${path}).`;
+    case "unreadable":
+      return `Claude Code settings could not be parsed (${path}); nothing was written.`;
+    case "foreign_env":
+      return `Claude Code settings already set HTTPS_PROXY or NODE_EXTRA_CA_CERTS to a value opencodex does not own (${path}); remove them first or use gateway mode.`;
+  }
+}
+
+/** Record which Desktop mode is applied; `false` when the config file could not be updated. */
+function persistDesktopModeMarker(desktopMode: ClaudeDesktopMode): boolean {
+  const outcome = mutatePersistedConfig(persisted => recordClaudeDesktopMode(persisted, desktopMode));
+  return outcome.status !== "unavailable";
+}
+
 let claudeDesktopToggleFlight: Promise<Response> | null = null;
 
 async function handleClaudeDesktopToggle(ctx: ManagementContext): Promise<Response> {
@@ -626,6 +666,11 @@ async function handleClaudeDesktopToggle(ctx: ManagementContext): Promise<Respon
     const fingerprint = current.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
 
     if (!body.enabled) {
+      const firstPartyRemoved = removeDesktopFirstParty();
+      if (!firstPartyRemoved.ok) {
+        return postCommitRefusal(409, "claude-desktop", "write_failed",
+          `Claude Code settings could not be read (${firstPartyRemoved.path}); the first-party proxy env was left in place.`, { desiredEnabled });
+      }
       const removed = (ctx.deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint: fingerprint });
       if (removed.kind === "cleanup_incomplete") {
         return postCommitRefusal(500, "claude-desktop", "cleanup_incomplete",
@@ -636,9 +681,47 @@ async function handleClaudeDesktopToggle(ctx: ManagementContext): Promise<Respon
         return postCommitRefusal(409, "claude-desktop", removed.reason === "metadata_unreadable" ? "metadata_unreadable" : "write_failed",
           "Claude Desktop configuration could not be changed safely.", { desiredEnabled });
       }
+      const changed = removed.changed || firstPartyRemoved.changed;
+      return jsonResponse({
+        ok: true, clientId: "claude-desktop", changed, state: "absent", desiredEnabled,
+        message: changed ? "Claude Desktop integration disabled." : "Claude Desktop integration is already off.",
+      } satisfies NativeToggleEnvelope);
+    }
+
+    if (resolveClaudeDesktopApplyMode(current) === "first-party") {
+      // Same contract as POST /api/claude-desktop/apply: an owned gateway profile left on disk
+      // is pivoted to standard first, so the two modes are never active together.
+      const library = inspectDesktop3pConfigLibrary({ appliedFingerprint: fingerprint });
+      let gatewayRemoved = false;
+      if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
+        const removed = (ctx.deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint: fingerprint, replaceWhileEnabled: true });
+        if (removed.kind === "cleanup_incomplete") {
+          return postCommitRefusal(500, "claude-desktop", "cleanup_incomplete",
+            "Claude Desktop now points at standard mode, but gateway credential cleanup is incomplete; first-party env was not applied.",
+            { desiredEnabled, residualPaths: removed.residualPaths ?? [] });
+        }
+        if (!removed.ok) {
+          return postCommitRefusal(409, "claude-desktop", removed.reason === "metadata_unreadable" ? "metadata_unreadable" : "write_failed",
+            "The gateway profile could not be removed safely, so first-party mode was not applied.", { desiredEnabled });
+        }
+        gatewayRemoved = removed.changed;
+      }
+      const applied = applyDesktopFirstParty(current);
+      if (!applied.ok) {
+        const reason = applied.reason === "foreign_env" || applied.reason === "intercept_disabled" ? applied.reason : "write_failed";
+        return postCommitRefusal(applied.reason === "unreadable" || applied.reason === "ca_unavailable" ? 500 : 409, "claude-desktop", reason,
+          firstPartyRefusalMessage(applied.reason, applied.path), { desiredEnabled });
+      }
+      const modeSaved = persistDesktopModeMarker("first-party");
+      const changed = applied.changed || gatewayRemoved;
       return jsonResponse({
-        ok: true, clientId: "claude-desktop", changed: removed.changed, state: "absent", desiredEnabled,
-        message: removed.changed ? "Claude Desktop integration disabled." : "Claude Desktop integration is already off.",
+        ok: true, clientId: "claude-desktop", changed, state: "current", desiredEnabled,
+        message: [
+          changed
+            ? "Claude Desktop integration enabled (first-party). Fully quit and reopen Claude Desktop."
+            : "Claude Desktop integration is already on.",
+          modeSaved ? "" : "The first-party mode marker could not be saved to config; status may report the mode as unsaved.",
+        ].filter(Boolean).join(" "),
       } satisfies NativeToggleEnvelope);
     }
 
@@ -665,9 +748,13 @@ async function handleClaudeDesktopToggle(ctx: ManagementContext): Promise<Respon
         nativeContextLimits(latest),
       );
       if (!result.written) return postCommitRefusal(500, "claude-desktop", "write_failed", "Claude Desktop apply failed.", { desiredEnabled: latestDesiredEnabled });
+      const modeSaved = persistDesktopModeMarker("gateway");
       return jsonResponse({
         ok: true, clientId: "claude-desktop", changed: true, state: "current", desiredEnabled: latestDesiredEnabled,
-        message: "Claude Desktop integration enabled.",
+        message: [
+          "Claude Desktop integration enabled.",
+          modeSaved ? "" : "The gateway mode marker could not be saved to config; status may report the mode as unsaved.",
+        ].filter(Boolean).join(" "),
       } satisfies NativeToggleEnvelope);
     } catch {
       return postCommitRefusal(500, "claude-desktop", "write_failed", "Claude Desktop apply failed.", { desiredEnabled });
diff --git a/src/server/management/oauth-account-routes.ts b/src/server/management/oauth-account-routes.ts
index 4cd52004665..0c03a96d3da 100644
--- a/src/server/management/oauth-account-routes.ts
+++ b/src/server/management/oauth-account-routes.ts
@@ -210,7 +210,7 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
       const { shouldOpenBrowserForLogin } = await import("../../oauth/open-browser-choice");
       if (authUrl && !deviceCode && shouldOpenBrowserForLogin(body.openBrowser, config)) {
         const { openUrl } = await import("../../lib/open-url");
-        openUrl(authUrl);
+        void openUrl(authUrl);
       }
       return jsonResponse({ url: authUrl, instructions, deviceCode });
     } catch (err) {
@@ -869,6 +869,10 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
         name: k.name,
         prefix: k.key.slice(0, 17) + "...",
         createdAt: k.createdAt,
+        // Scope is metadata, not secret: an operator has to be able to read
+        // what a key may reach without minting a replacement to find out.
+        ...(k.allowedProviders ? { allowedProviders: [...k.allowedProviders] } : {}),
+        ...(k.allowedModels ? { allowedModels: [...k.allowedModels] } : {}),
         ...(k.pendingRotation ? { pendingRotation: {
           id: k.pendingRotation.id,
           createdAt: k.pendingRotation.createdAt,
@@ -952,15 +956,46 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     const body = await readJsonBody(req);
     if (!body) return jsonResponse({ error: "invalid body" }, 400, req, config);
     if (typeof body.id !== "string" || !body.id) return jsonResponse({ error: "id required" }, 400, req, config);
-    const nameField = validateKeyName(body.name, { required: true });
-    if ("error" in nameField) return jsonResponse({ error: nameField.error }, 400, req, config);
     const entry = (config.apiKeys ?? []).find(k => k.id === body.id);
     if (!entry) return jsonResponse({ error: "key not found" }, 404, req, config);
-    entry.name = nameField.value;
+    // Rename and scope are independent edits. A scope-only PATCH must not have
+    // to restate the name, and a rename must not silently widen a scope, so
+    // each field is applied only when the caller actually sent it.
+    const renaming = body.name !== undefined;
+    const scopingProviders = body.allowedProviders !== undefined;
+    const scopingModels = body.allowedModels !== undefined;
+    if (!renaming && !scopingProviders && !scopingModels) {
+      return jsonResponse({ error: "name, allowedProviders or allowedModels required" }, 400, req, config);
+    }
+    if (renaming) {
+      const nameField = validateKeyName(body.name, { required: true });
+      if ("error" in nameField) return jsonResponse({ error: nameField.error }, 400, req, config);
+      entry.name = nameField.value;
+    }
+    for (const [field, sent] of [["allowedProviders", scopingProviders], ["allowedModels", scopingModels]] as const) {
+      if (!sent) continue;
+      const value = body[field];
+      // `null` and `[]` both clear the list back to unrestricted; anything else
+      // must be a list of non-empty strings, because a silently ignored malformed
+      // scope would read as "allowed everything" to whoever set it.
+      if (value === null) { delete entry[field]; continue; }
+      if (!Array.isArray(value) || value.some(item => typeof item !== "string" || !item.trim() || item.length > 256)) {
+        return jsonResponse({ error: `${field} must be a list of non-empty names` }, 400, req, config);
+      }
+      const normalized = [...new Set((value as string[]).map(item => item.trim()))];
+      if (normalized.length === 0) delete entry[field];
+      else entry[field] = normalized;
+    }
     saveConfigPreservingClaudeCode(config);
     reconcileLiveStateStores();
     // Never echo key material from a rename.
-    return jsonResponse({ id: entry.id, name: entry.name, createdAt: entry.createdAt }, 200, req, config);
+    return jsonResponse({
+      id: entry.id,
+      name: entry.name,
+      createdAt: entry.createdAt,
+      ...(entry.allowedProviders ? { allowedProviders: [...entry.allowedProviders] } : {}),
+      ...(entry.allowedModels ? { allowedModels: [...entry.allowedModels] } : {}),
+    }, 200, req, config);
   }
 
   if (url.pathname === "/api/keys" && req.method === "DELETE") {
diff --git a/src/server/management/route-registry.ts b/src/server/management/route-registry.ts
index 95dc71be749..bacf385d7ee 100644
--- a/src/server/management/route-registry.ts
+++ b/src/server/management/route-registry.ts
@@ -240,6 +240,12 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/storage/trash", module: "server/management/logs-usage-routes", mutates: false },
   { method: "GET", path: "/api/storage/trash/restore/test-stream", module: "server/management/logs-usage-routes", mutates: false, exempt: { reason: "test-seam", why: "Opt-in streaming seam declared at src/storage/restore-job.ts:34." } },
   { method: "GET", path: "/api/usage", module: "server/management/logs-usage-routes", mutates: false },
+  // server/management/usage-timeline-routes
+  { method: "GET", path: "/api/usage/timeline", module: "server/management/usage-timeline-routes", mutates: false },
+  // server/management/companion-routes
+  { method: "POST", path: "/api/companion/open-in-browser", module: "server/management/companion-routes", mutates: true, exempt: { reason: "session-only", why: "Dashboard-only navigation helper; the GUI session opens its current view in the system browser, and there is no standalone CLI operation to drive." } },
+  { method: "GET", path: "/api/companion/settings", module: "server/management/companion-routes", mutates: false },
+  { method: "PUT", path: "/api/companion/settings", module: "server/management/companion-routes", mutates: true },
   { method: "POST", path: "/api/storage/cleanup", module: "server/management/logs-usage-routes", mutates: true },
   { method: "POST", path: "/api/storage/cleanup-policy/run", module: "server/management/logs-usage-routes", mutates: true },
   { method: "POST", path: "/api/storage/cleanup/preview", module: "server/management/logs-usage-routes", mutates: true },
diff --git a/src/server/management/shared.ts b/src/server/management/shared.ts
index fa3845250f2..d69adc83d47 100644
--- a/src/server/management/shared.ts
+++ b/src/server/management/shared.ts
@@ -35,12 +35,13 @@ import { clearThreadAccountMap } from "../../codex/routing";
 import { primeCodexPoolQuotas } from "../../codex/auth-api";
 import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
 import { resolveCodexHomeDir } from "../../codex/home";
-import { readUsageEntries } from "../../usage/log";
+import { isKnownRequestFailureCause, isKnownRequestFailureStage, readUsageEntries } from "../../usage/log";
 import { getUsageDebugLogEntries } from "../../usage/debug";
 import { cacheObservationFromUsage, parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
 import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
 import { getProviderRegistryEntry, providerMatchesRegistryTransport } from "../../providers/registry";
 import { getDebugLogEntries } from "../../lib/debug-log-buffer";
+import { resendPermission } from "../../lib/request-failure-model";
 import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
 import {
   clearDebugSettings,
@@ -210,12 +211,27 @@ export function costResult(entry: MetricSource): CostResult {
  * a Logs-page metric, and widening a separate endpoint's response shape is not this change's
  * business. Flipping it on later is one argument.
  */
+
+/**
+ * Whether this proxy could have sent the row again, derived at READ time from the stage and
+ * cause the recorder stored.
+ *
+ * Deliberately not persisted. The verdict is a function of two tables that this build owns, and
+ * a row written months ago must not be able to assert a permission the current tables would
+ * refuse -- the whole point of INV-RESEND-01 is that the refusal rules are one statement, and a
+ * stored verdict would be a second one with no way to correct it.
+ */
+function resendVerdict(row: { failureStage?: string; failureCause?: string }): { resendPermission?: string } {
+  if (!isKnownRequestFailureStage(row.failureStage) || !isKnownRequestFailureCause(row.failureCause)) return {};
+  return { resendPermission: resendPermission(row.failureStage, row.failureCause) };
+}
 export function requestLogDto(
   entry: RequestLogEntry,
   { includeDecodeRate = true }: { includeDecodeRate?: boolean } = {},
 ): Record<string, unknown> {
   return {
     ...entry,
+    ...resendVerdict(entry),
     displayMetrics: {
       tokPerSecond: tokPerSecondResult(entry),
       // The parent uses the REQUEST's own TTFT. A combo parent must not borrow an attempt's,
@@ -227,6 +243,7 @@ export function requestLogDto(
       ? {
         attempts: entry.attempts.map(attempt => ({
           ...attempt,
+          ...resendVerdict(attempt),
           displayMetrics: {
             tokPerSecond: tokPerSecondResult(attempt),
             // Each attempt measures its own attempt-relative TTFT.
diff --git a/src/server/management/usage-timeline-routes.ts b/src/server/management/usage-timeline-routes.ts
new file mode 100644
index 00000000000..d4f04c37186
--- /dev/null
+++ b/src/server/management/usage-timeline-routes.ts
@@ -0,0 +1,44 @@
+import { readUsageSnapshotForManagement } from "../../usage/log";
+import { createTimelineAccumulator, parseTimelineQuery } from "../../usage/timeline";
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+
+const TIMELINE_CACHE_TTL_MS = 15_000;
+const cache = new Map<string, { expiresAt: number; promise: Promise<ReturnType<ReturnType<typeof createTimelineAccumulator>["finish"]>> }>();
+
+export async function handleUsageTimelineRoutes(ctx: ManagementContext): Promise<Response | undefined> {
+  const { req, url } = ctx;
+  if (url.pathname !== "/api/usage/timeline" || req.method !== "GET") return undefined;
+  const query = parseTimelineQuery(url.searchParams, Date.now());
+  if ("error" in query) return jsonResponse(query, 400, req, ctx.config);
+  const bucketMs = query.bucketMinutes * 60_000;
+  const roundedNow = Math.floor(query.now / bucketMs) * bucketMs;
+  const normalized = { ...query, now: roundedNow };
+  const key = JSON.stringify(normalized);
+  const current = Date.now();
+  const cached = cache.get(key);
+  if (cached && cached.expiresAt > current) return jsonResponse(await cached.promise, 200, req, ctx.config);
+  let promise: Promise<ReturnType<ReturnType<typeof createTimelineAccumulator>["finish"]>>;
+  promise = (async () => {
+    const accumulator = createTimelineAccumulator(normalized);
+    const snapshot = await readUsageSnapshotForManagement(ctx.config.managementUsageMaxReadBytes);
+    for (const entry of snapshot.entries) accumulator.add(entry);
+    return {
+      ...accumulator.finish(),
+      truncated: snapshot.truncatedPrefixBytes > 0 || snapshot.entriesTruncated,
+    };
+  })().catch(error => {
+    const entry = cache.get(key);
+    if (entry?.promise === promise) cache.delete(key);
+    throw error;
+  });
+  cache.set(key, { expiresAt: current + TIMELINE_CACHE_TTL_MS, promise });
+  try {
+    return jsonResponse(await promise, 200, req, ctx.config);
+  } finally {
+    setTimeout(() => {
+      const entry = cache.get(key);
+      if (entry?.promise === promise && entry.expiresAt <= Date.now()) cache.delete(key);
+    }, TIMELINE_CACHE_TTL_MS + 1);
+  }
+}
diff --git a/src/server/proxy-liveness.ts b/src/server/proxy-liveness.ts
index 594be867b02..98202e42d86 100644
--- a/src/server/proxy-liveness.ts
+++ b/src/server/proxy-liveness.ts
@@ -32,6 +32,8 @@ export interface HealthzIdentity {
   guiPairCapability?: unknown;
 }
 
+export type EndpointLiveness = "live" | "dead" | "unknown";
+
 export interface LivenessIo {
   fetchFn?: typeof fetch;
   readPidFn?: () => number | null;
@@ -85,6 +87,11 @@ export const START_OWNERSHIP_LIVENESS: Pick<LivenessIo, "timeoutMs" | "attempts"
   attempts: 3,
 };
 
+type LivenessFetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
 export interface LiveProxy {
   pid: number | null;
   port: number;
@@ -148,6 +155,74 @@ export function isOpencodexHealthz(body: HealthzIdentity | null): boolean {
   return body.status === "ok" && typeof body.version === "string" && typeof body.uptime === "number";
 }
 
+/**
+ * "Nothing is listening" is narrower than "the probe failed". Only a connect-phase refusal
+ * proves the endpoint is free; a timeout, reset, or other transport failure leaves the
+ * question open.
+ */
+export function isConnectionRefused(error: unknown): boolean {
+  const visit = (current: unknown, depth: number): boolean => {
+    if (depth >= 4) return false;
+    if (current === null || (typeof current !== "object" && typeof current !== "function")) return false;
+    const record = current as { code?: unknown; cause?: unknown; errors?: unknown };
+    if (record.code === "ECONNREFUSED" || record.code === "ConnectionRefused") return true;
+    if (typeof record.code === "string" && record.code.endsWith("ECONNREFUSED")) return true;
+    if (Array.isArray(record.errors) && record.errors.length > 0) {
+      // One connect attempt fanned out over several addresses reports a single AggregateError.
+      // Only a unanimous refusal proves the endpoint is free: a bundle that mixes ECONNREFUSED
+      // with a timeout means one address answered nothing at all, and an address whose state is
+      // unreadable is unknown, not absence. Collapsing it to "refused" is how a second runtime
+      // gets started on a port that already has one.
+      return record.errors.every(error => visit(error, depth + 1));
+    }
+    return visit(record.cause, depth + 1);
+  };
+  return visit(error, 0);
+}
+
+async function classifyHealthz(
+  url: string,
+  fetchFn: LivenessFetch,
+  timeoutMs: number,
+): Promise<EndpointLiveness> {
+  try {
+    const response = await fetchFn(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (response.status !== 200) return "unknown";
+    const body = (await response.json().catch(() => undefined)) as HealthzIdentity | null | undefined;
+    if (body === undefined) return "unknown";
+    return isOpencodexHealthz(body) ? "live" : "dead";
+  } catch (error) {
+    return isConnectionRefused(error) ? "dead" : "unknown";
+  }
+}
+
+/**
+ * Tri-state probe of one endpoint, the in-process counterpart of
+ * `src/update/proxy-liveness-probe.mjs`. Only a connect-phase refusal or a clean 200 that is
+ * not ours proves "dead"; a timeout, reset, non-200 or unreadable body leaves the question
+ * open. Loopback endpoints are checked on both IPv4 and IPv6 because a listener may bind only
+ * one family. Runs in-process because a compiled standalone binary cannot fork `execPath -e`.
+ */
+export async function probeEndpointLiveness(
+  endpoint: { port: number; hostname?: string },
+  io: Pick<LivenessIo, "fetchFn" | "timeoutMs"> = {},
+): Promise<EndpointLiveness> {
+  if (!Number.isFinite(endpoint.port) || endpoint.port <= 0 || endpoint.port > 65535) return "dead";
+  const fetchFn = io.fetchFn ?? directLocalHttpFetch;
+  const timeoutMs = io.timeoutMs ?? 1500;
+  let sawUnknown = false;
+  for (const hostname of loopbackProbeHosts(endpoint.hostname)) {
+    const result = await classifyHealthz(
+      `http://${hostname}:${endpoint.port}/healthz`,
+      fetchFn,
+      timeoutMs,
+    );
+    if (result === "live") return "live";
+    if (result === "unknown") sawUnknown = true;
+  }
+  return sawUnknown ? "unknown" : "dead";
+}
+
 /** Identity-checked /healthz probe; null when unreachable, non-OK, or not our proxy. */
 export async function proxyIdentityAt(
   port: number,
diff --git a/src/server/relay.ts b/src/server/relay.ts
index 7e84092fb62..1bbb9fd72c7 100644
--- a/src/server/relay.ts
+++ b/src/server/relay.ts
@@ -12,6 +12,7 @@ import {
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
 import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
+import { carryReplayRefusal } from "../lib/upstream-retry";
 import { isUsageDebugEnabled } from "../usage/debug";
 import {
   addRequestLog,
@@ -833,11 +834,14 @@ export function responseWithDeferredRequestLog(
           }, addLog);
         },
       });
-      return new Response(body, {
+      // Logging re-wraps the response, and an in-process verdict does not survive a re-wrap on
+      // its own. A replay refusal that lost it here would read to a later quota recorder or
+      // Retry-After synthesizer as a 429 some upstream produced.
+      return carryReplayRefusal(response, new Response(body, {
         status: response.status,
         statusText: response.statusText,
         headers: response.headers,
-      });
+      }));
     }
     if (isUsageDebugEnabled() && logCtx.usageDebugBodyKind === undefined) {
       logCtx.usageDebugBodyKind = response.body ? "other" : "none";
@@ -989,6 +993,14 @@ export type SseInspectorHandlers = {
    * with an empty `output`.
    */
   onParsedPayload?: (payload: unknown) => void;
+  /**
+   * A complete data payload that did not parse as a JSON event, `[DONE]` included.
+   *
+   * An inspector that only hears about parsed events cannot tell "nothing has been emitted"
+   * from "something was emitted that I could not read", and a replay decision needs that
+   * difference: an unreadable payload is a payload the caller may already have seen.
+   */
+  onOpaquePayload?: () => void;
   onFirstOutput?: () => void;
   /**
    * Provider-scoped compatibility: persist the completed snapshot under the
@@ -1177,6 +1189,11 @@ export function createSseInspector(handlers: SseInspectorHandlers): SseInspector
     if (handlers.onParsedPayload && parsed !== undefined) {
       try { handlers.onParsedPayload(parsed); } catch { /* inspection must never throw into the pump */ }
     }
+    // The other half of the same observation. A payload that did not parse still reached the
+    // caller, so a consumer deciding whether anything has been emitted has to hear about it.
+    if (handlers.onOpaquePayload && parsed === undefined) {
+      try { handlers.onOpaquePayload(); } catch { /* inspection must never throw into the pump */ }
+    }
     reportFirstOutput.parsed(parsed);
     const status = terminalStatusFromParsed(parsed);
     const policyTerminal = status === "failed"
diff --git a/src/server/request-log-failure-attribution.ts b/src/server/request-log-failure-attribution.ts
new file mode 100644
index 00000000000..9a22e0ba8bb
--- /dev/null
+++ b/src/server/request-log-failure-attribution.ts
@@ -0,0 +1,99 @@
+/**
+ * Where a request's failure attribution is derived and stamped.
+ *
+ * A sibling of `request-log.ts` rather than a section inside it. That file carries the whole
+ * request-logging surface and sits against the 2,000-line repository ceiling, which only ever
+ * moves down; this is the extraction that rule asks for, not a cap that was negotiated.
+ *
+ * It holds the two places a stage and cause are decided and written. Both read the recorder's
+ * own closed facts and neither reads `errorCode` or `upstreamError`, which are assembled partly
+ * from upstream text.
+ */
+import { deriveRequestFailureAttribution } from "../lib/request-failure-attribution";
+import { causeForRecoveryKind } from "../lib/request-failure-model";
+import type { AttemptRecoveryKind, PersistedUsageAttempt, RequestFailureCause, RequestFailureStage } from "../usage/log";
+import type { ResponsesTerminalStatus } from "../bridge";
+
+/** The subset of the log context this derivation may see. Narrow on purpose. */
+export interface FinalRequestAttributionFacts {
+  readonly status: number;
+  readonly terminalStatus?: ResponsesTerminalStatus | undefined;
+  readonly closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow" | undefined;
+  readonly transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse" | undefined;
+  readonly terminalSource?: "upstream" | "synthetic" | undefined;
+  /** The REQUEST's first-output observation, not the final attempt's. See below. */
+  readonly outputObserved: boolean;
+  readonly locallyAnswered: boolean;
+  readonly attempt?: PersistedUsageAttempt | undefined;
+}
+
+export interface StampedAttribution {
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
+}
+
+/**
+ * Derive the attribution for a finished logical request and stamp the attempt that ended it.
+ *
+ * Called from the one seam every request passes exactly once, and BEFORE the attempt snapshot,
+ * so the row that reaches disk and the live attempt object carry the same pair. Deriving it at
+ * each transport's own exit would give the same request a different attribution per transport,
+ * which is the disagreement the shared terminal classifier already removed once.
+ *
+ * `outputObserved` is the request's observation rather than the final attempt's. A request that
+ * relayed output on its first attempt and then failed over has committed that output to the
+ * caller whatever the last attempt saw, so the logical row and the attempt that ended it carry
+ * the same answer. Reading the attempt-local value would produce a MORE permissive resend verdict
+ * for exactly that case, and a permission decision has to fail in the safe direction.
+ */
+export function attributeFinalRequest(facts: FinalRequestAttributionFacts): StampedAttribution {
+  const attribution = deriveRequestFailureAttribution({
+    status: facts.status,
+    ...(facts.terminalStatus ? { terminalStatus: facts.terminalStatus } : {}),
+    ...(facts.closeReason ? { closeReason: facts.closeReason } : {}),
+    ...(facts.transportPhase ? { transportPhase: facts.transportPhase } : {}),
+    ...(facts.terminalSource ? { terminalSource: facts.terminalSource } : {}),
+    ...(facts.attempt?.streamAborted === true ? { streamAborted: true } : {}),
+    outputObserved: facts.outputObserved,
+    // The one fact that can raise a stage above `semantic-output`, and the reason it is counted
+    // at the transport rather than at the adapter: an emitted tool call the client never
+    // received has committed nothing, and a resend for it is still safe (#3983).
+    sideEffectObserved: (facts.attempt?.deliverySummary?.sideEffectEvents ?? 0) > 0,
+    locallyAnswered: facts.locallyAnswered,
+    recoveryKinds: facts.attempt?.recoveryKinds ?? [],
+  });
+  // The final row and the attempt that ended it describe the same exchange, so they carry the
+  // same pair rather than each deriving one from a different slice of the facts.
+  if (facts.attempt) {
+    if (attribution?.stage) facts.attempt.failureStage = attribution.stage;
+    else delete facts.attempt.failureStage;
+    if (attribution?.cause) facts.attempt.failureCause = attribution.cause;
+    else delete facts.attempt.failureCause;
+  }
+  return {
+    ...(attribution?.stage ? { failureStage: attribution.stage } : {}),
+    ...(attribution?.cause ? { failureCause: attribution.cause } : {}),
+  };
+}
+
+/**
+ * Attribute an attempt being sealed because a named recovery rejected it.
+ *
+ * The recovery kind is direct evidence here rather than an inference from history: this attempt
+ * is ending precisely because that recovery was needed. Without it the sealed attempt would reach
+ * the ledger with no attribution at all, because the finalization seam only ever sees the last
+ * attempt of a request.
+ */
+export function attributeSealedAttempt(
+  attempt: PersistedUsageAttempt,
+  recovery: AttemptRecoveryKind | undefined,
+): void {
+  const attribution = deriveRequestFailureAttribution({
+    status: attempt.status,
+    outputObserved: attempt.firstOutputMs !== undefined,
+    sideEffectObserved: (attempt.deliverySummary?.sideEffectEvents ?? 0) > 0,
+    ...(recovery ? { causeHint: causeForRecoveryKind(recovery) } : {}),
+  });
+  if (attribution?.stage) attempt.failureStage = attribution.stage;
+  if (attribution?.cause) attempt.failureCause = attribution.cause;
+}
diff --git a/src/server/request-log.ts b/src/server/request-log.ts
index f3d73ba8984..ac1ad98270d 100644
--- a/src/server/request-log.ts
+++ b/src/server/request-log.ts
@@ -40,6 +40,7 @@ import {
   isLogicalRequestId,
   isValidReasoningWireValue,
   normalizeClaudeCompatibilityUsageLog,
+  normalizeRequestFailureAttribution,
   normalizeRequestSpend,
   readRecentUsageEntries,
   usageForFinalLog,
@@ -52,9 +53,13 @@ import {
   type PersistedUsageAttempt,
   type PersistedUsageEntry,
   type PersistedClaudeCompatibilityLog,
+  type RequestFailureCause,
+  type RequestFailureStage,
   type UsageStatus,
 } from "../usage/log";
 import type { RequestExecutionBudget } from "../lib/request-execution-budget";
+import { attributeFinalRequest, attributeSealedAttempt } from "./request-log-failure-attribution";
+import { debugAttemptDeliverySummary } from "../lib/debug";
 import {
   appendUsageDebug,
   isUsageDebugEnabled,
@@ -70,6 +75,21 @@ import { KIRO_MODEL_CONTEXT_WINDOWS, normalizeKiroModelId } from "../providers/k
 import { DEVIN_MODEL_CONTEXT_WINDOWS } from "../adapters/devin/live-models";
 import { modelRecordValue } from "../reasoning-effort";
 import type { RequestMetricsRecorder } from "./request-metrics";
+import type {
+  CacheDiagnosticDraft,
+  CacheDiagnosticFinalFacts,
+  PromptCacheKeySource,
+} from "../usage/cache-diagnostic";
+
+const CACHE_DIAGNOSTIC_HOOK = Symbol.for("opencodex.cache-diagnostic.v1");
+interface CacheDiagnosticHooks {
+  observeInbound(body: unknown, headers: Headers, source: PromptCacheKeySource): CacheDiagnosticDraft;
+  rebind(body: unknown, draft: CacheDiagnosticDraft | undefined): void;
+  finalize(facts: CacheDiagnosticFinalFacts): void;
+}
+function cacheDiagnosticHooks(): CacheDiagnosticHooks | undefined {
+  return (globalThis as Record<symbol, CacheDiagnosticHooks | undefined>)[CACHE_DIAGNOSTIC_HOOK];
+}
 
 export interface RequestLogContext {
   model: string;
@@ -83,6 +103,8 @@ export interface RequestLogContext {
    * budget minted at ingress; a retry leg, a repair refetch and a combo child share it.
    */
   logicalRequestId?: string;
+  /** Process-local privacy-bounded cache diagnostic; never persisted with request logs. */
+  cacheDiagnosticDraft?: CacheDiagnosticDraft;
   /**
    * Internal live reference to this request's execution budget; omitted from RequestLogEntry and
    * JSONL. Read at final-log time so the row reports the budget's FINAL state rather than a
@@ -209,6 +231,24 @@ export interface RequestLogContext {
   claudeCompatibility?: PersistedClaudeCompatibilityLog;
 }
 
+export function observeCacheDiagnosticInbound(
+  logCtx: RequestLogContext,
+  body: unknown,
+  headers: Headers,
+  source: PromptCacheKeySource,
+): void {
+  const draft = cacheDiagnosticHooks()?.observeInbound(body, headers, source);
+  if (draft) logCtx.cacheDiagnosticDraft = draft;
+}
+
+/** Alias a rebuilt form of the request body to the request's diagnostic draft. */
+export function rebindCacheDiagnosticBody(
+  body: unknown,
+  draft: CacheDiagnosticDraft | undefined,
+): void {
+  cacheDiagnosticHooks()?.rebind(body, draft);
+}
+
 export interface RequestLogEntry {
   requestId: string;
   /** The logical request this row belongs to (#4546); absent on rows written without a budget. */
@@ -295,6 +335,13 @@ export interface RequestLogEntry {
   routeDecision?: RouteDecisionTraceV1;
   /** Closed Claude protocol codes; no request or header values. */
   claudeCompatibility?: PersistedClaudeCompatibilityLog;
+  /**
+   * How far this request got and why it failed, in the shared stage and cause vocabulary
+   * (#2366). Derived once at the single finalization seam and carried on the row so the
+   * dashboard, the durable ledger and the exporter read one answer instead of three.
+   */
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
 }
 
 const requestLog: RequestLogEntry[] = [];
@@ -420,6 +467,7 @@ export function requestLogEntryFromPersistedUsage(entry: PersistedUsageEntry): R
     ...(entry.conversationStateScrub === "account-change"
       ? { conversationStateScrub: "account-change" }
       : {}),
+    ...normalizeRequestFailureAttribution(entry),
   };
 }
 
@@ -480,6 +528,24 @@ export function hydrateRequestLogsFromDisk(
   }
 }
 
+/**
+ * Rebuild the Logs ring after retention deleted rows from the ledger.
+ *
+ * Without this a compaction is invisible where an operator actually looks: the ring holds up to
+ * 2,000 entries independently of the file, so rows deleted from disk keep serving through
+ * /api/logs until eviction or a restart -- the dashboard showing history the ledger no longer
+ * has. Observers are deliberately not replayed; they exist to watch NEW rows arrive, and
+ * replaying a rehydration through them would announce two thousand arrivals that did not happen.
+ */
+export function rehydrateRequestLogsAfterLedgerReplacement(
+  reader: () => PersistedUsageEntry[] = () => readRecentUsageEntries(MAX_LOG_SIZE),
+): number {
+  requestLog.length = 0;
+  requestLogBytes = 0;
+  requestLogsHydratedFromDisk = false;
+  return hydrateRequestLogsFromDisk(reader);
+}
+
 export function addRequestLog(entry: RequestLogEntry) {
   // Sanitize ONCE, at the ingress, and use that one value for both destinations.
   //
@@ -566,6 +632,10 @@ export function addRequestLog(entry: RequestLogEntry) {
       ...(isKnownTransportPhase(entry.transportPhase) ? { transportPhase: entry.transportPhase } : {}),
       ...(isKnownTerminalSource(entry.terminalSource) ? { terminalSource: entry.terminalSource } : {}),
       ...failureDiagnostics,
+      // Rebuilt explicitly, like every other field here: this function does not spread the
+      // entry, so a pair omitted at this line would reach /api/logs and never reach
+      // usage.jsonl, which is the surface the derived failure projection reads.
+      ...normalizeRequestFailureAttribution(entry),
       ...(entry.routeDecision ? { routeDecision: entry.routeDecision } : {}),
       ...(entry.claudeCompatibility ? { claudeCompatibility: entry.claudeCompatibility } : {}),
       ...(entry.conversationStateScrub === "account-change"
@@ -1334,6 +1404,18 @@ export function addFinalRequestLog(
     if (errorCode) logCtx.activeAttempt.errorCode = errorCode;
     else delete logCtx.activeAttempt.errorCode;
   }
+  // Derived and stamped in a sibling module, before the attempt snapshot below. Every input is
+  // a closed value; the open error strings are deliberately not among them.
+  const attribution = attributeFinalRequest({
+    status: effectiveStatus,
+    ...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
+    ...(closeReason ? { closeReason } : {}),
+    ...(logCtx.transportPhase ? { transportPhase: logCtx.transportPhase } : {}),
+    ...(logCtx.terminalSource ? { terminalSource: logCtx.terminalSource } : {}),
+    outputObserved: logCtx.firstOutputMs !== undefined,
+    locallyAnswered: logCtx.localTerminalReason !== undefined,
+    ...(logCtx.activeAttempt ? { attempt: logCtx.activeAttempt } : {}),
+  });
   // The one seam every request passes exactly once, whatever transport served it and however
   // it ended. The terminal usage belongs to the last send that left; the ledger resolves every
   // earlier send of this request as unresolved spend rather than handing its tokens back.
@@ -1351,6 +1433,10 @@ export function addFinalRequestLog(
     ...(attempt.recoveryWithheld?.length ? { recoveryWithheld: [...attempt.recoveryWithheld] } : {}),
     ...(attempt.usage ? { usage: { ...attempt.usage } } : {}),
     ...(attempt.tierOutcome ? { tierOutcome: { ...attempt.tierOutcome } } : {}),
+    // Detached, like every mutable field beside it: the live summary keeps counting if the
+    // stream is still draining, and a shared reference would let a finalized row change after
+    // it was written.
+    ...(attempt.deliverySummary ? { deliverySummary: { ...attempt.deliverySummary } } : {}),
   }));
   const isCombo = logCtx.comboId !== undefined && (attempts?.length ?? 0) > 0;
   const aggregate = isCombo ? aggregateAttemptUsage(attempts ?? []) : null;
@@ -1368,11 +1454,30 @@ export function addFinalRequestLog(
     ...(closeReason ? { closeReason } : {}),
     ...(attempts !== undefined ? { attempts } : {}),
     ...(spend ? { spendSends: spend.sends } : {}),
+    ...(attribution.failureCause ? { failureCause: attribution.failureCause } : {}),
   });
   const cacheProvenance = classifyCacheTelemetryProvenance(loggedUsage, {
     wireParsed: logCtx.usageWireParsed === true,
   });
   const logicalRequestId = logCtx.logicalRequestId ?? logCtx.executionBudget?.logicalRequestId;
+  const normalizedCacheValue = loggedUsage?.cacheReadInputTokens ?? loggedUsage?.cachedInputTokens;
+  cacheDiagnosticHooks()?.finalize({
+    requestId,
+    ...(isLogicalRequestId(logicalRequestId) ? { logicalRequestId } : {}),
+    protocol: logCtx.inboundProtocol ?? "responses",
+    provider: logCtx.provider,
+    model: logCtx.model,
+    ...(isCodexUsageAccountLogLabel(logCtx.accountLogLabel) ? { accountLogLabel: logCtx.accountLogLabel } : {}),
+    ...(logCtx.affinity ? { affinityMove: logCtx.affinity } : {}),
+    ...(logCtx.affinityReason ? { affinityReason: logCtx.affinityReason } : {}),
+    // loggedUsage carries the upstream cache counter by reference all the way from the
+    // adapter extraction for the native Responses route, so an undefined read here is a
+    // genuinely absent counter rather than a defaulted one.
+    ...(normalizedCacheValue !== undefined ? { rawCacheCounterValue: normalizedCacheValue } : {}),
+    ...(normalizedCacheValue !== undefined ? { normalizedCacheValue } : {}),
+    cacheProvenance,
+    ...(logCtx.cacheDiagnosticDraft ? { draft: logCtx.cacheDiagnosticDraft } : {}),
+  });
   // Sanitize at the logging layer, not only at the one call site that populates this today.
   // The value originates in an upstream-supplied model id, so an unsanitized newline would
   // let a single field forge a record boundary in any line-oriented log viewer. Doing it here
@@ -1440,7 +1545,10 @@ export function addFinalRequestLog(
     ...(logCtx.terminalSource ? { terminalSource: logCtx.terminalSource } : {}),
     ...(logCtx.routeDecision ? { routeDecision: logCtx.routeDecision } : {}),
     ...(claudeCompatibility ? { claudeCompatibility } : {}),
+    ...attribution,
   });
+  // Formatted from the finalized snapshot, so the ring shows exactly what the ledger holds.
+  for (const attempt of attempts ?? []) debugAttemptDeliverySummary(requestId, attempt);
   if (isUsageDebugEnabled()) {
     appendUsageDebug({
       ts: Date.now(),
@@ -1687,8 +1795,14 @@ export function noteProviderAttemptSend(
     finishRequestAttempt(attempt, attempt.status >= 100 ? attempt.status
       : recovery === "key-401" ? 401 : recovery?.includes("429") ? 429 : 502,
     Date.now() - (logCtx.activeAttemptStartedAt ?? Date.now()), attempt.usage);
+    // This attempt is being sealed because a NAMED recovery rejected it, so the recovery kind
+    // is direct evidence here rather than an inference from history. Without this the sealed
+    // attempt would reach the ledger with no attribution at all: the finalization seam below
+    // only ever sees the last attempt of the request.
+    attributeSealedAttempt(attempt, recovery);
     const completed = { ...attempt, recoveryKinds: [...attempt.recoveryKinds],
       ...(attempt.usage ? { usage: { ...attempt.usage } } : {}),
+      ...(attempt.deliverySummary ? { deliverySummary: { ...attempt.deliverySummary } } : {}),
       ...(attempt.tierOutcome ? { tierOutcome: { ...attempt.tierOutcome } } : {}) };
     const attempts = logCtx.attempts ??= [attempt];
     const index = attempts.indexOf(attempt);
diff --git a/src/server/request-metrics.ts b/src/server/request-metrics.ts
index d6126d5d9da..cc3b89db977 100644
--- a/src/server/request-metrics.ts
+++ b/src/server/request-metrics.ts
@@ -1,13 +1,40 @@
 import type { ResponsesTerminalStatus } from "../bridge";
 import type { AttemptRecoveryKind } from "../usage/log";
+import {
+  REQUEST_FAILURE_CAUSES,
+  type RequestFailureCause,
+  causeForRecoveryKind,
+} from "../lib/request-failure-model";
+import {
+  REQUEST_OUTCOME_CLASSES,
+  classifyRequestOutcome,
+  type RequestOutcomeClass,
+} from "../usage/request-outcome";
 
 export const REQUEST_METRICS_PROTOCOLS = Object.freeze(["responses", "chat", "messages", "unknown"] as const);
-export const REQUEST_METRICS_RESULTS = Object.freeze(["completed", "failed", "incomplete", "aborted"] as const);
+/**
+ * The exporter's result label set IS the shared outcome vocabulary, not a copy of it. Restating
+ * these four strings here is what let the exporter and the dashboard drift into disagreeing about
+ * the same request.
+ */
+export const REQUEST_METRICS_RESULTS = REQUEST_OUTCOME_CLASSES;
+/**
+ * Closed recovery classes exported as Prometheus label values.
+ *
+ * Bounded by construction: the label can only ever take one of these strings, so no user, model,
+ * account or request identifier can reach a series name. `quota`, `policy` and `ciphertext` are
+ * separate members because an operator seeing a spike needs to know which one it is -- waiting
+ * out a rate limit, changing accounts, changing the prompt and dropping stale ciphertext are
+ * four different responses, and collapsing them is what made the existing counter unactionable.
+ */
 export const REQUEST_METRICS_RECOVERY_CLASSES = Object.freeze([
   "transient",
   "connection",
   "credential",
   "rate_limit",
+  "quota",
+  "policy",
+  "ciphertext",
   "payload",
   "empty_completion",
   "effort_downgrade",
@@ -17,8 +44,20 @@ export const REQUEST_METRICS_RECOVERY_CLASSES = Object.freeze([
 export const REQUEST_DURATION_BUCKETS_SECONDS = Object.freeze([0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60] as const);
 export const REQUEST_TTFT_BUCKETS_SECONDS = Object.freeze([0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30] as const);
 
+/**
+ * The failure-cause label set IS the shared dictionary, for the same reason the result label set
+ * is the shared outcome vocabulary: a restated copy is what let two surfaces drift into
+ * disagreeing about the same request.
+ *
+ * It labels a COUNTER and never a histogram. Fifteen causes across four protocols is sixty
+ * series, fixed for the lifetime of the roster, and every value comes from a frozen list, so no
+ * user, model, account or request identifier can reach a series name. A histogram labelled by
+ * cause would multiply that by its bucket count for no question anyone asks.
+ */
+export const REQUEST_METRICS_FAILURE_CAUSES = REQUEST_FAILURE_CAUSES;
+
 export type RequestMetricsProtocol = typeof REQUEST_METRICS_PROTOCOLS[number];
-export type RequestMetricsResult = typeof REQUEST_METRICS_RESULTS[number];
+export type RequestMetricsResult = RequestOutcomeClass;
 export type RequestMetricsRecoveryClass = typeof REQUEST_METRICS_RECOVERY_CLASSES[number];
 
 export interface RequestMetricFinalFact {
@@ -33,6 +72,11 @@ export interface RequestMetricFinalFact {
     recoveryKinds: readonly AttemptRecoveryKind[];
   }>;
   spendSends?: number;
+  /**
+   * Why this request failed, as the recorder derived it. Absent when it did not fail, which is
+   * why the counter below cannot be reconstructed by subtracting completions from totals.
+   */
+  failureCause?: RequestFailureCause;
 }
 
 export interface RequestMetricsRecorder {
@@ -56,6 +100,7 @@ interface HistogramCell {
 const protocolCell = (value: RequestMetricsProtocol): number => REQUEST_METRICS_PROTOCOLS.indexOf(value);
 const resultCell = (value: RequestMetricsResult): number => REQUEST_METRICS_RESULTS.indexOf(value);
 const recoveryCell = (value: RequestMetricsRecoveryClass): number => REQUEST_METRICS_RECOVERY_CLASSES.indexOf(value);
+const failureCauseCell = (value: RequestFailureCause): number => REQUEST_METRICS_FAILURE_CAUSES.indexOf(value);
 
 function matrix(rows: number, columns: number): number[][] {
   return Array.from({ length: rows }, () => Array.from({ length: columns }, () => 0));
@@ -71,35 +116,34 @@ function histograms(bounds: readonly number[]): HistogramCell[][] {
   ));
 }
 
-function classifyResult(fact: RequestMetricFinalFact): RequestMetricsResult {
-  if (fact.closeReason === "client_cancel" || fact.status === 499) return "aborted";
-  if (fact.terminalStatus === "failed") return "failed";
-  if (fact.terminalStatus === "incomplete"
-    || fact.closeReason === "body_stall"
-    || fact.closeReason === "body_overflow") return "incomplete";
-  if (fact.terminalStatus === "completed") return "completed";
-  if (fact.terminalStatus === undefined
-    && (fact.status === 101 || (fact.status >= 200 && fact.status < 400))) return "completed";
-  return "failed";
-}
+/**
+ * Metrics class for each shared failure cause.
+ *
+ * Keyed on the cause rather than on the recovery kind so this projection and the durable log
+ * speak one vocabulary. Total by construction: the previous switch ended in `default: "other"`,
+ * which meant a recovery kind added later compiled cleanly and then disappeared into an
+ * unactionable bucket. A missing member is now a typecheck failure.
+ */
+const CAUSE_METRICS_CLASS = {
+  "transport-unsent": "connection",
+  "transport-ambiguous": "connection",
+  "upstream-declined": "transient",
+  "rate-limit": "rate_limit",
+  "quota-exhausted": "quota",
+  "credential-rejected": "credential",
+  "policy-refusal": "policy",
+  "parameter-rejected": "effort_downgrade",
+  "ciphertext-refusal": "ciphertext",
+  "payload-too-large": "payload",
+  "payload-rejected": "payload",
+  "upstream-fault": "transient",
+  "empty-output": "empty_completion",
+  "client-cancelled": "other",
+  "local-refusal": "other",
+} as const satisfies Record<RequestFailureCause, RequestMetricsRecoveryClass>;
 
 function recoveryClass(kind: AttemptRecoveryKind): RequestMetricsRecoveryClass {
-  switch (kind) {
-    case "transient-5xx": return "transient";
-    case "connection-reset": return "connection";
-    case "oauth-401":
-    case "key-401": return "credential";
-    case "key-429":
-    case "rate-limit-429":
-    case "anthropic-oauth-429":
-    case "oauth-account-429": return "rate_limit";
-    case "image-413":
-    case "console-go-upload-retry":
-    case "opaque-blob-rejection": return "payload";
-    case "empty-completion": return "empty_completion";
-    case "reasoning-effort-downgrade": return "effort_downgrade";
-    default: return "other";
-  }
+  return CAUSE_METRICS_CLASS[causeForRecoveryKind(kind)];
 }
 
 function observeHistogram(cell: HistogramCell, bounds: readonly number[], value: number): void {
@@ -145,6 +189,7 @@ export function createRequestMetricsOwner(
   let logicalRequests = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length);
   let physicalSends = Array.from({ length: REQUEST_METRICS_PROTOCOLS.length }, () => 0);
   let recoveries = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RECOVERY_CLASSES.length);
+  let failureCauses = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_FAILURE_CAUSES.length);
   let durations = histograms(REQUEST_DURATION_BUCKETS_SECONDS);
   let ttft = histograms(REQUEST_TTFT_BUCKETS_SECONDS);
   let missingTtft = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length);
@@ -152,7 +197,7 @@ export function createRequestMetricsOwner(
   return {
     recordFinalRequest(fact): void {
       const protocol: RequestMetricsProtocol = fact.protocol ?? "unknown";
-      const result = classifyResult(fact);
+      const result = classifyRequestOutcome(fact);
       const protocolIndex = protocolCell(protocol);
       const resultIndex = resultCell(result);
       logicalRequests[protocolIndex]![resultIndex]! += 1;
@@ -165,6 +210,13 @@ export function createRequestMetricsOwner(
         ), 0);
       physicalSends[protocolIndex]! += sends;
 
+      // Counted from the cause the recorder derived, not re-derived here. Two derivations of one
+      // answer is the disagreement this batch exists to remove, and the recorder is the only
+      // place that sees the transport facts a cause needs.
+      if (fact.failureCause !== undefined) {
+        failureCauses[protocolIndex]![failureCauseCell(fact.failureCause)]! += 1;
+      }
+
       for (const attempt of attempts ?? []) {
         for (const kind of new Set(attempt.recoveryKinds)) {
           recoveries[protocolIndex]![recoveryCell(recoveryClass(kind))]! += 1;
@@ -205,6 +257,15 @@ export function createRequestMetricsOwner(
           lines.push(`opencodex_recoveries_total{protocol="${protocol}",recovery="${recovery}"} ${recoveries[protocolCell(protocol)]![recoveryCell(recovery)]}`);
         }
       }
+      lines.push(
+        "# HELP opencodex_request_failures_total Finalized logical requests that did not deliver an answer, by derived cause.",
+        "# TYPE opencodex_request_failures_total counter",
+      );
+      for (const protocol of REQUEST_METRICS_PROTOCOLS) {
+        for (const cause of REQUEST_METRICS_FAILURE_CAUSES) {
+          lines.push(`opencodex_request_failures_total{protocol="${protocol}",cause="${cause}"} ${failureCauses[protocolCell(protocol)]![failureCauseCell(cause)]}`);
+        }
+      }
       appendHistogram(lines, "opencodex_request_duration_seconds", "Finalized logical request duration in seconds.", durations, REQUEST_DURATION_BUCKETS_SECONDS);
       appendHistogram(lines, "opencodex_ttft_seconds", "Observed time to first output in seconds.", ttft, REQUEST_TTFT_BUCKETS_SECONDS);
       lines.push(
@@ -228,6 +289,7 @@ export function createRequestMetricsOwner(
       logicalRequests = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length);
       physicalSends = Array.from({ length: REQUEST_METRICS_PROTOCOLS.length }, () => 0);
       recoveries = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RECOVERY_CLASSES.length);
+      failureCauses = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_FAILURE_CAUSES.length);
       durations = histograms(REQUEST_DURATION_BUCKETS_SECONDS);
       ttft = histograms(REQUEST_TTFT_BUCKETS_SECONDS);
       missingTtft = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length);
diff --git a/src/server/responses-request-tool-scope.ts b/src/server/responses-request-tool-scope.ts
new file mode 100644
index 00000000000..aa140aaa6ad
--- /dev/null
+++ b/src/server/responses-request-tool-scope.ts
@@ -0,0 +1,214 @@
+/**
+ * The tool selection a Responses request actually authorized, read from the final outbound body.
+ *
+ * The undeclared-tool guard answers whether a NAME was declared. This answers a different
+ * question: whether this request still permits a client tool call at all, and which names it
+ * permits. `tool_choice: "none"`, a forced selector and an `allowed_tools` allow-list each narrow
+ * the catalog without removing a declaration, so a name can be declared and forbidden at the same
+ * time — and a repair that rebuilds a terminal from collected items would otherwise hand the
+ * client a call the caller ruled out.
+ *
+ * The scope is read from the OUTBOUND body, after every removal, rename and translation, because
+ * that is the request the destination answered. A catalog that ends up empty there authorizes no
+ * client call whatever the selector still says.
+ */
+import type { MuseToolNameAliases } from "../responses/muse-tool-name-alias";
+import { museWireNameForOriginal } from "../responses/muse-tool-name-alias";
+import type {
+  RoutedNamespaceToolAliases,
+  RoutedNamespaceToolIdentity,
+} from "../responses/namespace-tool-compat";
+import {
+  CLIENT_EXECUTED_CALL_TYPES,
+  collectDeclaredWireToolNames,
+  hasExplicitWireToolCatalog,
+} from "./responses-undeclared-tool-guard";
+import { isPlainObject } from "./responses-snapshot-codec";
+
+type ToolKind = "function" | "custom";
+const BUILTIN_FUNCTIONS_NAMESPACE = "functions";
+
+type ToolIdentity = Readonly<{
+  kind: ToolKind;
+  name: string;
+  namespace?: string;
+}>;
+
+export type RequestToolScopeCorrespondence = Readonly<{
+  clientToolAuthorizationBody?: unknown;
+  routedNamespaceToolAliases?: RoutedNamespaceToolAliases;
+  routedMuseToolNameAliases?: MuseToolNameAliases;
+  convertedRoutedCustomToolNames?: ReadonlySet<string>;
+}>;
+
+function identityKey(identity: ToolIdentity): string {
+  return JSON.stringify([identity.kind, identity.namespace ?? null, identity.name]);
+}
+
+function clientNamespace(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 && value !== BUILTIN_FUNCTIONS_NAMESPACE
+    ? value
+    : undefined;
+}
+
+function selectorIdentity(selector: unknown): ToolIdentity | undefined {
+  if (!isPlainObject(selector)) return undefined;
+  if (selector.type !== "function" && selector.type !== "custom") return undefined;
+  if (typeof selector.name !== "string" || selector.name.length === 0) return undefined;
+  if ("namespace" in selector && typeof selector.namespace !== "string") return undefined;
+  const namespace = clientNamespace(selector.namespace);
+  return { kind: selector.type, name: selector.name, ...(namespace ? { namespace } : {}) };
+}
+
+function callIdentity(item: Record<string, unknown>): ToolIdentity | undefined {
+  const kind = item.type === "function_call"
+    ? "function"
+    : item.type === "custom_tool_call"
+      ? "custom"
+      : undefined;
+  if (!kind || typeof item.name !== "string" || item.name.length === 0) return undefined;
+  const namespace = clientNamespace(item.namespace);
+  return { kind, name: item.name, ...(namespace ? { namespace } : {}) };
+}
+
+function sameRestoredIdentity(left: ToolIdentity, right: RoutedNamespaceToolIdentity): boolean {
+  return left.namespace === right.namespace
+    && left.name === right.name
+    && left.kind === right.kind;
+}
+
+/**
+ * Exact identities this restored call could have used on the final outbound wire.
+ *
+ * Namespace spellings come only from namespace-tool-compat's request-scoped, ambiguity-checked
+ * aliases. Muse aliases then compose over those wire names. A kind change is admitted only when
+ * the request recorded that exact custom identity as converted to a function.
+ */
+function outboundCallIdentities(
+  item: Record<string, unknown>,
+  correspondence: RequestToolScopeCorrespondence,
+): ReadonlySet<string> {
+  const restored = callIdentity(item);
+  if (!restored) return new Set();
+  const keys = new Set<string>([identityKey(restored)]);
+  const museAliases = correspondence.routedMuseToolNameAliases ?? new Map();
+  const convertedCustom = correspondence.convertedRoutedCustomToolNames ?? new Set();
+  const originalSelection = isPlainObject(correspondence.clientToolAuthorizationBody)
+    ? toolSelection(correspondence.clientToolAuthorizationBody)
+    : UNRESTRICTED;
+  const originalSelectionAllowsRestored = originalSelection.kind === "allow"
+    && originalSelection.identities.has(identityKey(restored));
+
+  const addWireIdentity = (
+    preMuseName: string,
+    clientKind: ToolKind,
+    conversionIdentityVerified: boolean,
+  ): void => {
+    const name = museWireNameForOriginal(preMuseName, museAliases);
+    if (name === undefined) return;
+    const kind = clientKind === "custom"
+      && convertedCustom.has(preMuseName)
+      && conversionIdentityVerified
+      ? "function"
+      : clientKind;
+    keys.add(identityKey({ kind, name }));
+  };
+
+  if (restored.namespace === undefined) {
+    addWireIdentity(restored.name, restored.kind, originalSelectionAllowsRestored);
+  }
+  for (const [wireName, identity] of correspondence.routedNamespaceToolAliases ?? new Map()) {
+    // namespace-tool-compat emits only aliases authorized under the outbound selector's kind,
+    // then restores `custom` provenance from the request's conversion set. That exact alias edge is
+    // already the proof that this custom-to-function transition belongs to this identity.
+    if (sameRestoredIdentity(restored, identity)) addWireIdentity(wireName, identity.kind, true);
+  }
+  return keys;
+}
+
+type ToolSelection =
+  | { readonly kind: "unrestricted" }
+  | { readonly kind: "deny_all" }
+  | { readonly kind: "allow"; readonly identities: ReadonlySet<string> };
+
+const UNRESTRICTED: ToolSelection = { kind: "unrestricted" };
+
+/**
+ * Read the selector only where it states a client-call boundary.
+ *
+ * `auto`, `required` and an absent selector restrict nothing. A hosted selector
+ * (`{ type: "web_search" }`) forces a tool the PROVIDER runs and does not describe the client
+ * calls this turn may contain, so it is left alone rather than read as a deny-all: a false
+ * refusal would drop a call the caller could have executed.
+ */
+function toolSelection(body: Record<string, unknown>): ToolSelection {
+  const choice = body.tool_choice;
+  if (choice === "none") return { kind: "deny_all" };
+  if (!isPlainObject(choice)) return UNRESTRICTED;
+  if (choice.type === "allowed_tools") {
+    const identities = new Set<string>();
+    if (!Array.isArray(choice.tools)) return { kind: "allow", identities };
+    for (const entry of choice.tools) {
+      const identity = selectorIdentity(entry);
+      if (identity) identities.add(identityKey(identity));
+    }
+    // An allow-list carrying no client tool — emptied by normalization, or hosted entries only —
+    // still bounds this turn: it allows no client call.
+    return { kind: "allow", identities };
+  }
+  if (choice.type === "function" || choice.type === "custom") {
+    const identity = selectorIdentity(choice);
+    return {
+      kind: "allow",
+      identities: new Set(identity ? [identityKey(identity)] : []),
+    };
+  }
+  return UNRESTRICTED;
+}
+
+export type RequestToolScope = {
+  /**
+   * The name a client call is refused under, or undefined when this request permits it.
+   * A nameless call type is not answered here: only the declaration guard knows those.
+   */
+  forbiddenClientToolCallName(item: Record<string, unknown>): string | undefined;
+};
+
+/**
+ * The client-call boundary this request states, or undefined when it states none.
+ *
+ * Returning undefined for an unrestricted request keeps every ordinary turn on the path it
+ * already had: a caller that selected nothing gets no new refusal.
+ */
+export function requestToolScope(
+  body: unknown,
+  correspondence: RequestToolScopeCorrespondence = {},
+): RequestToolScope | undefined {
+  if (!isPlainObject(body)) return undefined;
+  const selection = toolSelection(body);
+  // A readable catalog that declares no client-executable name is authoritative, exactly as it is
+  // for the declaration guard: an explicit empty list denies every client call. An absent catalog
+  // says nothing — a passthrough request may omit `tools` and still receive a call the client
+  // understands.
+  const catalogDeniesClientCalls = hasExplicitWireToolCatalog(body)
+    && collectDeclaredWireToolNames(body).size === 0;
+  if (selection.kind === "unrestricted" && !catalogDeniesClientCalls) return undefined;
+  return {
+    forbiddenClientToolCallName(item: Record<string, unknown>): string | undefined {
+      if (typeof item.type !== "string" || !CLIENT_EXECUTED_CALL_TYPES.has(item.type)) {
+        return undefined;
+      }
+      const restored = callIdentity(item);
+      const reported = restored?.name;
+      if (reported === undefined) return undefined;
+      if (catalogDeniesClientCalls || selection.kind === "deny_all") return reported;
+      if (selection.kind === "allow") {
+        const candidates = outboundCallIdentities(item, correspondence);
+        return [...candidates].some(candidate => selection.identities.has(candidate))
+          ? undefined
+          : reported;
+      }
+      return undefined;
+    },
+  };
+}
diff --git a/src/server/responses-undeclared-tool-guard.ts b/src/server/responses-undeclared-tool-guard.ts
index 7b2a2a22c1c..943f19e7d6d 100644
--- a/src/server/responses-undeclared-tool-guard.ts
+++ b/src/server/responses-undeclared-tool-guard.ts
@@ -13,7 +13,10 @@ import {
 import { replaceSseDataPayload, sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
 
 /** Item types the client executes through a request-declared wire name. */
-const CLIENT_EXECUTED_CALL_TYPES = new Set(["function_call", "custom_tool_call"]);
+export const CLIENT_EXECUTED_CALL_TYPES: ReadonlySet<string> = new Set([
+  "function_call",
+  "custom_tool_call",
+]);
 /** Codex groups ordinary top-level tools here; unlike an MCP namespace, it has no wire prefix. */
 const BUILTIN_FUNCTIONS_NAMESPACE = "functions";
 
diff --git a/src/server/responses/codex-ws-wire.ts b/src/server/responses/codex-ws-wire.ts
index 35764c83522..e8edb1106c7 100644
--- a/src/server/responses/codex-ws-wire.ts
+++ b/src/server/responses/codex-ws-wire.ts
@@ -4,7 +4,8 @@ import {
   UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE,
   UPSTREAM_NO_RESPONSE_CODE,
 } from "../../lib/upstream-retry";
-import { readFileSync } from "node:fs";
+import type { RequestFailureCause, RequestFailureStage } from "../../lib/request-failure-model";
+import { packageVersion } from "../../lib/package-version";
 // If the 101 never arrives (network black hole), give SSE a chance well before
 // the caller's connect timeout (default 200s) would fire.
 export const UPGRADE_DEADLINE_MS = 10_000;
@@ -72,13 +73,7 @@ export function markCodexWsResponse(response: Response, observed: boolean): void
  * importing management-api from the transport layer would invert the
  * layering and pull the management surface into every WS exchange.
  */
-const OCX_VERSION = (() => {
-  try {
-    return JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8")).version as string;
-  } catch {
-    return "0.0.0";
-  }
-})();
+const OCX_VERSION = packageVersion("0.0.0");
 
 /**
  * The durable form of the stage counters, carried out of the exchange on the
@@ -210,6 +205,37 @@ export function classifyCodexWsFailure(stage: CodexWsFailureStage): CodexWsFailu
   return "no-response-event";
 }
 
+/**
+ * The same four outcomes said in the shared stage-and-cause vocabulary (#4191).
+ *
+ * A projection, not a second classifier: {@link classifyCodexWsFailure} stays the one place that
+ * reads the counters, and this only restates its answer in the words the durable log, the metrics
+ * projection and the HTTP path already use. Without it the WebSocket transport is the one surface
+ * whose failures cannot be compared with anything else, which is the reported symptom -- every
+ * such failure reached the user as one of two bare sentences.
+ *
+ * It does not relax the transport's own rule. The no-replay-after-send contract in
+ * `codex-ws-exchange.ts` holds regardless of what this returns, and the stage below is
+ * deliberately not consulted as a fallback-eligibility signal; it reports where the exchange got
+ * to, and `resendPermission` happens to agree that everything past `before-send` is refused.
+ */
+export const CODEX_WS_FAILURE_PROJECTION = {
+  /** The create frame never left, so the origin provably never saw this turn. */
+  "before-send": { stage: "pre-header", cause: "transport-unsent" },
+  /** The frame left and the socket said nothing at all. The turn may be running upstream. */
+  "no-upstream-frame": { stage: "pre-header", cause: "transport-ambiguous" },
+  /** Control frames only: the peer is alive and answered, but no Responses event arrived. */
+  "no-response-event": { stage: "protocol-prelude", cause: "transport-ambiguous" },
+  /** Events already reached the caller, so a resend would duplicate output they have seen. */
+  "after-response-started": { stage: "semantic-output", cause: "transport-ambiguous" },
+} as const satisfies Record<CodexWsFailureCause, { stage: RequestFailureStage; cause: RequestFailureCause }>;
+
+export function projectCodexWsFailure(
+  stage: CodexWsFailureStage,
+): { stage: RequestFailureStage; cause: RequestFailureCause } {
+  return CODEX_WS_FAILURE_PROJECTION[classifyCodexWsFailure(stage)];
+}
+
 /**
  * Render the stage as a suffix appended to an existing failure message.
  *
diff --git a/src/server/responses/combo-stream-preflight.ts b/src/server/responses/combo-stream-preflight.ts
index 22e1ae12e45..801946fb571 100644
--- a/src/server/responses/combo-stream-preflight.ts
+++ b/src/server/responses/combo-stream-preflight.ts
@@ -1,6 +1,7 @@
 import type { ResponsesTerminalStatus } from "../../bridge";
 import { comboFailureDecision } from "../../combos";
 import { httpStatusFromTerminalError } from "../../lib/errors";
+import type { RequestFailureStage } from "../../lib/request-failure-model";
 import type { RequestLogContext } from "../request-log";
 import { createSseInspector } from "../relay";
 import { MAX_CLIENT_SSE_FRAME_BYTES } from "../sse-frame-buffer";
@@ -108,9 +109,48 @@ export function comboStreamPayloadCommitsOutput(payload: unknown): boolean {
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) return true;
   const type = (payload as { type?: unknown }).type;
   if (typeof type !== "string") return true;
+  if (type === "response.created") {
+    // A created event is a control frame only while its snapshot is empty. An origin that
+    // resumes a turn can put completed items in it, and treating that as a prelude would let
+    // a replacement re-emit output the caller already received.
+    const response = (payload as { response?: unknown }).response;
+    if (response && typeof response === "object" && !Array.isArray(response)) {
+      const output = (response as { output?: unknown }).output;
+      if (Array.isArray(output) && output.length > 0) return true;
+    }
+  }
   return !PRE_OUTPUT_CONTROL_EVENTS.has(type) && !TERMINAL_EVENTS.has(type);
 }
 
+/**
+ * How far this SSE body got, in the vocabulary of src/lib/request-failure-model.ts.
+ *
+ * The preflight cannot separate `semantic-output` from `side-effect`: it classifies any event
+ * that is not a lifecycle control frame as committing, without reading item types. Both stages
+ * refuse a resend, so the distinction would change no decision -- it is named here so a later
+ * reader does not mistake the collapse for an omission.
+ *
+ * A terminal that settled carrying no output is `protocol-prelude`, not `terminal`. That is
+ * the failure model's own rule: `terminal` means the answer was delivered, and an empty
+ * completion delivered none.
+ *
+ * Only the two nothing-observed stages actually reach a read error today: the loop below hands
+ * the body back as `accepted` the moment output commits or a terminal arrives, so a stream
+ * that committed anything never reports a stage at all. The committed branches stay because
+ * this has to be total for any other caller, and because a later change to that loop must not
+ * be able to promote a committed stream into a replaceable one by omission.
+ */
+function observedResponsesStage(state: {
+  readonly outputCommitted: boolean;
+  readonly terminalStatus: ResponsesTerminalStatus | undefined;
+  readonly responseCreated: boolean;
+}): RequestFailureStage {
+  if (state.outputCommitted) return "semantic-output";
+  if (state.terminalStatus === "completed") return "terminal";
+  if (state.responseCreated || state.terminalStatus !== undefined) return "protocol-prelude";
+  return "headers-only";
+}
+
 function replayBufferedResponse(
   response: Response,
   reader: ReadableStreamDefaultReader<Uint8Array>,
@@ -186,13 +226,22 @@ function failedTerminalResponse(
 
 export type ComboStreamPreflightResult =
   | { kind: "accepted"; response: Response }
-  | { kind: "failed"; response: Response };
+  | { kind: "failed"; response: Response }
+  /**
+   * The body errored mid-stream and `replayReadErrors` asked for the prefix back rather than
+   * a rethrow. `stage` is how far the inspection actually got; whether that permits a
+   * replacement is the resend gate's decision, not this function's. Callers that only act on
+   * a projected terminal can treat this exactly as `accepted`, which is what it was before
+   * the stage became observable.
+   */
+  | { kind: "read-error"; response: Response; error: unknown; stage: RequestFailureStage };
 
 /**
- * Buffer a combo child's downstream SSE only until the request becomes unsafe to
- * replay or reaches a terminal. This owns exactly one body reader. The aggregate
- * buffer is capped by bytes and retained chunks; hitting either cap commits the
- * current target instead of growing memory or guessing that replay is safe.
+ * Buffer a Responses SSE only until the request becomes unsafe to replay or reaches a
+ * terminal. Combo failover and native post-header reset recovery share this protocol
+ * boundary, because they are asking the same question about the same bytes. This owns exactly
+ * one body reader. The aggregate buffer is capped by bytes and retained chunks; hitting either
+ * cap commits the current target instead of growing memory or guessing that replay is safe.
  */
 export async function preflightComboStreamResponse(
   response: Response,
@@ -211,12 +260,18 @@ export async function preflightComboStreamResponse(
   const buffered: Uint8Array[] = [];
   let bufferedBytes = 0;
   let outputCommitted = false;
+  let responseCreated = false;
   let terminalStatus: ResponsesTerminalStatus | undefined;
   let retryableTerminalPayload: Record<string, unknown> | undefined;
   const inspector = createSseInspector({
     logCtx,
+    // A payload the inspector could not parse still reached this proxy, and it may be output.
+    // Committing on it is what keeps an unreadable frame from reading as an empty prelude.
+    onOpaquePayload: () => { outputCommitted = true; },
     onParsedPayload: payload => {
       if (terminalStatus !== undefined || outputCommitted || retryableTerminalPayload) return;
+      if (payload !== null && typeof payload === "object" && !Array.isArray(payload)
+        && (payload as { type?: unknown }).type === "response.created") responseCreated = true;
       const retryable = retryableTerminal(payload);
       const matchedBareError = retryable && payload !== null && typeof payload === "object"
         && !Array.isArray(payload) && (payload as { type?: unknown }).type === "error";
@@ -239,7 +294,9 @@ export async function preflightComboStreamResponse(
         // The native relay still owns post-header transport failures. Preserve
         // the bounded prefix and the errored reader; cancelling it here would
         // erase the failure before either client relay or inspection sees it.
-        return { kind: "accepted", response: replayBufferedResponse(response, reader, buffered) };
+        const replay = replayBufferedResponse(response, reader, buffered);
+        const stage = observedResponsesStage({ outputCommitted, terminalStatus, responseCreated });
+        return { kind: "read-error", response: replay, error, stage };
       }
       if (next.done) {
         inspector.finish();
@@ -277,3 +334,108 @@ export async function preflightComboStreamResponse(
     inspector.dispose();
   }
 }
+
+/** Produce a replacement body for a mid-stream failure at `stage`, or null to keep the error. */
+export type ProtocolSafeResetRecovery = (
+  error: unknown,
+  stage: RequestFailureStage,
+) => Promise<Response | null>;
+
+/**
+ * Defer protocol inspection until the downstream actually pulls the body.
+ *
+ * Direct passthrough must return response headers before the first SSE event arrives, so the
+ * inspection cannot be awaited at the dispatch site the way combo routing awaits it. Wrapping
+ * the body moves it to the first pull, which is the earliest moment the client is willing to
+ * wait anyway.
+ */
+export function deferProtocolSafeResetRecovery(
+  response: Response,
+  logCtx: RequestLogContext,
+  recover: ProtocolSafeResetRecovery,
+  options?: { allowMissingContentType?: boolean },
+): Response {
+  if (!response.body) return response;
+
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let initialization: Promise<void> | undefined;
+  let closed = false;
+
+  const cancelBody = (body: ReadableStream<Uint8Array> | null, reason?: unknown): void => {
+    try { void body?.cancel(reason).catch(() => {}); } catch { /* already locked or closed */ }
+  };
+  const initialize = async (): Promise<void> => {
+    const preflight = await preflightComboStreamResponse(
+      response,
+      logCtx,
+      () => false,
+      { allowMissingContentType: options?.allowMissingContentType === true, replayReadErrors: true },
+    );
+    let selected = preflight.response;
+    if (preflight.kind === "read-error") {
+      const replacement = await recover(preflight.error, preflight.stage);
+      if (replacement) {
+        cancelBody(selected.body, "using protocol-safe replacement stream");
+        selected = replacement;
+      }
+    }
+    if (closed) {
+      cancelBody(selected.body, "downstream cancelled before protocol preflight completed");
+      return;
+    }
+    reader = selected.body?.getReader();
+  };
+
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        initialization ??= initialize();
+        await initialization;
+        if (closed) return;
+        if (!reader) {
+          closed = true;
+          controller.close();
+          return;
+        }
+        const next = await reader.read();
+        if (closed) return;
+        if (next.done) {
+          closed = true;
+          try { reader.releaseLock(); } catch { /* already released */ }
+          reader = undefined;
+          controller.close();
+          return;
+        }
+        controller.enqueue(next.value);
+      } catch (error) {
+        if (closed) return;
+        closed = true;
+        try { reader?.releaseLock(); } catch { /* errored reader */ }
+        reader = undefined;
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      if (closed) return;
+      closed = true;
+      if (reader) {
+        try { void reader.cancel(reason).catch(() => {}); } catch { /* already closed */ }
+        try { reader.releaseLock(); } catch { /* already released */ }
+        reader = undefined;
+      } else if (initialization === undefined) {
+        // Nothing has read the upstream yet, so this body is still ours to cancel.
+        cancelBody(response.body, reason);
+      }
+      // A cancel while the preflight is mid-flight falls through deliberately. That body is
+      // locked by the preflight's own reader, so cancelling it here would reject and be
+      // swallowed; `initialize` sees `closed` when it settles and releases whichever body it
+      // ended up selecting, which is the one that actually has to be let go.
+    },
+  }, { highWaterMark: 0 });
+
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
diff --git a/src/server/responses/compact.ts b/src/server/responses/compact.ts
index 92e394751bc..89e40123789 100644
--- a/src/server/responses/compact.ts
+++ b/src/server/responses/compact.ts
@@ -1,4 +1,10 @@
 import { capturePoolQuotaWriter } from "../../codex/account-store";
+import {
+  admissionModelDeniedResponse,
+  AdmissionModelDeniedError,
+  assertRouteAllowedByScope,
+  resolveAdmissionModelScope,
+} from "../admission-model-scope";
 import type { Server } from "bun";
 import { bridgeToResponsesSSE, buildResponseJSON, formatErrorResponse, type ResponsesTerminalStatus } from "../../bridge";
 import {
@@ -655,7 +661,12 @@ export async function handleResponsesCompact(
     // routes ordinary turns elsewhere (#2901); the compaction-scoped router
     // may land that on the configured default provider instead of 404.
     route = routeCompactionModel(config, compactModel, evidenceFromBody(raw));
+    // A compaction override picks the model, not the caller, so the key's scope
+    // is applied to what the override resolved to rather than to the selector
+    // the client sent.
+    assertRouteAllowedByScope(resolveAdmissionModelScope(config, admission), compactRequestedModel, route);
   } catch (err) {
+    if (err instanceof AdmissionModelDeniedError) return admissionModelDeniedResponse(err);
     if (err instanceof NoEligiblePolicyCandidateError) {
       // Persist the evaluation trace (per-candidate exclusions + the
       // no-eligible reason) so a failed compact policy request stays
diff --git a/src/server/responses/core-opaque-recovery.ts b/src/server/responses/core-opaque-recovery.ts
index 03df9766863..13a65b76ea0 100644
--- a/src/server/responses/core-opaque-recovery.ts
+++ b/src/server/responses/core-opaque-recovery.ts
@@ -116,6 +116,88 @@ export function isReasoningBlobCallerMismatchMessage(message: string): boolean {
 }
 
 
+/**
+ * Longest embedded payload this will parse. The wrapper is a short error envelope; anything
+ * larger is not the shape being matched, and refusing to walk it keeps an upstream-controlled
+ * string from deciding how much work the classifier does.
+ */
+const LITELLM_EMBEDDED_PAYLOAD_LIMIT = 16_384;
+const LITELLM_WRAPPER_PREFIX = "litellm.BadRequestError:";
+const LITELLM_WRAPPER_MARKER = "OpenAIException - ";
+
+/**
+ * The JSON an OpenAI-compatible gateway embeds in its own error message, or undefined.
+ *
+ * Brace-aware rather than a regex because the embedded object legitimately contains braces and
+ * escaped quotes inside its message, and the gateway appends its own prose after the closing
+ * brace. Counting depth outside string literals is the only way to find the real end.
+ */
+function liteLlmEmbeddedErrorPayload(message: string): unknown {
+  if (!message.startsWith(LITELLM_WRAPPER_PREFIX)) return undefined;
+  const markerIndex = message.indexOf(LITELLM_WRAPPER_MARKER);
+  if (markerIndex < 0) return undefined;
+  const start = message.indexOf("{", markerIndex + LITELLM_WRAPPER_MARKER.length);
+  if (start < 0) return undefined;
+  const end = Math.min(message.length, start + LITELLM_EMBEDDED_PAYLOAD_LIMIT);
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = start; index < end; index += 1) {
+    const character = message[index]!;
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"') { inString = true; continue; }
+    if (character === "{") depth += 1;
+    else if (character === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        try { return JSON.parse(message.slice(start, index + 1)) as unknown; } catch { return undefined; }
+      }
+    }
+  }
+  return undefined;
+}
+
+
+/** True for an error message that is a gateway envelope rather than an upstream's own wording. */
+function isLiteLlmEnvelopeMessage(message: string): boolean {
+  return message.startsWith(LITELLM_WRAPPER_PREFIX) && message.includes(LITELLM_WRAPPER_MARKER);
+}
+
+
+/**
+ * An OpenAI-compatible gateway relaying the one authoritative ciphertext rejection inside its
+ * own error string.
+ *
+ * Deliberately narrower than {@link isSelfIdentifiedOpaqueBlobRejection}. The embedded payload is
+ * matched against exactly one identity -- `invalid_request_error` carrying
+ * `invalid_encrypted_content` -- and the generic classifier is NOT re-run against it. Re-running
+ * it would let every other opaque identity arrive through the wrapper as well: the code-less
+ * unverifiable-ciphertext wording, the #4469 caller mismatch, and the two xAI decoder strings.
+ * Each of those was admitted on evidence from a specific upstream about how that upstream words
+ * its own rejection, and a gateway in between is not that evidence. Only the coded identity is
+ * unambiguous enough to survive relaying.
+ */
+export function isLiteLlmWrappedCiphertextRejection(payload: unknown): boolean {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+  const outer = (payload as { error?: unknown }).error;
+  if (!outer || typeof outer !== "object" || Array.isArray(outer)) return false;
+  const message = (outer as { message?: unknown }).message;
+  if (typeof message !== "string") return false;
+  const embedded = liteLlmEmbeddedErrorPayload(message);
+  if (!embedded || typeof embedded !== "object" || Array.isArray(embedded)) return false;
+  const inner = (embedded as { error?: unknown }).error;
+  if (!inner || typeof inner !== "object" || Array.isArray(inner)) return false;
+  const { type, code } = inner as { type?: unknown; code?: unknown };
+  return type === "invalid_request_error" && code === "invalid_encrypted_content";
+}
+
+
 export function isSelfIdentifiedOpaqueBlobRejection(bodyText: string): boolean {
   if (isEncryptedFunctionOutputRejection(bodyText)) return true;
   try {
@@ -132,6 +214,14 @@ export function isSelfIdentifiedOpaqueBlobRejection(bodyText: string): boolean {
 
     if (record.error && typeof record.error === "object" && !Array.isArray(record.error)) {
       const error = record.error as { type?: unknown; code?: unknown; message?: unknown };
+      // A gateway envelope is decided ONLY by its embedded payload, before any wording check
+      // below runs. Those checks match anchored phrases anywhere in the message, and a gateway
+      // quotes the upstream's message inside its own -- so without this the relayed text would
+      // satisfy the caller-mismatch identity and gain a resend the strict wrapper check exists to
+      // withhold. Returning here rather than falling through is the point.
+      if (typeof error.message === "string" && isLiteLlmEnvelopeMessage(error.message)) {
+        return isLiteLlmWrappedCiphertextRejection(payload);
+      }
       if (error.type === "invalid_request_error") {
         if (error.code === "invalid_encrypted_content") return true;
         if (
diff --git a/src/server/responses/fetch-helpers.ts b/src/server/responses/fetch-helpers.ts
index b2e44969740..61981aac401 100644
--- a/src/server/responses/fetch-helpers.ts
+++ b/src/server/responses/fetch-helpers.ts
@@ -12,9 +12,57 @@ import { waitForProviderRequestSlot } from "../../providers/request-pacing";
 import { withUpstreamHttpVersion } from "../../lib/upstream-http-version";
 import type { CodexWsQuotaObserver } from "./codex-ws-metadata";
 import { configuredOutboundFetch } from "../../lib/proxy-env";
+import {
+  describeProviderEgressForLog,
+  markEgressTransparentExecutor,
+  providerEgressSendInit,
+  providerEgressIsExplicit,
+  resolveProviderEgress,
+  type ProviderEgressBinding,
+} from "../../lib/provider-egress";
+import { redactSecretString } from "../../lib/redact";
 
 export { withUpstreamHttpVersion };
 
+const egressWebsocketDowngradeWarned = new Set<string>();
+/** A provider name is configuration-controlled, so the notice set is bounded like any cache. */
+const EGRESS_DOWNGRADE_NOTICE_LIMIT = 64;
+/**
+ * Marks an init whose provider egress route an outer physical-send boundary already decided.
+ *
+ * Own symbol keys survive object spread, so the mark travels through the rebuild a
+ * `dispatchOverride` performs, and an unknown symbol on a `RequestInit` is inert at the wire.
+ */
+const EGRESS_DECIDED = Symbol.for("opencodex.provider-egress.decided");
+
+/**
+ * Announce once, per provider, that an explicit egress route moved this provider off the
+ * WebSocket fast lane.
+ *
+ * The WebSocket upstream selects its proxy from the process environment when it dials, so it
+ * cannot carry a per-provider route. Serving the turn over HTTP/SSE honours the operator's
+ * egress choice, which is the one that has to win — but a transport change the operator did
+ * not ask for is exactly the kind of substitution this batch refuses to make silently, so it
+ * is stated rather than merely done.
+ */
+function warnEgressWebsocketDowngradeOnce(providerName: string, egress: string): void {
+  if (egressWebsocketDowngradeWarned.has(providerName)) return;
+  if (egressWebsocketDowngradeWarned.size >= EGRESS_DOWNGRADE_NOTICE_LIMIT) return;
+  egressWebsocketDowngradeWarned.add(providerName);
+  console.warn(
+    // The name is caller-controlled and can be token-shaped, so it is redacted and JSON-escaped
+    // before it reaches a log, exactly as at the management error boundary.
+    `[opencodex] provider ${JSON.stringify(redactSecretString(providerName))} declares egress ${egress}; the WebSocket upstream `
+    + "selects its proxy from the process environment and cannot carry a per-provider route, "
+    + "so these turns are served over HTTP/SSE.",
+  );
+}
+
+/** Test seam: the downgrade notice is once per provider per process, not once per request. */
+export function __resetEgressWebsocketDowngradeNotices(): void {
+  egressWebsocketDowngradeWarned.clear();
+}
+
 export function disableResponsesRequestTimeout(req: Request, server: Pick<Server<WsData>, "timeout"> | undefined): boolean {
   if (!server) return false;
   try {
@@ -97,21 +145,43 @@ export function sendWithConnectionPolicy(
   physicalFetch: typeof globalThis.fetch,
   input: Parameters<typeof globalThis.fetch>[0],
   init?: RequestInit,
+  egress?: ProviderEgressBinding,
 ): Promise<Response> {
   const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
   const fresh = wantsFreshConnection(input);
   if (fresh) {
     headers.set("Connection", "close");
   }
+  // Decided here, against the destination this send is actually going to, and around whichever
+  // executor was just selected. A `dispatchOverride` that rebuilds a queued request can change
+  // both the upstream host and the provider transport after the wrapper was constructed, so a
+  // route resolved at construction could be applied to a different host than it was decided for.
+  // These calls nest: an override decides with its own binding and then hands the send to the
+  // executor `providerFetch` supplied, which is another one of these. The outermost caller holds
+  // the reselected provider and the rebuilt destination, so it decides and marks the init; the
+  // inner pass honours that mark rather than recomputing from a stale closure.
+  const alreadyDecided = (init as Record<symbol, unknown> | undefined)?.[EGRESS_DECIDED] === true;
+  const decide = egress !== undefined && !alreadyDecided;
+  const egressInit = decide ? providerEgressSendInit(egress, physicalFetch, input) : {};
   return physicalFetch(input, {
     ...init,
     headers,
     redirect: "manual",
     ...(fresh ? { keepalive: false } : {}),
+    ...egressInit,
+    ...(decide ? { [EGRESS_DECIDED]: true } : {}),
   });
 }
 
 export interface ProviderFetchOptions {
+  /**
+   * Keep this send on HTTP even where the WebSocket upstream would normally be selected.
+   *
+   * Set by a caller replacing an HTTP stream that already failed: a WS create frame is a
+   * different send on a different transport, and the replacement has to be the same kind of
+   * exchange the client is already reading.
+   */
+  httpOnly?: boolean;
   nativeControl?: NativeResponseControl;
   providerName?: string;
   modelId?: string;
@@ -130,28 +200,63 @@ export function providerFetch(
   runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
   options: ProviderFetchOptions = {},
 ): ProviderFetch {
-  const configuredFetch = Object.assign(
+  const providerName = options.providerName ?? "<unnamed provider>";
+  const customExecutor = (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch;
+  // The route is applied at the physical send (see `sendWithConnectionPolicy`). This binding is
+  // only what that boundary needs to decide it.
+  const egressBinding: ProviderEgressBinding = { providerName, provider };
+  // Resolved per request, not once per wrapper: `providers.<name>.noProxy` is evaluated against
+  // the destination, so two requests through the same executor can legitimately take different
+  // routes. A malformed value throws and rejects the request rather than degrading to the
+  // global proxy or to direct, either of which would read as success at the call site.
+  const egressFor = (input: Parameters<typeof globalThis.fetch>[0]) => resolveProviderEgress({
+    providerName,
+    provider,
+    url: typeof input === "string" ? input : input instanceof URL ? input : input.url,
+  });
+  // The built-in executor forwards its init to a transport that honours the proxy option.
+  const configuredFetch = markEgressTransparentExecutor(Object.assign(
     (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => configuredOutboundFetch(input, init),
     { preconnect: globalThis.fetch.preconnect?.bind(globalThis.fetch) },
-  ) as typeof globalThis.fetch;
-  const base = (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch ?? configuredFetch;
+  ) as typeof globalThis.fetch);
+  const base = customExecutor ?? configuredFetch;
   const preconnect = (...args: Parameters<typeof globalThis.fetch.preconnect>): void => {
     base.preconnect?.(...args);
   };
   // Rebuilt dispatches must use the same physical-send boundary as ordinary HTTP sends.
   // Return the original 3xx so the response owner retains its retry/health/relay contract.
-  const dispatch = Object.assign(
+  //
+  // Marked transparent because it forwards its init to a transport that honours the proxy
+  // option. Leaving it unmarked would make an ordinary configured provider refuse its own route
+  // on every overridden path, after the attempt had already been recorded — an override selects
+  // `provider.fetch ?? execute`, and `execute` is this wrapper. It still carries the binding, so
+  // an override that simply calls it gets the route decided rather than dropped; an override
+  // that decided for itself has already marked the init and this pass defers to that decision.
+  const dispatch = markEgressTransparentExecutor(Object.assign(
     (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) =>
-      sendWithConnectionPolicy(base, input, init),
+      sendWithConnectionPolicy(base, input, init, egressBinding),
     { preconnect },
-  ) as typeof globalThis.fetch;
+  ) as typeof globalThis.fetch);
   const httpFetch = Object.assign(
     async (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
+      // Refuse before any dispatch side effect where that is sound. `beforeDispatch` commits
+      // attempt accounting and consumes admission state, so a refusal firing after it would
+      // charge an attempt for a send that never happens, and a throwing hook would mask the
+      // egress error with an unrelated one.
+      //
+      // With no override, this input and `base` ARE the final destination and executor, so the
+      // full decision can be made now. With an override, only the configured value is checked:
+      // the override may rebuild against a different host and select a different transport, and
+      // refusing on this destination would reject a request whose real route is fine.
+      if (options.dispatchOverride) egressFor(input);
+      else providerEgressSendInit(egressBinding, base, input);
       // The hook inspects the outgoing headers and refuses the send by throwing; it is not a
       // mutator, and the copy it receives is deliberately not threaded onward. `Connection`
       // is decided inside `dispatch`, which runs after this, so the fresh-connection policy
       // wins regardless of what any caller or hook put in the header.
       options.beforeDispatch?.(new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined)));
+      // No proxy option is attached here: a `dispatchOverride` may rebuild this request against
+      // a different destination, so the route is decided at the physical send instead.
       const dispatchInit = { ...withUpstreamHttpVersion(input, init, provider), timeout: 0 };
       return options.dispatchOverride
         ? options.dispatchOverride(input, dispatchInit, dispatch)
@@ -164,7 +269,13 @@ export function providerFetch(
   // else keeps the provider's HTTP fetch. See ws-upstream.ts for the details.
   const unpaced = async (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
     const upstreamWebsocket = provider.upstreamWebsocket === true;
-    if (typeof input === "string" && init && shouldUseCodexWsUpstream(input, init, runtime, upstreamWebsocket)) {
+    if (!options.httpOnly && typeof input === "string" && init
+      && shouldUseCodexWsUpstream(input, init, runtime, upstreamWebsocket)) {
+      const egress = egressFor(input);
+      if (providerEgressIsExplicit(egress)) {
+        warnEgressWebsocketDowngradeOnce(providerName, describeProviderEgressForLog(egress));
+        return httpFetch(input, init);
+      }
       // The fallback has to be the same HTTP fetch the non-WS branch would have
       // used, protocol pin included: a WS turn that falls back is serving the
       // request over HTTP, and dropping the provider's `upstreamHttpVersion`
@@ -188,11 +299,16 @@ export function providerFetch(
     await waitForPacing(init?.signal ?? undefined);
     return unpaced(input, init);
   };
-  return Object.assign(wrapped, {
+  // The returned wrapper forwards its init down to `dispatch`, which applies the route at the
+  // physical send. Adapters that hand this executor back as `provider.fetch` (Cursor does)
+  // therefore still carry a per-provider route instead of being refused as opaque.
+  const paceAware = Object.assign(wrapped, {
     preconnect,
     waitForPacing,
     unpacedFetch: Object.assign(unpaced, { preconnect }),
   });
+  markEgressTransparentExecutor(paceAware as unknown as typeof globalThis.fetch);
+  return paceAware;
 }
 
 
diff --git a/src/server/responses/input-admission.ts b/src/server/responses/input-admission.ts
index ca11fd60eb5..950a3d90505 100644
--- a/src/server/responses/input-admission.ts
+++ b/src/server/responses/input-admission.ts
@@ -85,9 +85,19 @@ function imageTokens(imageUrl: string): number {
 function contentPartTokens(part: OcxContentPart, modelId: string): number {
   if (part.type === "image") return imageTokens(part.imageUrl);
   if (part.type === "video") return imageTokens(part.videoUrl);
+  // An inline document is a base64 payload, not a sentence: estimating it from its marker would
+  // admit a request whose real input is orders of magnitude larger. Counted arithmetically —
+  // rebuilding the data URL here would materialize a second request-sized string just to measure it.
+  if (part.type === "document") return base64PayloadTokens(part.data);
   return estimateTokens(part.text, modelId);
 }
 
+function base64PayloadTokens(base64: string): number {
+  if (base64.length === 0) return 0;
+  const decoded = Math.floor((base64.length * 3) / 4);
+  return Math.max(1, Math.ceil(decoded / IMAGE_BYTES_PER_TOKEN));
+}
+
 function contentTokens(content: string | readonly OcxContentPart[], modelId: string): number {
   if (typeof content === "string") return estimateTokens(content, modelId);
   let total = 0;
diff --git a/src/server/responses/passthrough-delivery.ts b/src/server/responses/passthrough-delivery.ts
index f6cd0009987..969cd84e589 100644
--- a/src/server/responses/passthrough-delivery.ts
+++ b/src/server/responses/passthrough-delivery.ts
@@ -93,6 +93,7 @@ import { createResponsesFieldBackfillBlockRewrite } from "./responses-field-back
 import { createResponsesFunctionToolRepairBlockRewrite } from "../responses-function-tool-repair";
 import {
   createUndeclaredToolCallGuardBlockRewrite,
+  currentTurnWireToolCatalogBody,
   undeclaredToolCallNameInResponse,
   undeclaredToolCallMessage,
   normalizeDefaultNamespaceInJson,
@@ -515,7 +516,19 @@ export async function deliverPassthroughResponse(
           ? createGrokResponsesTimestampBlockRewrite()
           : undefined,
         grokClientCompatibilityEnabled
-          ? createGrokResponsesSparseTerminalBlockRewrite(translatorBudget)
+          ? createGrokResponsesSparseTerminalBlockRewrite(
+            translatorBudget,
+            nativeExchange.outboundRequestBody,
+            {
+              clientToolAuthorizationBody: currentTurnWireToolCatalogBody(
+                parsed._rawBody,
+                parsed._replayPrefixLen ?? 0,
+              ),
+              routedNamespaceToolAliases: responseEffects.routedNamespaceToolAliases,
+              routedMuseToolNameAliases: responseEffects.routedMuseToolNameAliases,
+              convertedRoutedCustomToolNames: routedCustomToolNames,
+            },
+          )
           : undefined,
         snapshotRepairEnabled
           ? createResponsesSnapshotBlockRewrite(nativeExchange.outboundRequestBody, translatorBudget)
diff --git a/src/server/responses/passthrough-dispatch.ts b/src/server/responses/passthrough-dispatch.ts
index 6676bbd1d40..7bd9b64253c 100644
--- a/src/server/responses/passthrough-dispatch.ts
+++ b/src/server/responses/passthrough-dispatch.ts
@@ -102,7 +102,7 @@ import {
   clearCodexModelDenialEvidence,
   recordCodexModelDenialEvidence,
 } from "../../codex/model-entitlements";
-import { readCodexWsStage } from "./codex-ws-wire";
+import { isCodexWsUpstreamResponse, readCodexWsStage } from "./codex-ws-wire";
 import { linkAbortSignal } from "./core-lifetime";
 import type { CodexAuthContext } from "../../codex/auth-context";
 import { checkOutboundBodySize, describeOutboundBodyRefusal } from "./outbound-body-guard";
@@ -112,7 +112,8 @@ import {
   fetchWithTransientRetry,
   applyUpstreamRecoveryInit,
   isNonReplayableResponse,
- prepareSameTarget429Wait,
+  refetchAfterProtocolSafeReset,
+  prepareSameTarget429Wait,
   sleepWithAbort,
 } from "../../lib/upstream-retry";
 import { mapCodexAuthContextErrorToResponse } from "./codex-auth-error";
@@ -151,7 +152,9 @@ import {
   reasoningEffortRejectionText,
 } from "./core-opaque-recovery";
 import type { RequestLogContext } from "../request-log";
-import { preflightComboStreamResponse } from "./combo-stream-preflight";
+import { deferProtocolSafeResetRecovery, preflightComboStreamResponse } from "./combo-stream-preflight";
+import { authorizeResendForRecovery } from "../../lib/request-resend-gate";
+import { ambiguousResendAllowanceFor, selfContainedResponsesBody } from "./reset-replay";
 import { upstreamErrorMessageFromPayload, ENCRYPTED_FUNCTION_OUTPUT_REJECTION } from "../../lib/errors";
 import { isTransientConsoleGoUploadRejection } from "../../providers/opencode-zen-rate-limit";
 import { planReasoningEffortDowngrade } from "../../providers/reasoning-metadata";
@@ -189,6 +192,8 @@ export async function preparePassthroughExchange(
     | "genericFailovers"
     | "applyFailoverSnapshot"
     | "noteRoutedAttemptSend"
+    | "selectionIsCurrent"
+    | "requestBindings"
   >,
   responseEffects: Pick<
     ResponsesEffects,
@@ -206,6 +211,7 @@ export async function preparePassthroughExchange(
     | "recoverySendAllowance"
     | "recoveryClassFor"
     | "sendBudgetExhausted"
+    | "claimAmbiguousResend"
     | "reserveCredentialHop"
     | "pendingHopPermit"
     | "workflowRootId"
@@ -239,6 +245,7 @@ export async function preparePassthroughExchange(
     recoverySendAllowance,
     recoveryClassFor,
     sendBudgetExhausted,
+    claimAmbiguousResend,
     reserveCredentialHop,
     workflowRootId,
   } = sendBudgetState;
@@ -704,6 +711,35 @@ export async function preparePassthroughExchange(
     );
     const configuredTransientSendBudgetExhausted = (): boolean =>
       transientSendPolicy() !== null && transientSendAttempts() === 0;
+    /**
+     * Judged once. The inbound body does not change between legs, and every rebuild this lane
+     * performs only ever REMOVES a hazard -- `previous_response_id` is expanded, hosted tools
+     * are lowered into client execution -- so a body that was replaceable stays replaceable.
+     * Memoized rather than recomputed because it walks the input array, and a provider that
+     * never opted in must not pay for it at all.
+     */
+    let selfContainedJudgment: boolean | undefined;
+    const requestIsSelfContained = (): boolean =>
+      selfContainedJudgment ??= selfContainedResponsesBody(parsed._rawBody);
+    /**
+     * The operator's replacement grant for THIS logical request.
+     *
+     * Read per leg because `route.provider` is reassigned by credential rotation and transport
+     * resolution inside the recovery loop, exactly like `transientSendPolicy`. The counter it
+     * claims from is not per leg: it lives on the request's execution budget, which a combo
+     * child shares, so every ambiguous stage of this request draws on the same grant.
+     */
+    const ambiguousResend = () =>
+      ambiguousResendAllowanceFor(route.provider, requestIsSelfContained, claimAmbiguousResend);
+    /**
+     * The pre-header row of the stage table, asked through the one gate.
+     *
+     * `fetchWithResetRetry` takes a plain callback because it is a leaf that must not import
+     * the server tree; routing the answer through `authorizeResendForRecovery` here is what
+     * keeps the decision derived from the table rather than restated as a boolean.
+     */
+    const claimPreHeaderResend = (): boolean =>
+      authorizeResendForRecovery("pre-header", "connection-reset", ambiguousResend()).allowed;
     /**
      * Refuse a built body that exceeds the operator's configured ceiling, before it is sent.
      *
@@ -845,6 +881,7 @@ export async function preparePassthroughExchange(
         },
         { abortSignal: upstream.signal, label: safeHostLabel(request.url),
           attempts: remainingTransientSendBudget(transientSendAttempts()), onSendsConsumed: noteTransientSends,
+          claimAmbiguousResend: claimPreHeaderResend,
           // The OpenCode Go destination stalls-then-drops inference sends (ambiguous
           // pre-header resets surfacing as refused 429s); its subscription traffic is
           // inference-only, so a bounded reset replay here absorbs the blip instead of
@@ -949,7 +986,8 @@ export async function preparePassthroughExchange(
               route.provider.authMode === "forward")
               .then(adoptObservedResponse);
           },
-          { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: allowance.attempts, onSendsConsumed: noteTransientSends },
+          { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: allowance.attempts,
+            onSendsConsumed: noteTransientSends, claimAmbiguousResend: claimPreHeaderResend },
         );
       } catch (err) {
         return { failed: transportFailureResponse(err) };
@@ -1030,35 +1068,54 @@ export async function preparePassthroughExchange(
         // every other build site; a replay is exactly when a grown payload reappears.
         const replayBodyRefusal = refuseOversizedOutboundBody(request);
         if (replayBodyRefusal) return replayBodyRefusal;
-        transportState.noteRoutedAttemptSend(passthroughEstimate, "oauth-401");
-        upstreamResponse = await fetchWithHeaderTimeout(
-          request.url,
-          { method: request.method, headers: request.headers, body: request.body },
-          upstream.signal,
-          connectMs,
-          parsed.stream,
-          // The replay-dispatched signal is what bounds the rest of this logical request, so it
-          // has to describe a send that actually happened. fetchWithHeaderTimeout awaits pacing
-          // admission BEFORE calling the executor, so signalling at the call site would spend the
-          // budget even when a rejected pacing wait means nothing reaches the network. Wrapping
-          // the executor moves the signal to the last moment before the send, where a throw from
-          // here on is a genuine transport attempt.
-          storedPoolReplayDispatchNotifier(
-            providerFetch(route.provider, options.codexWsRuntimeIdentity, {
-              nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
-                && responseEffects.plaintextV2AgentMessageToolNames.size === 0
-                ? options.nativeControl : undefined,
-              dispatchOverride: oauthDispatch(request),
-              providerName: route.providerName,
-              modelId: route.modelId,
-              onCodexWsQuota: codexWsQuotaObserver(admissionState.authCtx, route.provider, route.modelId),
-              beforeDispatch: isCanonicalOpenAiForwardProvider(route.provider)
-                ? createCodexReserveDispatchGuard(admissionState.authCtx, options.codexAuthPolicy ?? config, route.modelId, options.admission, options.visionDescribeTerminal === true) : undefined,
-            }),
-            codex401ReplayKind === "stored" ? options.onStoredPool401ReplayDispatched : undefined,
-          ),
-          route.provider.authMode === "forward",
-        ).then(adoptObservedResponse);
+        // The replay-dispatched signal is what bounds the rest of this logical request, so it
+        // has to describe a send that actually happened. fetchWithHeaderTimeout awaits pacing
+        // admission BEFORE calling the executor, so signalling at the call site would spend the
+        // budget even when a rejected pacing wait means nothing reaches the network. Wrapping
+        // the executor moves the signal to the last moment before the send, where a throw from
+        // here on is a genuine transport attempt. The notifier is built once for the whole leg:
+        // it fires on the first dispatch, and a replacement is another send of the same replay
+        // rather than a second one to announce.
+        const oauthReplayExecutor = storedPoolReplayDispatchNotifier(
+          providerFetch(route.provider, options.codexWsRuntimeIdentity, {
+            nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
+              && responseEffects.plaintextV2AgentMessageToolNames.size === 0
+              ? options.nativeControl : undefined,
+            dispatchOverride: oauthDispatch(request),
+            providerName: route.providerName,
+            modelId: route.modelId,
+            onCodexWsQuota: codexWsQuotaObserver(admissionState.authCtx, route.provider, route.modelId),
+            beforeDispatch: isCanonicalOpenAiForwardProvider(route.provider)
+              ? createCodexReserveDispatchGuard(admissionState.authCtx, options.codexAuthPolicy ?? config, route.modelId, options.admission, options.visionDescribeTerminal === true) : undefined,
+          }),
+          codex401ReplayKind === "stored" ? options.onStoredPool401ReplayDispatched : undefined,
+        );
+        // Routed through the shared helper so an ambiguous reset on THIS leg answers with the
+        // same refusal every other leg gives. A bare fetch here rejected instead, and the
+        // caller's transport-failure path turns a rejection into a client-retryable 502 --
+        // which invites the whole turn to be sent again, on a leg whose first send may already
+        // have run it.
+        upstreamResponse = await fetchWithTransientRetry(
+          recovery => {
+            transportState.noteRoutedAttemptSend(passthroughEstimate, recovery ?? "oauth-401");
+            return fetchWithHeaderTimeout(
+              request.url,
+              applyUpstreamRecoveryInit({
+                method: request.method,
+                headers: request.headers,
+                body: request.body,
+              }, recovery),
+              upstream.signal,
+              connectMs,
+              parsed.stream,
+              oauthReplayExecutor,
+              route.provider.authMode === "forward",
+            ).then(adoptObservedResponse);
+          },
+          { abortSignal: upstream.signal, label: safeHostLabel(request.url),
+            attempts: remainingTransientSendBudget(transientSendAttempts()),
+            onSendsConsumed: noteTransientSends, claimAmbiguousResend: claimPreHeaderResend },
+        );
       } catch (err) {
         return transportFailureResponse(err);
       } finally {
@@ -1182,7 +1239,8 @@ export async function preparePassthroughExchange(
               route.provider.authMode === "forward")
               .then(adoptObservedResponse);
           },
-          { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(transientSendAttempts()), onSendsConsumed: noteTransientSends },
+          { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(transientSendAttempts()),
+            onSendsConsumed: noteTransientSends, claimAmbiguousResend: claimPreHeaderResend },
         );
       } catch (err) {
         return transportFailureResponse(err);
@@ -1314,7 +1372,8 @@ export async function preparePassthroughExchange(
               route.provider.authMode === "forward")
               .then(adoptObservedResponse);
           },
-          { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(transientSendAttempts()), onSendsConsumed: noteTransientSends },
+          { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(transientSendAttempts()),
+            onSendsConsumed: noteTransientSends, claimAmbiguousResend: claimPreHeaderResend },
         );
       } catch (err) {
         return transportFailureResponse(err);
@@ -1571,6 +1630,91 @@ export async function preparePassthroughExchange(
         continue passthroughRecovery;
       }
     }
+
+    // The post-header row of the same table. A native SSE body can die after the head with the
+    // caller having observed nothing, which is the identical question the pre-header helper
+    // answers -- and the identical grant, because both claim from this request's one allowance.
+    const streamRecoveryContentType = upstreamResponse.headers.get("content-type")?.toLowerCase() ?? "";
+    const protocolRecoveryCandidate = upstreamResponse.ok
+      && !!upstreamResponse.body
+      && !isNonReplayableResponse(upstreamResponse)
+      // The WebSocket transport settles its own ambiguous failures and marks them
+      // non-replayable; re-reading its body here would be a second owner of one exchange.
+      && !isCodexWsUpstreamResponse(upstreamResponse)
+      // A downstream WebSocket turn that fell back to HTTP must relay response.created
+      // immediately so the client can address the turn and receive explicit control refusal.
+      // This preflight retains that event until output commits, so the two contracts cannot
+      // share one body owner.
+      && !(options.nativeControl && options.inboundTransport === "websocket")
+      && ambiguousResend() !== undefined
+      && remainingTransientSendBudget(transientSendAttempts()) > 0
+      && (streamRecoveryContentType.includes("text/event-stream") || (!streamRecoveryContentType && parsed.stream));
+    if (protocolRecoveryCandidate) {
+      upstreamResponse = deferProtocolSafeResetRecovery(
+        upstreamResponse,
+        { model: logCtx.model, provider: logCtx.provider },
+        (error, stage) => refetchAfterProtocolSafeReset(
+          (signal = upstream.signal) => fetchWithHeaderTimeout(
+            request.url,
+            applyUpstreamRecoveryInit({
+              method: request.method,
+              headers: request.headers,
+              body: request.body,
+            }, "connection-reset"),
+            signal,
+            connectMs,
+            true,
+            providerFetch(route.provider, options.codexWsRuntimeIdentity, {
+              // A replacement HTTP body must not open a fresh WebSocket exchange: the turn it
+              // replaces was an HTTP stream, and a WS create frame is a different send.
+              httpOnly: true,
+              providerName: route.providerName,
+              modelId: route.modelId,
+              dispatchOverride: oauthDispatch(request),
+              beforeDispatch: headers => {
+                if (signal.aborted) throw signal.reason;
+                if (!transportState.selectionIsCurrent(transportState.requestBindings.get(request))) {
+                  throw new Error("Credential selection changed before pre-output stream recovery");
+                }
+                if (isCanonicalOpenAiForwardProvider(route.provider)) {
+                  createCodexReserveDispatchGuard(
+                    admissionState.authCtx,
+                    options.codexAuthPolicy ?? config,
+                    route.modelId,
+                    options.admission,
+                    options.visionDescribeTerminal === true,
+                  )?.(headers);
+                }
+                // Recorded with the kind the gate derived its cause from, at the moment the
+                // send actually leaves. One authorisation, one recorded reason, one send.
+                transportState.noteRoutedAttemptSend(passthroughEstimate, "connection-reset");
+                // Charged to the SAME request counter every other send goes through. The
+                // replacement is bought here rather than by a nested retry helper, so there is
+                // one charge for one send and no per-layer counter to reconcile.
+                noteTransientSends(1);
+              },
+            }),
+            route.provider.authMode === "forward",
+          ).then(adoptObservedResponse),
+          error,
+          {
+            abortSignal: upstream.signal,
+            label: safeHostLabel(request.url),
+            attempts: remainingTransientSendBudget(transientSendAttempts()),
+            // The whole decision, including the stage the preflight observed and the grant the
+            // pre-header helper shares. A committed stage refuses here without touching the
+            // allowance, which is what keeps a turn that already emitted output from draining
+            // the replacement a later ambiguous reset would have been entitled to.
+            authorize: () => authorizeResendForRecovery(stage, "connection-reset", ambiguousResend()).allowed,
+            acceptResponse: candidate => {
+              const type = candidate.headers.get("content-type")?.toLowerCase() ?? "";
+              return type.includes("text/event-stream") || (!type && parsed.stream);
+            },
+          },
+        ),
+        { allowMissingContentType: !streamRecoveryContentType && parsed.stream },
+      );
+    }
     break;
     }
 
diff --git a/src/server/responses/passthrough-error.ts b/src/server/responses/passthrough-error.ts
index eee33c02a96..7a993255ee3 100644
--- a/src/server/responses/passthrough-error.ts
+++ b/src/server/responses/passthrough-error.ts
@@ -1,6 +1,11 @@
 import { formatErrorResponse } from "../../bridge";
 import { isCyberPolicyCode, isCyberPolicyMessage } from "../../lib/errors";
-import { isReplayRefusalCode, UPSTREAM_RESET_REPLAY_REFUSED_CODE } from "../../lib/upstream-retry";
+import {
+  applyReplayRefusalClientHeaders,
+  isReplayRefusalCode,
+  retainReplayRefusal,
+  UPSTREAM_RESET_REPLAY_REFUSED_CODE,
+} from "../../lib/upstream-retry";
 import {
   resolveClientRetryAfter,
   validateClientRetryAfterHeader,
@@ -62,6 +67,10 @@ function isReplayRefusalBody(body: string): boolean {
  * - a replay refusal this proxy wrote gets none and keeps none: the whole point of the
  *   refusal is that the turn may already be running, and the synthetic default for a
  *   retryable 429 is a direct instruction to the client to send it a second time
+ *
+ * A refusal also leaves with the shared no-retry header and the in-process marker, so the
+ * verdict survives this re-wrap as a property of the response rather than as a status a later
+ * reader would have to guess from.
  */
 export function formatPassthroughUpstreamError(
   status: number,
@@ -84,11 +93,10 @@ export function formatPassthroughUpstreamError(
   const upstreamRetryAfter = options?.headers?.get("retry-after")?.trim() || undefined;
   const originalValid = validateClientRetryAfterHeader(upstreamRetryAfter, now);
   const cyberPolicyFailure = isCyberPolicyBody(trimmed);
+  const replayRefusal = options?.replayRefusal === true || isReplayRefusalBody(trimmed);
   // Two different reasons to answer with no wait at all, handled the same way: a hard policy
   // block will not become servable, and a refusal we made was never a rate limit.
-  const suppressRetryAfter = cyberPolicyFailure
-    || options?.replayRefusal === true
-    || isReplayRefusalBody(trimmed);
+  const suppressRetryAfter = cyberPolicyFailure || replayRefusal;
   const resolved = suppressRetryAfter
     ? undefined
     : resolveClientRetryAfter({
@@ -105,7 +113,9 @@ export function formatPassthroughUpstreamError(
         && upstreamRetryAfter !== undefined
         && originalValid === undefined);
 
-    if (!needsSet && !needsDelete) {
+    // A refusal always takes the rewriting path: it has a header to add even when the
+    // upstream named no wait for it to remove.
+    if (!needsSet && !needsDelete && !replayRefusal) {
       return new Response(bodyText, {
         status,
         ...(options?.statusText ? { statusText: options.statusText } : {}),
@@ -118,21 +128,30 @@ export function formatPassthroughUpstreamError(
       : new Headers({ "Content-Type": "application/json" });
     if (needsSet) headers.set("Retry-After", resolved!);
     else headers.delete("Retry-After");
-    return new Response(bodyText, {
+    if (replayRefusal) applyReplayRefusalClientHeaders(headers);
+    const rewritten = new Response(bodyText, {
       status,
       ...(options?.statusText ? { statusText: options.statusText } : {}),
       headers,
     });
+    return replayRefusal ? retainReplayRefusal(rewritten) : rewritten;
   }
 
   const response = formatErrorResponse(
     status,
     "upstream_error",
     `Provider error ${status}: (empty body)`,
-    resolved !== undefined ? { retryAfter: resolved } : undefined,
+    // Provenance is all that is left when the bounded read returned nothing display-safe, and
+    // it is enough: the formatter allowlists this code, restates the refusal status and marks
+    // the response, so an unreadable refusal reaches the client as the same refusal.
+    replayRefusal
+      ? { code: UPSTREAM_RESET_REPLAY_REFUSED_CODE }
+      : resolved !== undefined ? { retryAfter: resolved } : undefined,
   );
   const headers = new Headers(response.headers);
   headers.set("Content-Type", "application/json");
   if (resolved !== undefined) headers.set("Retry-After", resolved);
-  return new Response(response.body, { status: response.status, headers });
+  if (replayRefusal) applyReplayRefusalClientHeaders(headers);
+  const wrapped = new Response(response.body, { status: response.status, headers });
+  return replayRefusal ? retainReplayRefusal(wrapped) : wrapped;
 }
diff --git a/src/server/responses/request-prepare.ts b/src/server/responses/request-prepare.ts
index 4d94d6a71ad..867f816414d 100644
--- a/src/server/responses/request-prepare.ts
+++ b/src/server/responses/request-prepare.ts
@@ -52,7 +52,7 @@ import { parseRequest } from "../../responses/parser";
 import { anthropicSessionKeyFromParts } from "../../oauth/anthropic-routing";
 import { isTranslatorBudgetExceededError } from "../../lib/translator-budget";
 import { bindTurnTerminationScope, rememberDeliveredFinalAnswer } from "../../responses/turn-termination";
-import { requestLogSpeedLabel, readConfiguredCodexServiceTier } from "../request-log";
+import { observeCacheDiagnosticInbound, rebindCacheDiagnosticBody, requestLogSpeedLabel, readConfiguredCodexServiceTier } from "../request-log";
 import type { RouteResult } from "../../router";
 import {
   captureRouteStaticPolicy,
@@ -110,6 +110,13 @@ import {
   CODEX_RESERVE_OPT_IN_REQUIRED_MESSAGE,
 } from "../../codex/loopback-target";
 import { checkComboTargetInputAdmission, checkInputAdmission } from "./input-admission";
+import {
+  admissionModelDeniedResponse,
+  AdmissionModelDeniedError,
+  assertRouteAllowedByScope,
+  resolveAdmissionModelScope,
+  routeAllowedByScope,
+} from "../admission-model-scope";
 import { nativeContextLimits } from "../../codex/catalog";
 import { streamingContextOverflowResponse } from "./context-overflow";
 import {
@@ -150,6 +157,14 @@ export async function prepareResponsesRequest(
     }
     return decodeRequestErrorResponse(err, "responses");
   }
+  observeCacheDiagnosticInbound(
+    logCtx,
+    body,
+    req.headers,
+    options.promptCacheKeyIsSharedCohort === true
+      ? "system-derived"
+      : options.promptCacheKeyIsSharedCohort === false ? "metadata-derived" : "caller",
+  );
   if (!options.comboAttempt && !options.compactionRoutingOverride && inboundWire === "responses") {
     options.compactionRoutingOverride = applyCompactionRoutingOverride(body, req.headers, config, {
       endpoint: "responses",
@@ -293,6 +308,10 @@ export async function prepareResponsesRequest(
   try {
     parsed = parseRequest(body);
     parsed._promptCacheKeyIsSharedCohort = options.promptCacheKeyIsSharedCohort;
+    // The body may have been rebuilt since the inbound observation (previous-response
+    // expansion); alias the parsed raw body to the same draft so the outbound
+    // observation at the adapter seam still finds it.
+    rebindCacheDiagnosticBody(parsed._rawBody, logCtx.cacheDiagnosticDraft);
     // Captured before any parser mutates it, so both grammars see the client's id.
     const { fastRow, effortRow } = parseSyntheticRowId(parsed.modelId, config);
     if (fastRow) {
@@ -411,7 +430,18 @@ export async function prepareResponsesRequest(
 
   let route: RouteResult;
   let credentialDomainWasRewritten = false;
+  // The selector the caller actually sent, captured before shadow interception
+  // or a subagent fallback rewrites it, so a refusal names the client's own
+  // request rather than a destination it never asked for.
+  const inboundSelector = parsed.modelId;
+  const admissionScope = resolveAdmissionModelScope(config, options.admission);
   const captureInboundRoutePolicy = (candidate: RouteResult): RouteResult => {
+    // Every route this request path produces passes through here: the direct
+    // name, an alias, a policy or combo selection, a compaction override, a
+    // shadow-intercept target and both subagent-fallback re-routes. Checking
+    // the key's scope at this one point is what stops a rewrite from reaching
+    // a destination the front door would have refused.
+    assertRouteAllowedByScope(admissionScope, inboundSelector, candidate);
     candidate.staticPolicy = captureRouteStaticPolicy(
       candidate.providerName,
       candidate.modelId,
@@ -474,6 +504,7 @@ export async function prepareResponsesRequest(
     }
     logCtx.routeDecision = route.routeDecision;
   } catch (err) {
+    if (err instanceof AdmissionModelDeniedError) return admissionModelDeniedResponse(err);
     if (err instanceof NoAvailableComboTargetsError) {
       return comboUnavailable(err.comboId);
     }
@@ -673,6 +704,7 @@ export async function prepareResponsesRequest(
         credentialDomainWasRewritten = true;
         logCtx.routeDecision = route.routeDecision;
       } catch (err) {
+        if (err instanceof AdmissionModelDeniedError) return admissionModelDeniedResponse(err);
         if (err instanceof NoAvailableComboTargetsError) {
           return comboUnavailable(err.comboId);
         }
@@ -873,6 +905,7 @@ export async function prepareResponsesRequest(
               credentialDomainWasRewritten = true;
               logCtx.routeDecision = route.routeDecision;
             } catch (err) {
+              if (err instanceof AdmissionModelDeniedError) return admissionModelDeniedResponse(err);
               if (err instanceof NoAvailableComboTargetsError) {
                 return comboUnavailable(err.comboId);
               }
@@ -1021,6 +1054,14 @@ export async function prepareResponsesRequest(
     inboundTransport: options.inboundTransport,
     claudeGoAffinity: options.claudeGoAffinity,
   });
+  // Normalization is the last thing that can move the destination: resolving an
+  // OpenAI virtual model rewrites route.modelId to the wire id that will
+  // actually be billed. A scope checked only before this would authorize the
+  // public selector and send the wire model, so the settled route is checked
+  // once more here.
+  if (!routeAllowedByScope(admissionScope, route)) {
+    return admissionModelDeniedResponse(new AdmissionModelDeniedError(inboundSelector, route));
+  }
   // Attribute local auth/cooldown failures to the public selector too; exact auth may fail before
   // the normal post-resolution provider label is assigned.
   if (route.codexAccountNamespace) {
diff --git a/src/server/responses/request-send-budget.ts b/src/server/responses/request-send-budget.ts
index 9250162da26..44ca16bc4d1 100644
--- a/src/server/responses/request-send-budget.ts
+++ b/src/server/responses/request-send-budget.ts
@@ -139,6 +139,16 @@ export function createResponsesSendBudget(
    */
   const sendBudgetExhausted = (cap: number = TRANSIENT_RETRY_MAX_ATTEMPTS): boolean =>
     remainingTransientSendBudget(cap) === 0;
+  /**
+   * Spend one operator-granted replacement for an ambiguous failure of THIS logical request.
+   *
+   * The counter is the execution budget's, so a combo child that derives its own scope draws on
+   * the same grant. A budget that predates it -- a stub, or a caller that passed the narrow
+   * holder -- cannot grant anything, and refusing is the fail-closed answer for a send whose
+   * upstream state is unknown.
+   */
+  const claimAmbiguousResend = (limit: number): boolean =>
+    isRequestExecutionBudget(sendBudget) && sendBudget.claimAmbiguousResend?.(limit) === true;
   /**
    * A credential hop reserves the send its own replay will make, and that replay is a recovery
    * leg. The leg must SPEND the hop's reservation instead of taking a second one: the
@@ -263,6 +273,7 @@ export function createResponsesSendBudget(
     noteAdapterPhysicalSend,
     noteAdapterRecoveryWithheld,
     sendBudgetExhausted,
+    claimAmbiguousResend,
     get pendingHopPermit(): SingleUseDispatchPermit | undefined {
       return pendingHopPermit;
     },
@@ -301,6 +312,7 @@ function adapterDispatchBudgetView(
     get targetTransitions(): number { return budget.targetTransitions; },
     get lastTargetKey(): string | undefined { return budget.lastTargetKey; },
     remainingBaseSends: (cap: number): number => budget.remainingBaseSends(cap),
+    claimAmbiguousResend: (limit: number): boolean => budget.claimAmbiguousResend?.(limit) === true,
     reserveDispatch(intent: DispatchIntent): DispatchDecision {
       // A dispatch whose upstream state is unknown is refused on its own merits. A hop that
       // already paid does not make an unsafe replay safe, so that check stays with the budget.
diff --git a/src/server/responses/request-transport.ts b/src/server/responses/request-transport.ts
index 11354c79497..e6834c7e941 100644
--- a/src/server/responses/request-transport.ts
+++ b/src/server/responses/request-transport.ts
@@ -64,6 +64,7 @@ import {
   recordKeyAttemptUsage,
 } from "../request-log";
 import type { AttemptRecoveryKind } from "../../usage/log";
+import { bindAttemptDeliveryRecorder } from "../../usage/attempt-delivery";
 import { resolvePassiveRouteSubjectId } from "../passive-route-linker";
 
 /** Owns live credential selection and adapter bindings for one request. */
@@ -298,15 +299,25 @@ export async function prepareResponsesTransport(
         recordKeyAttemptUsage(logCtx, event.usage);
       }
     };
+    // Counted at the one seam every adapter parse passes, and counted for EVERY event rather
+    // than only usage-bearing ones: the number this pairs with is the frame count the client
+    // transport relayed, and a difference between the two is the loss signal (#3983). Reading
+    // the current attempt through logCtx rather than capturing one keeps the count with the
+    // attempt that is live when the event arrives, across a mid-request attempt rotation.
+    const delivery = bindAttemptDeliveryRecorder(translatorBudget, () => logCtx.activeAttempt);
+    const observeEvent = (event: AdapterEvent, response: object): void => {
+      delivery.noteAdapterEvent();
+      observeUsage(event, response);
+    };
     const parseStream = resolved.parseStream.bind(resolved);
     resolved.parseStream = async function* (...args) {
-      for await (const event of parseStream(...args)) { observeUsage(event, args[0]); yield event; }
+      for await (const event of parseStream(...args)) { observeEvent(event, args[0]); yield event; }
     };
     if (resolved.parseResponse) {
       const parseResponse = resolved.parseResponse.bind(resolved);
       resolved.parseResponse = async (...args) => {
         const events = await parseResponse(...args);
-        events.forEach(event => observeUsage(event, args[0]));
+        events.forEach(event => observeEvent(event, args[0]));
         return events;
       };
     }
@@ -321,7 +332,7 @@ export async function prepareResponsesTransport(
       const runTurn = resolved.runTurn.bind(resolved);
       rawRunTurns.set(resolved, (requestParsed, incoming, emit) => {
         const response = {};
-        return runTurn(requestParsed, incoming, event => { observeUsage(event, response); emit(event); });
+        return runTurn(requestParsed, incoming, event => { observeEvent(event, response); emit(event); });
       });
       resolved.runTurn = (requestParsed, incoming, emit) => runSelectedTurn(resolved, requestParsed, incoming, emit);
     }
@@ -409,7 +420,16 @@ export async function prepareResponsesTransport(
           // Either way the send crosses the physical boundary, so the connection policy is
           // applied around whichever implementation was just selected (#4992).
           commitKeyAttemptSend();
-          const response = await sendWithConnectionPolicy(fetchImpl, destination, { ...dispatchInit, redirect: "manual" });
+          // The binding travels with the send, so a rebuilt request resolves its provider route
+          // against the destination it is actually going to rather than the one this dispatch
+          // started with. Account reselection can move the upstream host, which would otherwise
+          // apply a host-scoped decision to a different host.
+          const response = await sendWithConnectionPolicy(
+            fetchImpl,
+            destination,
+            { ...dispatchInit, redirect: "manual" },
+            { providerName: route.providerName, provider: route.provider },
+          );
           if (!response.ok) await recordKeyAttemptFailure(logCtx, response, dispatchInit.signal ?? options.abortSignal);
           // Observe each physical response before retries replace it. The binding belongs to
           // this dispatch, so a manual switch cannot file A's headers against B. Header
diff --git a/src/server/responses/reset-replay.ts b/src/server/responses/reset-replay.ts
new file mode 100644
index 00000000000..b8e47d44b93
--- /dev/null
+++ b/src/server/responses/reset-replay.ts
@@ -0,0 +1,108 @@
+/**
+ * The operator opt-in that overrides the stage table's refusal, and the one request-wide
+ * allowance both ambiguous stages claim from.
+ *
+ * `resendPermission` answers `refused-ambiguous` for a native Responses send that died with
+ * the caller having observed nothing -- before the response head, or after it while the SSE
+ * body carried only control events. This module is the one place that answer is overridden,
+ * and it is narrow on three axes at once: the provider has to opt in, the request has to be
+ * one whose second send cannot do more than run the same inference again, and the whole
+ * logical request gets a fixed number of replacements no matter how many legs ask.
+ *
+ * The judgment is made on the inbound body the client sent, which is already parsed. It is
+ * conservative for the outbound request: the proxy expands `previous_response_id` and lowers
+ * hosted tools into client execution, so every hazard that reaches the wire was visible here,
+ * and a hazard visible here may already have been removed. A cheap fail-closed answer beats
+ * re-parsing a multi-megabyte outbound body on every send.
+ */
+import type { OcxProviderConfig } from "../../types";
+import { resetReplayPolicyFor } from "../../providers/key-failover";
+import type { AmbiguousResendAllowance } from "../../lib/request-resend-gate";
+
+/** Input items a client owns end to end: replaying them re-runs nothing but the model. */
+const CLIENT_INPUT_ITEM_TYPES: ReadonlySet<string> = new Set([
+  "message", "reasoning", "compaction",
+  "function_call", "function_call_output",
+  "custom_tool_call", "custom_tool_call_output",
+  "tool_search_call",
+]);
+const MESSAGE_ROLES: ReadonlySet<string> = new Set(["user", "assistant", "system", "developer"]);
+/** Bounded traversal: a catalog is operator data, not a reason to walk forever. */
+const MAX_TOOL_ENTRIES = 4096;
+const MAX_TOOL_DEPTH = 4;
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * True when every tool in the catalog is executed by the client. Hosted tools (`web_search`,
+ * `mcp`, `code_interpreter`, ...) run on the origin during the turn, so an unknown or hosted
+ * type fails the whole catalog rather than being skipped: a tool this proxy does not
+ * recognise is a tool it cannot vouch for.
+ */
+function clientExecutedTools(tools: unknown, budget: { remaining: number }, depth = 0): boolean {
+  if (!Array.isArray(tools) || depth > MAX_TOOL_DEPTH) return false;
+  return tools.every(tool => {
+    budget.remaining -= 1;
+    if (budget.remaining < 0 || !record(tool)) return false;
+    if (tool.type === "function" || tool.type === "custom") return true;
+    if (tool.type === "tool_search") return tool.execution === "client";
+    return tool.type === "namespace" && typeof tool.name === "string"
+      && clientExecutedTools(tool.tools, budget, depth + 1);
+  });
+}
+
+/**
+ * A Responses body whose second send can only repeat the inference: nothing stored, no
+ * server-side continuation state, complete input, and only client-executed tools. Deferred
+ * tool declarations inside `input` are checked by the same rule as the root catalog, so a
+ * hosted tool cannot ride in through `additional_tools` or a `tool_search_output`.
+ */
+export function selfContainedResponsesBody(body: unknown): boolean {
+  if (!record(body)) return false;
+  if (body.store !== false || body.background === true) return false;
+  if (body.previous_response_id != null || body.conversation != null || Object.hasOwn(body, "stream_id")) return false;
+  const input = body.input;
+  if (typeof input !== "string" && !Array.isArray(input)) return false;
+  const budget = { remaining: MAX_TOOL_ENTRIES };
+  if (body.tools !== undefined && !clientExecutedTools(body.tools, budget)) return false;
+  if (typeof input === "string") return true;
+  return input.every(item => {
+    if (!record(item)) return false;
+    if (item.type === "additional_tools" || item.type === "tool_search_output") {
+      return clientExecutedTools(item.tools, budget);
+    }
+    if (item.type === undefined) return typeof item.role === "string" && MESSAGE_ROLES.has(item.role);
+    return typeof item.type === "string" && CLIENT_INPUT_ITEM_TYPES.has(item.type);
+  });
+}
+
+/**
+ * The allowance for ONE logical request, or nothing when the provider did not opt in.
+ *
+ * Built once per request and handed to every leg. `claim` spends the request's counter, which
+ * lives on the execution budget and is therefore shared with a combo child's derived scope --
+ * that sharing is the reason the pre-header helper takes a callback instead of a number.
+ *
+ * The body judgment is carried rather than applied here, because the gate has to be able to
+ * say WHY it refused: "the operator granted nothing" and "this request cannot be replayed" are
+ * different operator problems, and folding them together is what made the old refusal a single
+ * undifferentiated no.
+ *
+ * `selfContained` is a predicate rather than a body, and the getter below is why: a provider
+ * that never opted in must not pay to walk the input array, and the caller memoizes one answer
+ * across every leg of the request.
+ */
+export function ambiguousResendAllowanceFor(
+  provider: Pick<OcxProviderConfig, "retryOnReset">,
+  requestIsSelfContained: () => boolean,
+  claim: (limit: number) => boolean,
+): AmbiguousResendAllowance | undefined {
+  const policy = resetReplayPolicyFor(provider);
+  if (policy === null) return undefined;
+  return {
+    get selfContained(): boolean { return requestIsSelfContained(); },
+    claim: () => claim(policy.replacements),
+  };
+}
diff --git a/src/server/search.ts b/src/server/search.ts
index e66a51e24b7..51e418346e9 100644
--- a/src/server/search.ts
+++ b/src/server/search.ts
@@ -25,6 +25,9 @@ import { codexAccountNamespaceForModel } from "../codex/account-namespace-match"
 import { NATIVE_RESERVE_MODEL } from "../codex/catalog/native-models";
 import { isCodexReserveRequestEligible } from "../codex/loopback-target";
 import type { DataPlaneAdmission } from "./auth-cors";
+import {
+  admissionScopeDenial,
+} from "./admission-model-scope";
 import { formatCodexProviderForLog } from "../codex/routing";
 import { signalWithTimeout } from "../lib/abort";
 import { readBoundedResponseBytes } from "../lib/bounded-body";
@@ -87,6 +90,11 @@ export async function handleSearch(
       if (!route.codexAccountId || route.codexAccountNamespace !== accountNamespace) {
         return formatErrorResponse(400, "invalid_request_error", "Invalid Codex account-qualified search model");
       }
+      // This branch resolves a model through the router and bills the account it
+      // names, so a scoped key is held to the same destination rule it is held
+      // to on the inference path.
+      const denial = admissionScopeDenial(config, admission, model, route);
+      if (denial) return denial;
       exactAccount = { accountId: route.codexAccountId, modelId: route.modelId };
       logCtx.provider = `${route.providerName}-${accountNamespace}`;
       logCtx.routeDecision = route.routeDecision;
@@ -108,7 +116,7 @@ export async function handleSearch(
   }
   const candidates = listOpenAiForwardSidecarCandidates(config);
   if (candidates.length === 0) {
-    return handleAlphaSearchSidecarFallback(body, config, req.signal, logCtx);
+    return handleAlphaSearchSidecarFallback(body, config, req.signal, logCtx, admission);
   }
 
   let upstream: Awaited<ReturnType<typeof resolveFirstUsableOpenAiSidecar>>;
@@ -148,6 +156,22 @@ export async function handleSearch(
     throw err;
   }
 
+  if (!accountNamespace) {
+    // An unqualified search model is never routed: the caller's own string is
+    // relayed to whichever ChatGPT account this upstream resolved to, and that
+    // account is billed for it. The qualified branch above was already judged
+    // against the route it resolved, so it is not judged twice here.
+    const searchModel = typeof model === "string" && model.trim() ? model : undefined;
+    const denial = admissionScopeDenial(config, admission, searchModel, {
+      providerName: upstream.providerName,
+      modelId: searchModel,
+    });
+    if (denial) {
+      upstream.releaseProbeLease?.();
+      return denial;
+    }
+  }
+
   const headers: Record<string, string> = { "content-type": "application/json" };
   if (upstream.provider.headers) Object.assign(headers, upstream.provider.headers);
   for (const [name, value] of upstream.headers) headers[name] = value;
diff --git a/src/server/usage-ledger-retention.ts b/src/server/usage-ledger-retention.ts
new file mode 100644
index 00000000000..46b5d676f04
--- /dev/null
+++ b/src/server/usage-ledger-retention.ts
@@ -0,0 +1,73 @@
+/**
+ * Runtime owner for the opt-in usage-ledger size limit (#5063).
+ *
+ * The compactor in `src/usage/ledger-retention.ts` knows how to publish a smaller ledger safely.
+ * This is the part that decides when, and -- the half #5063 was missing -- what has to be
+ * discarded afterwards.
+ *
+ * Deleting rows from usage.jsonl invalidates three readers that do not watch the file: the
+ * 2,000-entry Logs ring, which otherwise keeps serving rows the ledger no longer has; the
+ * retained usage aggregate and failure projection, whose checkpoints now point past a boundary
+ * that moved; and the request-history index, whose source identity has changed. A compaction
+ * that skips any of them makes the dashboard disagree with the ledger, which is the disagreement
+ * this batch exists to remove.
+ */
+import { currentUsageLogRevision, setUsageLedgerAppendHook } from "../usage/log";
+import { enforceUsageLedgerSizeLimit } from "../usage/ledger-retention";
+import { discardRetainedFailureProjection } from "../usage/failure-projection-cache";
+import { rehydrateRequestLogsAfterLedgerReplacement } from "./request-log";
+import type { UsageLedgerRetentionStatus } from "../usage/retention-contract";
+
+let configuredMaxBytes: number | undefined;
+let enforcing = false;
+
+function invalidateLedgerReaders(): void {
+  // Ordered cheapest-first, and each guarded on its own: a projection that fails to discard
+  // must not stop the ring from being rebuilt, because the ring is the surface an operator is
+  // looking at while this happens.
+  try { discardRetainedFailureProjection(); } catch { /* rebuildable by construction */ }
+  void (async () => {
+    try {
+      const { discardRetainedUsageAggregate } = await import("./management/usage-aggregate-cache");
+      discardRetainedUsageAggregate();
+    } catch { /* rebuildable by construction */ }
+    try {
+      const { closeRequestHistoryIndex } = await import("../routing/history/indexer");
+      closeRequestHistoryIndex();
+    } catch { /* the index rebuilds from its own source-identity contract */ }
+  })();
+  try { rehydrateRequestLogsAfterLedgerReplacement(); } catch { /* the ring refills as rows arrive */ }
+}
+
+function enforceNow(): void {
+  // Re-entrancy guard, not a lock. The compaction itself runs inside the append call stack, and
+  // its own publication writes nothing through appendUsageEntry -- this exists so a future
+  // caller on that path cannot start a second pass over a file the first one is replacing.
+  if (enforcing) return;
+  enforcing = true;
+  try {
+    const result = enforceUsageLedgerSizeLimit(configuredMaxBytes);
+    if (result.kind === "replaced") invalidateLedgerReaders();
+  } catch (error) {
+    // Never fail a request because history could not be trimmed. The limit is not enforced and
+    // says so; the next append tries again from a fresh revision.
+    console.warn(
+      `[usage-retention] could not enforce the usage ledger size limit: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  } finally {
+    enforcing = false;
+  }
+}
+
+/** Install or update the policy. `undefined` removes the hook entirely. */
+export function setUsageLedgerRetention(maxBytes: number | undefined): void {
+  configuredMaxBytes = maxBytes;
+  setUsageLedgerAppendHook(maxBytes === undefined ? null : enforceNow);
+}
+
+export function usageLedgerRetentionStatus(): UsageLedgerRetentionStatus {
+  return {
+    ...(configuredMaxBytes !== undefined ? { maxBytes: configuredMaxBytes } : {}),
+    currentBytes: currentUsageLogRevision()?.size ?? 0,
+  };
+}
diff --git a/src/service.ts b/src/service.ts
index 149b1ae02c7..79cfff6efda 100644
--- a/src/service.ts
+++ b/src/service.ts
@@ -6,8 +6,12 @@
  * restore it via the command.
  */
 
-export type { ServiceBackend, ServiceInstallState, ServiceStateEvidence } from "./service/state";
-export { SERVICE_MANAGED_ENV, stableLauncherEntry, serviceLogPath, serviceStatePathsForOpenCodexHome, parseServiceInstallState, inspectServiceStateEvidence, currentServiceHomes, serviceHomeMatches, readServiceBackend, serviceReinstallArgs, serviceInstallArgs } from "./service/state";
+export type { ServiceBackend, ServiceInstallState, ServiceStateEvidence, ServiceStateResolution, ServiceOwner, ServiceOwnership, ServiceOwnershipSubject, ServiceOwnershipResolution, ServiceStateSwapDeps, RecordServiceOwnerRequest, RecordServiceOwnerDeps, ReleaseServiceOwnerDeps, RemoveServiceStateDeps } from "./service/state";
+export { SERVICE_MANAGED_ENV, SERVICE_OWNERSHIP_PROTOCOL_VERSION, SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION, stableLauncherEntry, serviceLogPath, serviceStatePaths, serviceStatePathsForOpenCodexHome, parseServiceInstallState, parseServiceOwnership, inspectServiceStateEvidence, resolveServiceState, currentServiceHomes, serviceHomeMatches, readServiceBackend, serviceReinstallArgs, serviceInstallArgs, ServiceStateConflictError, ServiceOwnershipSubjectMismatchError, ServiceOwnershipSubjectUnknownError, ServiceTakeoverCompatibilityChangedError, swapServiceInstallState, removeServiceInstallStateRecords, serviceOwnership, resolveServiceOwnership, sameServiceOwnershipSubject, desktopOwnsService, ownershipGrantedTo, recordServiceOwner, releaseServiceOwner } from "./service/state";
+export type { OwnershipMutationLeaseOptions, OwnershipMutationLease } from "./service/ownership-mutation-lease.mjs";
+export { acquireOwnershipMutationLease, withOwnershipMutationLease } from "./service/ownership-mutation-lease.mjs";
+export type { ManagingCliRole, ManagingCliObservation, RegisteredManagingCliInvocation, ServiceTakeoverCompatibilityInput, ServiceTakeoverCompatibility } from "./service/ownership-compatibility";
+export { registeredManagingCliInvocation, assessServiceTakeoverCompatibility, sameServiceTakeoverCompatibility } from "./service/ownership-compatibility";
 export type { ServiceApiTokenOrigin, ProvisionedServiceApiToken } from "./service/guards";
 export { ServiceOwnershipError, isServiceOwnershipError, serviceEnvironmentOwnedHere, assertServiceEnvironmentMatchesInstall, serviceRetryCommand, assertNotAdminToken, assertServiceAuthEnvironment, writeServiceApiTokenFile, assertLiveServiceManagerAllowed } from "./service/guards";
 export { resolveServiceListenPort, installedServiceListenPort, SERVICE_INSTALL_HEALTH_MS, SERVICE_INSTALL_HEALTH_WINDOWS_MS, serviceInstallHealthMs, confirmServiceServing, reportServiceServing, resolvedProxyEnv } from "./service/health";
@@ -21,7 +25,7 @@ export { buildWindowsServiceScript, buildWindowsSchtasksCreateArgs, buildWindows
 export type { WindowsSchedulerRegistrationStageDeps, FreshWindowsSchedulerRegistrationDeps, RemoveNativeWindowsServiceDeps } from "./service/windows-ops";
 export { windowsListenPort, winswListenPort, writeServiceDefinitionFile, definitionCarriesCredential, stageWindowsSchedulerRegistrationXml, stageElevatedSchedulerRegistration, describeElevatedRegistrationFailure, registerFreshWindowsSchedulerTask, removeNativeWindowsServiceForScheduler, assertWindowsNativeServiceAccountSupported, isWindowsSchedulerEndBenign, stopWindows, stopWindowsChecked, classifyWindowsServiceStop } from "./service/windows-ops";
 export type { ServiceRepairVerb, RepairServiceDeps } from "./service/repair";
-export { repairService } from "./service/repair";
+export { repairService, foreignServiceOwnerRefusal, unknownServiceOwnerRefusal } from "./service/repair";
 export type { ServiceInstallPreparationDeps, FreshWindowsSchedulerInstallDeps, ServiceStopOutcome, ServiceUninstallOutcome } from "./service/orchestration";
 export { proxyStillLiveAfterStop, prepareServiceInstall, installServiceSafely, installFreshWindowsSchedulerSafely, installedServiceRespawnRisk, stopServiceIfInstalledDetailed, setUninstallServiceHooksForTests, uninstallServiceDetailed, uninstallServiceIfInstalled, isServiceInstalled, isServiceViable } from "./service/orchestration";
 export type { ServiceDiagnostic, WindowsTaskDiagnosticIdentityDeps, WindowsServiceDiagnosticInputs, LaunchdServiceDiagnosticInputs } from "./service/diagnostics";
diff --git a/src/service/cli.ts b/src/service/cli.ts
index 86f99a0be32..1322b9948b4 100644
--- a/src/service/cli.ts
+++ b/src/service/cli.ts
@@ -13,7 +13,8 @@ import { resolveServiceListenPort, reportServiceServing } from "./health";
 import { platformOps, proxyStillLiveAfterStop, stopTrackedProxyForServiceCommand, installServiceSafely, installFreshWindowsSchedulerSafely, removeServiceInstallState, isServiceInstalled } from "./orchestration";
 import { repairService } from "./repair";
 import type { ServiceRepairVerb } from "./repair";
-import { TASK, plistPath, readServiceBackend } from "./state";
+import { TASK, plistPath, readServiceBackend, releaseServiceOwner, resolveServiceOwnership } from "./state";
+import { foreignServiceOwnerRefusal, unknownServiceOwnerRefusal } from "./repair";
 import type { ServiceBackend } from "./state";
 import { unitPath } from "./systemd";
 import { inspectWindowsSchedulerServiceStatus, schtasksErrorDetail, probeWindowsSchedulerTask } from "./windows-scheduler";
@@ -233,6 +234,15 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     case "install":
       assertServiceEnvironmentMatchesInstall();
       assertServiceAuthEnvironment();
+      // The install may advance provenance, but it may take back only the owner it observed
+      // before touching the registration. A desktop successor that claims ownership while
+      // the install is running must survive the late release below.
+      const ownershipBeforeInstall = resolveServiceOwnership();
+      if (ownershipBeforeInstall.kind === "unknown") {
+        console.error(`❌ ${unknownServiceOwnerRefusal(ownershipBeforeInstall.reason, "install")}`);
+        process.exitCode = 1;
+        break;
+      }
       // A manually started proxy can still own the configured port while the service
       // registration is absent or unloaded. Stop both the registered manager and any
       // tracked standalone listener before loading the freshly written service assets.
@@ -258,6 +268,23 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
         process.exitCode = 1;
         break;
       }
+      // ONLY now. `install` is the verb that takes the runtime back, and it does so after the
+      // registration exists — releasing first meant a cancelled UAC prompt, a failed
+      // registration or an aborted cleanup left the retained npm registration looking
+      // CLI-owned, so the next incidental repair would reactivate it.
+      //
+      // `repair` and `restart` refuse under a foreign owner precisely because they run
+      // incidentally — from a tray helper, from `ocx update`, from a doctor suggestion — and
+      // undoing a takeover the user consented to must be something the user asked for.
+      {
+        const released = releaseServiceOwner(ownershipBeforeInstall, { allowRevisionAdvance: true });
+        if (released) {
+          console.log(
+            `ℹ️  The desktop app owned the background runtime (install ${released.installId}, `
+            + `consent generation ${released.consentGeneration}); this install took it back.`,
+          );
+        }
+      }
       // The wrapper was written moments ago in this process, so the configured port
       // and the baked one cannot have diverged yet — unlike `start`, which reads the
       // installed artifact instead.
@@ -269,15 +296,34 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       // Same one-time marker and same guards (TTY, gh auth, agent deferral) apply.
       await maybeShowStarPrompt();
       break;
-    case "start":
+    case "start": {
       // The installed launcher preserves the recorded CODEX_SQLITE_HOME: a
       // changed sqlite_home/CODEX_SQLITE_HOME/CODEX_HOME would start the service
       // on the recorded database while this shell resolves another, splitting
       // native Codex history between databases. Same guard `stop` already runs.
       assertServiceEnvironmentMatchesInstall();
+      // `start` activates the npm registration, so it refuses on the same terms repair does.
+      // The Windows tray starts the service automatically, which would otherwise put a second
+      // proxy beside the one the desktop app is running without anyone asking for it.
+      // `stop` and `uninstall` are deliberately NOT gated: they deactivate.
+      //
+      // Reported rather than thrown: the tray drives this through `runTrayProxyStart`, which
+      // does not catch, and a refusal is a decision rather than a crash.
+      const ownership = resolveServiceOwnership();
+      const refusal = ownership.kind === "unknown"
+        ? unknownServiceOwnerRefusal(ownership.reason, "start")
+        : ownership.kind === "owned" && ownership.ownership.owner !== "cli"
+          ? foreignServiceOwnerRefusal(ownership.ownership, "start")
+          : null;
+      if (refusal) {
+        console.error(`❌ ${refusal}`);
+        process.exitCode = 1;
+        break;
+      }
       ops.start();
       await reportServiceServing("started");
       break;
+    }
     case "stop": {
       assertServiceEnvironmentMatchesInstall();
       // Only stop what is actually installed. The unguarded call ran a real `launchctl unload`
diff --git a/src/service/health.ts b/src/service/health.ts
index 0306ab536d4..d04c83ef3ff 100644
--- a/src/service/health.ts
+++ b/src/service/health.ts
@@ -32,9 +32,10 @@ export function resolveServiceListenPort(override?: number): number {
   return 10100;
 }
 
-export function buildServiceShellCommand(bun: string, cli: string, port = resolveServiceListenPort()): string {
+export function buildServiceShellCommand(bun: string, cli: string | null, port = resolveServiceListenPort()): string {
   const tokenFile = serviceApiTokenFilePath();
-  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${shellQuote(cli)} start --port ${port}`;
+  const args = cli ? `${shellQuote(cli)} start` : "start";
+  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${args} --port ${port}`;
 }
 
 /**
diff --git a/src/service/install-state-contract.d.mts b/src/service/install-state-contract.d.mts
new file mode 100644
index 00000000000..5dc5412ce32
--- /dev/null
+++ b/src/service/install-state-contract.d.mts
@@ -0,0 +1,27 @@
+export type {
+  AuthoritativeServiceStateRecord,
+  ServiceInstallStateRecord,
+  ServiceOwnershipRecord as OwnershipClaim,
+  ServiceStateRecordEvidence as InstallStateEvidence,
+} from "./state-record.mjs";
+
+export {
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+} from "./state-record.mjs";
+
+import type { ServiceStateRecordEvidence } from "./state-record.mjs";
+
+export type OwnershipResolution =
+  | { readonly kind: "none"; readonly revision: number; readonly needsRepair?: boolean }
+  | { readonly kind: "owned"; readonly ownership: { owner: string; installId: string; consentGeneration: number }; readonly revision: number }
+  | { readonly kind: "unknown"; readonly reason: string };
+
+export declare const SERVICE_STATE_FILE: "service-state.json";
+export declare function parseOwnershipClaim(value: unknown): import("./state-record.mjs").ServiceOwnershipRecord | null;
+export declare function parseInstallStateRecord(value: unknown): import("./state-record.mjs").ServiceInstallStateRecord | null;
+export declare function inspectInstallStateBytes(path: string, read: (path: string) => string): ServiceStateRecordEvidence;
+export declare function resolveOwnershipFromEvidence(evidence: readonly ServiceStateRecordEvidence[]): OwnershipResolution;
+export declare function serviceStateFilesFor(opencodexHomeDir: string, defaultHomeDir: string, platform?: NodeJS.Platform): string[];
diff --git a/src/service/install-state-contract.mjs b/src/service/install-state-contract.mjs
new file mode 100644
index 00000000000..b9baafa6186
--- /dev/null
+++ b/src/service/install-state-contract.mjs
@@ -0,0 +1,34 @@
+/** Compatibility surface for the shared install-state contract landed before C2 hardening. */
+import {
+  inspectServiceStateRecords,
+  parseServiceInstallStateRecord,
+  parseServiceOwnershipRecord,
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+  serviceStatePathsForHomes,
+} from "./state-record.mjs";
+
+export const SERVICE_STATE_FILE = "service-state.json";
+export const parseOwnershipClaim = parseServiceOwnershipRecord;
+export const parseInstallStateRecord = parseServiceInstallStateRecord;
+export const serviceStateFilesFor = serviceStatePathsForHomes;
+export {
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+};
+
+export function inspectInstallStateBytes(path, read) {
+  return inspectServiceStateRecords([path], read)[0];
+}
+
+export function resolveOwnershipFromEvidence(evidence) {
+  const selected = selectAuthoritativeServiceState(evidence);
+  if (selected.kind === "unknown" || selected.kind === "none") return selected;
+  return selected.state.ownership
+    ? { kind: "owned", ownership: selected.state.ownership, revision: selected.revision }
+    : { kind: "none", revision: selected.revision };
+}
diff --git a/src/service/launchd.ts b/src/service/launchd.ts
index 613c40ea530..d561d01a294 100644
--- a/src/service/launchd.ts
+++ b/src/service/launchd.ts
@@ -160,7 +160,7 @@ function launchdServiceCommand(
  */
 export function expectedLaunchdCommand(
   port: number,
-  deps: { state?: ServiceInstallState | null; entry?: { bun: string; cli: string } } = {},
+  deps: { state?: ServiceInstallState | null; entry?: { bun: string; cli: string | null } } = {},
 ): string {
   const state = deps.state === undefined ? readServiceInstallState() : deps.state;
   if (state?.launcherPath) return buildServiceLauncherShellCommand(state.launcherPath, port);
diff --git a/src/service/orchestration.ts b/src/service/orchestration.ts
index 9a40ba2479e..92f374b3c34 100644
--- a/src/service/orchestration.ts
+++ b/src/service/orchestration.ts
@@ -11,7 +11,7 @@ import type { ServiceDiagnostic } from "./diagnostics";
 import { assertServiceEnvironmentMatchesInstall } from "./guards";
 import { runLaunchctl, launchdEvictionTargets, launchctlBootoutBenign, probeLaunchdLoadState, installLaunchd, startLaunchd, stopLaunchd, statusLaunchd, uninstallLaunchd } from "./launchd";
 import { assertSchedulerRegistrationBeforeStart } from "./repair";
-import { SERVICE_MANAGED_ENV, TASK, plistPath, serviceStatePaths, writeServiceInstallState } from "./state";
+import { SERVICE_MANAGED_ENV, TASK, plistPath, removeServiceInstallStateRecords, writeServiceInstallState } from "./state";
 import type { ServiceBackend } from "./state";
 import { unitPath, isSystemd, installSystemd, startSystemd, stopSystemd, statusSystemd, uninstallSystemd, systemdServiceInstallCleanupOps } from "./systemd";
 import { writeWindowsSchedulerAssets, stageWindowsSchedulerRegistrationXml, removeWindowsSchedulerRegistrationStage, registerFreshWindowsSchedulerTask, recordWindowsSchedulerOwnership, removeNativeWindowsServiceForScheduler, installWindows, installWindowsNative, startWindows, isWindowsSchedulerEndBenign, stopWindows, stopWindowsChecked, statusWindows, statusWindowsXml, killWindowsServiceWrapperProcesses, uninstallWindows, classifyWindowsServiceStop } from "./windows-ops";
@@ -527,9 +527,7 @@ export function stopServiceIfInstalledDetailed(): ServiceStopOutcome {
 
 /** Delete install-state files; stale state would make `ocx update` "reinstall" a service that no longer exists. */
 export function removeServiceInstallState(): void {
-  for (const path of serviceStatePaths()) {
-    try { if (existsSync(path)) unlinkSync(path); } catch { /* best-effort */ }
-  }
+  removeServiceInstallStateRecords();
 }
 
 type UninstallServiceHooksForTests = {
diff --git a/src/service/ownership-compatibility.ts b/src/service/ownership-compatibility.ts
new file mode 100644
index 00000000000..fe089e44758
--- /dev/null
+++ b/src/service/ownership-compatibility.ts
@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { parseStrictSemver } from "../lib/strict-semver";
+import type {
+  ServiceInstallState,
+  ServiceOwnershipSubject,
+} from "./state";
+import {
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+} from "./install-state-contract.mjs";
+
+export type ManagingCliRole = "service-registration" | "path";
+
+export type ManagingCliObservation =
+  | { readonly status: "absent" }
+  | { readonly status: "unknown"; readonly reason: string }
+  | { readonly status: "observed"; readonly version: string; readonly identity: string };
+
+export type RegisteredManagingCliInvocation =
+  | { readonly status: "absent" }
+  | { readonly status: "unknown"; readonly reason: string }
+  | { readonly status: "resolved"; readonly executable: string; readonly args: readonly string[] };
+
+/** Resolve the exact command baked into the preserved service registration. */
+export function registeredManagingCliInvocation(
+  state: ServiceInstallState | null,
+): RegisteredManagingCliInvocation {
+  if (!state) return { status: "absent" };
+  if (state.launcherPath) {
+    return isAbsolute(state.launcherPath)
+      ? { status: "resolved", executable: state.launcherPath, args: [] }
+      : { status: "unknown", reason: "the recorded service launcher is not absolute" };
+  }
+  if (!state.bunPath || !isAbsolute(state.bunPath)) {
+    return { status: "unknown", reason: "the registered service executable is missing or not absolute" };
+  }
+  if (state.cliPath === null) return { status: "resolved", executable: state.bunPath, args: [] };
+  if (typeof state.cliPath === "string" && isAbsolute(state.cliPath)) {
+    return { status: "resolved", executable: state.bunPath, args: [state.cliPath] };
+  }
+  return { status: "unknown", reason: "the registered service CLI path is missing or not absolute" };
+}
+
+export interface ServiceTakeoverCompatibilityInput {
+  readonly state: ServiceInstallState | null;
+  readonly subject: ServiceOwnershipSubject;
+  readonly managers: Readonly<Record<ManagingCliRole, ManagingCliObservation>>;
+}
+
+export type ServiceTakeoverCompatibility =
+  | {
+      readonly kind: "supported";
+      readonly protocolVersion: typeof SERVICE_OWNERSHIP_PROTOCOL_VERSION;
+      readonly minimumCliVersion: typeof SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION;
+      /** Opaque binding over the approved subject and both managing-CLI observations. */
+      readonly token: string;
+    }
+  | {
+      readonly kind: "blocked";
+      readonly reason:
+        | "managing-cli-unknown"
+        | "managing-cli-unsupported"
+        | "managing-cli-unobserved"
+        | "service-protocol-unsupported";
+      readonly detail: string;
+      readonly minimumCliVersion: typeof SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION;
+    };
+
+function comparePrerelease(left: readonly (bigint | string)[], right: readonly (bigint | string)[]): number {
+  if (left.length === 0 || right.length === 0) return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const a = left[index];
+    const b = right[index];
+    if (a === undefined || b === undefined) return a === b ? 0 : a === undefined ? -1 : 1;
+    if (a === b) continue;
+    if (typeof a === "bigint" && typeof b === "bigint") return a < b ? -1 : 1;
+    if (typeof a === "bigint") return -1;
+    if (typeof b === "bigint") return 1;
+    return a < b ? -1 : 1;
+  }
+  return 0;
+}
+
+function versionSupportsOwnership(value: string): boolean {
+  const actual = parseStrictSemver(value);
+  const minimum = parseStrictSemver(SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION);
+  if (!actual || !minimum) return false;
+  for (let index = 0; index < actual.core.length; index += 1) {
+    if (actual.core[index] !== minimum.core[index]) return actual.core[index]! > minimum.core[index]!;
+  }
+  return comparePrerelease(actual.prerelease, minimum.prerelease) >= 0;
+}
+
+function compatibilityToken(input: ServiceTakeoverCompatibilityInput): string {
+  return createHash("sha256").update(JSON.stringify({
+    subject: input.subject,
+    protocolVersion: input.state?.ownershipProtocolVersion ?? null,
+    managers: {
+      "service-registration": input.managers["service-registration"],
+      path: input.managers.path,
+    },
+  })).digest("hex");
+}
+
+/**
+ * Decide whether permanent desktop ownership can be offered.
+ *
+ * Both managing surfaces are mandatory observations. `absent` is a trustworthy answer;
+ * `unknown` is not. An observed service registration additionally needs the protocol marker
+ * written by a CLI whose start/repair/update paths honor the ownership claim. This is what
+ * keeps the preserved registration from starting an older runtime at the next login.
+ */
+export function assessServiceTakeoverCompatibility(
+  input: ServiceTakeoverCompatibilityInput,
+): ServiceTakeoverCompatibility {
+  const observed = Object.entries(input.managers) as Array<[ManagingCliRole, ManagingCliObservation]>;
+  const unknown = observed.find(([, manager]) => manager.status === "unknown");
+  if (unknown) return {
+    kind: "blocked",
+    reason: "managing-cli-unknown",
+    detail: `${unknown[0]} compatibility could not be determined`,
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  };
+  const present = observed.filter(([, manager]) => manager.status === "observed") as Array<[
+    ManagingCliRole,
+    Extract<ManagingCliObservation, { status: "observed" }>,
+  ]>;
+  if (present.length === 0) return {
+    kind: "blocked",
+    reason: "managing-cli-unobserved",
+    detail: "no managing OpenCodex CLI installation was observed",
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  };
+  const unsupported = present.find(([, manager]) => !versionSupportsOwnership(manager.version));
+  if (unsupported) return {
+    kind: "blocked",
+    reason: "managing-cli-unsupported",
+    detail: `${unsupported[0]} uses OpenCodex ${unsupported[1].version}; ${SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION} or later is required`,
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  };
+  if (input.managers["service-registration"].status === "observed"
+    && input.state?.ownershipProtocolVersion !== SERVICE_OWNERSHIP_PROTOCOL_VERSION) {
+    return {
+      kind: "blocked",
+      reason: "service-protocol-unsupported",
+      detail: "the preserved service registration was not written by an ownership-aware CLI",
+      minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+    };
+  }
+  return {
+    kind: "supported",
+    protocolVersion: SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+    token: compatibilityToken(input),
+  };
+}
+
+export function sameServiceTakeoverCompatibility(
+  left: ServiceTakeoverCompatibility,
+  right: ServiceTakeoverCompatibility,
+): boolean {
+  return left.kind === "supported" && right.kind === "supported" && left.token === right.token;
+}
diff --git a/src/service/ownership-mutation-lease.d.mts b/src/service/ownership-mutation-lease.d.mts
new file mode 100644
index 00000000000..48d293263cd
--- /dev/null
+++ b/src/service/ownership-mutation-lease.d.mts
@@ -0,0 +1,32 @@
+export interface OwnershipMutationLeaseOptions {
+  readonly waitMs?: number;
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => void;
+  readonly processAlive?: (pid: number) => boolean;
+  readonly beforeRelease?: (lockPath: string) => void;
+  readonly joinToken?: string;
+}
+
+export interface OwnershipMutationLease { readonly token: string; release(): void }
+
+export declare const OWNERSHIP_MUTATION_LEASE_TOKEN_ENV: "OCX_OWNERSHIP_MUTATION_LEASE_TOKEN";
+
+export declare function ownershipMutationLeaseChildEnvironment(
+  environment: NodeJS.ProcessEnv,
+  token: string,
+): NodeJS.ProcessEnv;
+
+export declare function unprivilegedOwnershipMutationEnvironment(
+  environment: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv;
+
+export declare function acquireOwnershipMutationLease(
+  statePaths: readonly string[],
+  options?: OwnershipMutationLeaseOptions,
+): OwnershipMutationLease;
+
+export declare function withOwnershipMutationLease<T>(
+  statePaths: readonly string[],
+  run: () => T,
+  options?: OwnershipMutationLeaseOptions,
+): T;
diff --git a/src/service/ownership-mutation-lease.mjs b/src/service/ownership-mutation-lease.mjs
new file mode 100644
index 00000000000..008d4e14f27
--- /dev/null
+++ b/src/service/ownership-mutation-lease.mjs
@@ -0,0 +1,211 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const WAIT_MS = 2_000;
+const POLL_MS = 20;
+const STALE_MS = 30_000;
+const PROCESS_INSTANCE = randomUUID();
+const held = new Map();
+const delegatedTokens = new Map();
+const sleeper = new Int32Array(new SharedArrayBuffer(4));
+export const OWNERSHIP_MUTATION_LEASE_TOKEN_ENV = "OCX_OWNERSHIP_MUTATION_LEASE_TOKEN";
+
+export function ownershipMutationLeaseChildEnvironment(environment, token) {
+  return { ...environment, [OWNERSHIP_MUTATION_LEASE_TOKEN_ENV]: token };
+}
+
+export function unprivilegedOwnershipMutationEnvironment(environment) {
+  const child = { ...environment };
+  delete child[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+  return child;
+}
+
+function sleep(ms) { Atomics.wait(sleeper, 0, 0, ms); }
+function processAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code !== "ESRCH"; }
+}
+
+function leasePath(statePaths) {
+  const authority = statePaths.at(-1);
+  if (!authority) throw new Error("cannot acquire ownership mutation lease without a service-state path");
+  try { return `${realpathSync.native(authority)}.mutation.lock`; }
+  catch {
+    try { return join(realpathSync.native(dirname(authority)), `${basename(authority)}.mutation.lock`); }
+    catch { return `${authority}.mutation.lock`; }
+  }
+}
+
+function ownerName(record) {
+  return `v1-${record.pid}-${record.processInstance}-${record.token}.json`;
+}
+
+function parseOwnerName(name) {
+  const match = /^v1-([1-9][0-9]*)-[0-9a-f-]+-[0-9a-f-]+[.]json$/i.exec(name);
+  if (!match) return null;
+  const pid = Number(match[1]);
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+
+function readOwner(path) {
+  try {
+    const lock = lstatSync(path);
+    if (!lock.isDirectory()) return null;
+    const entries = readdirSync(path);
+    if (entries.length !== 1) return null;
+    const ownerPath = join(path, entries[0]);
+    const owner = lstatSync(ownerPath);
+    if (!owner.isFile() || owner.size > 4096) return null;
+    const record = JSON.parse(readFileSync(ownerPath, "utf8"));
+    if (record?.version !== 1 || !Number.isSafeInteger(record.pid) || record.pid <= 0
+      || typeof record.processInstance !== "string" || !record.processInstance
+      || typeof record.token !== "string" || !record.token
+      || !Number.isFinite(record.createdAt) || entries[0] !== ownerName(record)) return null;
+    const currentLock = lstatSync(path);
+    const currentOwner = lstatSync(ownerPath);
+    if (currentLock.dev !== lock.dev || currentLock.ino !== lock.ino
+      || currentOwner.dev !== owner.dev || currentOwner.ino !== owner.ino
+      || currentOwner.size !== owner.size) return null;
+    return { path, ownerPath, record, lockDev: lock.dev, lockIno: lock.ino, ownerDev: owner.dev, ownerIno: owner.ino, ownerSize: owner.size, mtimeMs: owner.mtimeMs };
+  } catch { return null; }
+}
+
+function sameOwner(left, right) {
+  return left.record.token === right.record.token
+    && left.record.pid === right.record.pid
+    && left.record.processInstance === right.record.processInstance
+    && left.lockDev === right.lockDev && left.lockIno === right.lockIno
+    && left.ownerDev === right.ownerDev && left.ownerIno === right.ownerIno
+    && left.ownerSize === right.ownerSize;
+}
+
+function readIncompleteOwner(path) {
+  try {
+    const lock = lstatSync(path);
+    if (!lock.isDirectory()) return null;
+    const entries = readdirSync(path);
+    if (entries.length === 0) return { path, ownerPath: null, pid: null, mtimeMs: lock.mtimeMs };
+    if (entries.length !== 1) return null;
+    const pid = parseOwnerName(entries[0]);
+    if (!pid) return null;
+    const ownerPath = join(path, entries[0]);
+    const owner = lstatSync(ownerPath);
+    return owner.isFile() ? { path, ownerPath, pid, mtimeMs: owner.mtimeMs } : null;
+  } catch { return null; }
+}
+
+function reclaim(path, now, alive) {
+  const observed = readOwner(path);
+  const incomplete = observed ? null : readIncompleteOwner(path);
+  if (!observed && !incomplete) return false;
+  const createdAt = observed ? Math.max(observed.record.createdAt, observed.mtimeMs) : incomplete.mtimeMs;
+  const pid = observed?.record.pid ?? incomplete.pid;
+  if (now() - createdAt <= STALE_MS || (pid !== null && alive(pid))) return false;
+  if (observed) {
+    const current = readOwner(path);
+    if (!current || !sameOwner(observed, current)) return false;
+  }
+  try {
+    const ownerPath = observed?.ownerPath ?? incomplete.ownerPath;
+    if (ownerPath) unlinkSync(ownerPath);
+    rmdirSync(path);
+    return true;
+  } catch { return false; }
+}
+
+export function acquireOwnershipMutationLease(
+  statePaths,
+  options = {},
+) {
+  const path = leasePath(statePaths);
+  const nested = held.get(path);
+  if (nested) {
+    nested.depth += 1;
+    return { token: nested.snapshot.record.token, release: () => release(path, options) };
+  }
+  const now = options.now ?? Date.now;
+  const alive = options.processAlive ?? processAlive;
+  const explicitJoinToken = options.joinToken;
+  const envJoinToken = process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+  const joinToken = explicitJoinToken ?? envJoinToken ?? delegatedTokens.get(path);
+  if (joinToken) {
+    const owner = readOwner(path);
+    if (owner?.record.token === joinToken && alive(owner.record.pid)) {
+      delegatedTokens.set(path, joinToken);
+      if (envJoinToken === joinToken) delete process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+      held.set(path, { depth: 1, snapshot: owner, delegated: true });
+      return { token: joinToken, release: () => release(path, options) };
+    }
+    delegatedTokens.delete(path);
+    if (envJoinToken === joinToken) delete process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+    if (explicitJoinToken) throw new Error("ownership mutation lease delegation is invalid or no longer live");
+  }
+  const wait = options.waitMs ?? WAIT_MS;
+  const deadline = now() + wait;
+  if (!existsSync(dirname(path))) mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  for (;;) {
+    const record = { version: 1, pid: process.pid, processInstance: PROCESS_INSTANCE, token: randomUUID(), createdAt: now() };
+    const ownerPath = join(path, ownerName(record));
+    let madeDirectory = false;
+    let descriptor = null;
+    try {
+      mkdirSync(path, { mode: 0o700 });
+      madeDirectory = true;
+      descriptor = openSync(ownerPath, "wx", 0o600);
+      writeFileSync(descriptor, `${JSON.stringify(record)}\n`, "utf8");
+      fsyncSync(descriptor);
+      closeSync(descriptor);
+      descriptor = null;
+      const snapshot = readOwner(path);
+      if (!snapshot || snapshot.record.token !== record.token) throw new Error("ownership mutation lease could not be verified");
+      held.set(path, { depth: 1, snapshot, delegated: false });
+      return { token: record.token, release: () => release(path, options) };
+    } catch (error) {
+      if (descriptor !== null) { try { closeSync(descriptor); } catch { /* stale recovery owns uncertain cleanup */ } }
+      if (madeDirectory) {
+        try { unlinkSync(ownerPath); } catch { /* partial owner is recovered after dead-PID proof */ }
+        try { rmdirSync(path); } catch { /* owner entry or successor keeps the directory live */ }
+      }
+      if (error?.code !== "EEXIST") throw error;
+      if (reclaim(path, now, alive)) continue;
+      if (now() >= deadline) throw new Error(`another process owns the runtime mutation lease at ${path}`);
+      (options.sleep ?? sleep)(POLL_MS);
+    }
+  }
+}
+
+function release(path, options) {
+  const currentHeld = held.get(path);
+  if (!currentHeld) return;
+  currentHeld.depth -= 1;
+  if (currentHeld.depth > 0) return;
+  held.delete(path);
+  if (currentHeld.delegated) return;
+  options.beforeRelease?.(path);
+  try {
+    const current = readOwner(path);
+    if (!current || !sameOwner(currentHeld.snapshot, current)) return;
+    unlinkSync(currentHeld.snapshot.ownerPath);
+    rmdirSync(path);
+  } catch { /* token-specific stale recovery handles an uncertain release */ }
+}
+
+export function withOwnershipMutationLease(statePaths, run, options = {}) {
+  const lease = acquireOwnershipMutationLease(statePaths, options);
+  try { return run(); }
+  finally { lease.release(); }
+}
diff --git a/src/service/repair.ts b/src/service/repair.ts
index 8b729f03e6d..34937498238 100644
--- a/src/service/repair.ts
+++ b/src/service/repair.ts
@@ -5,7 +5,8 @@ import type { ServiceDiagnostic } from "./diagnostics";
 import { assertServiceEnvironmentMatchesInstall, assertServiceAuthEnvironment } from "./guards";
 import { installLaunchd, restartLaunchdJob } from "./launchd";
 import type { LaunchdInstallOutcome } from "./launchd";
-import { TASK, writeServiceInstallState, serviceSourceDir } from "./state";
+import { TASK, writeServiceInstallState, serviceSourceDir, resolveServiceOwnership } from "./state";
+import type { ServiceOwnership, ServiceOwnershipResolution } from "./state";
 import { installSystemd } from "./systemd";
 import { writeWindowsSchedulerAssets, reregisterWindowsSchedulerTask, windowsSchedulerRegistrationMatchesSnapshot, restoreWindowsSchedulerTaskIfAbsent, startWindows, stopWindows, statusWindowsXml } from "./windows-ops";
 import { probeWindowsSchedulerTask, SCHEDULER_SETTLE_DELAYS_MS, settleDelay } from "./windows-scheduler";
@@ -35,6 +36,8 @@ export interface RepairServiceDeps {
   repairSystemd?: () => void;
   /** Restarts a launchd job the install path deliberately left alone. `restart` only. */
   restartLaunchd?: () => void;
+  /** Resolves the recorded runtime owner across every state path. */
+  readOwnership?: () => ServiceOwnershipResolution;
   /**
    * Which CLI verb is being served. `repair` must leave a healthy service alone — that no-op
    * IS the #4236 fix — while `restart` promises a new process, so on darwin it kicks the job
@@ -61,6 +64,37 @@ export interface RepairServiceDeps {
   platform?: NodeJS.Platform;
 }
 
+/**
+ * Why a repair stops when something other than this CLI owns the runtime.
+ *
+ * The npm service registration is KEPT — the maintainer's decision is that a user's install
+ * is never deleted — so the recorded owner is the only thing standing between a takeover the
+ * user consented to and the next `ocx service repair`, which would re-enable and restart the
+ * npm launcher without mentioning it. Repair runs incidentally: a tray helper, `ocx update`,
+ * a doctor suggestion. `install` is the deliberate act, so `install` is the verb that takes
+ * ownership back.
+ */
+export function foreignServiceOwnerRefusal(ownership: ServiceOwnership, action = "repair"): string {
+  return `Background service ${action} stopped: the desktop app owns the runtime `
+    + `(install ${ownership.installId}, consent generation ${ownership.consentGeneration}).\n`
+    + "The service registration was left exactly as it is — not re-enabled, not rewritten and not restarted.\n"
+    + "Quit the desktop app and run 'ocx service install' to hand the runtime back to this CLI.";
+}
+
+/**
+ * Why an unreadable or contradictory record stops a repair too.
+ *
+ * Collapsing "I could not read the claim" into "there is no claim" is how a consented
+ * takeover gets reactivated by a permissions error. `ocx service install` is deliberately
+ * not gated, so this never leaves an operator without a way forward.
+ */
+export function unknownServiceOwnerRefusal(reason: string, action = "repair"): string {
+  return `Background service ${action} stopped: ${reason}, so the runtime's recorded owner could `
+    + "not be determined.\n"
+    + "The service registration was left exactly as it is — not re-enabled, not rewritten and not restarted.\n"
+    + "Repair the service-state file or its permissions, then run 'ocx service install' to take the runtime back.";
+}
+
 async function assertSchedulerSnapshotBeforeStart(
   readSchedulerXml: () => string,
   expectedXml: string,
@@ -128,6 +162,16 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
     throw new Error("Background service is not installed. Run 'ocx service install' first.");
   }
 
+  // Before anything is asserted, written, stopped or started. A repair that has already
+  // rewritten the assets has changed the thing it was supposed to leave alone.
+  const ownership = (deps.readOwnership ?? resolveServiceOwnership)();
+  if (ownership.kind === "unknown") throw new Error(unknownServiceOwnerRefusal(ownership.reason));
+  // `!== "cli"` rather than `=== "desktop"`: this is the CLI's own repair path, so any owner
+  // that is not this CLI is one whose runtime it must not touch.
+  if (ownership.kind === "owned" && ownership.ownership.owner !== "cli") {
+    throw new Error(foreignServiceOwnerRefusal(ownership.ownership));
+  }
+
   (deps.assertEnv ?? assertServiceEnvironmentMatchesInstall)();
   (deps.assertAuth ?? assertServiceAuthEnvironment)();
 
diff --git a/src/service/state-lock.ts b/src/service/state-lock.ts
new file mode 100644
index 00000000000..6bc2fabfb92
--- /dev/null
+++ b/src/service/state-lock.ts
@@ -0,0 +1,269 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+  type Stats,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const SERVICE_STATE_LOCK_WAIT_MS = 2_000;
+const SERVICE_STATE_LOCK_POLL_MS = 20;
+const SERVICE_STATE_LOCK_STALE_MS = 30_000;
+const PROCESS_INSTANCE = randomUUID();
+
+interface ServiceStateLockRecord {
+  readonly version: 1;
+  readonly pid: number;
+  readonly processInstance: string;
+  readonly token: string;
+  readonly createdAt: number;
+}
+
+interface ServiceStateLockSnapshot {
+  readonly record: ServiceStateLockRecord;
+  readonly ownerPath: string;
+  readonly lockIdentity: Pick<Stats, "dev" | "ino">;
+  readonly ownerIdentity: Pick<Stats, "dev" | "ino" | "size">;
+  readonly mtimeMs: number;
+}
+
+export interface ServiceStateLockHooks {
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => void;
+  readonly processAlive?: (pid: number) => boolean;
+  readonly beforeStaleDelete?: (lockPath: string) => void;
+  readonly beforeRelease?: (lockPath: string) => void;
+}
+
+interface HeldServiceStateLock {
+  depth: number;
+  readonly snapshot: ServiceStateLockSnapshot;
+}
+
+const heldLocks = new Map<string, HeldServiceStateLock>();
+
+function lockPathForStatePath(statePath: string): string {
+  try { return `${realpathSync.native(statePath)}.lock`; }
+  catch {
+    try { return join(realpathSync.native(dirname(statePath)), `${basename(statePath)}.lock`); }
+    catch { return `${statePath}.lock`; }
+  }
+}
+
+function lockOwnerProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but this account cannot signal it. Unknown failures
+    // also fail closed: only ESRCH proves the holder is gone.
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+function sameIdentity(
+  left: Pick<Stats, "dev" | "ino">,
+  right: Pick<Stats, "dev" | "ino">,
+): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function ownerFileName(record: ServiceStateLockRecord): string {
+  return `v1-${record.pid}-${record.processInstance}-${record.token}.json`;
+}
+
+function parseOwnerFileName(name: string): { pid: number; pathToken: string } | null {
+  const match = /^v1-([1-9][0-9]*)-([0-9a-f-]+)-([0-9a-f-]+)[.]json$/i.exec(name);
+  if (!match) return null;
+  const pid = Number(match[1]);
+  return Number.isSafeInteger(pid) && pid > 0 ? { pid, pathToken: `${match[2]}-${match[3]}` } : null;
+}
+
+function readLockSnapshot(lockPath: string): ServiceStateLockSnapshot | null {
+  let lockIdentity: Stats;
+  let entries: string[];
+  try {
+    lockIdentity = lstatSync(lockPath);
+    if (!lockIdentity.isDirectory()) return null;
+    entries = readdirSync(lockPath);
+  } catch {
+    return null;
+  }
+  if (entries.length !== 1 || !parseOwnerFileName(entries[0]!)) return null;
+  const ownerPath = join(lockPath, entries[0]!);
+  try {
+    const ownerIdentity = lstatSync(ownerPath);
+    if (!ownerIdentity.isFile() || ownerIdentity.size > 4096) return null;
+    const value = JSON.parse(readFileSync(ownerPath, "utf8")) as Partial<ServiceStateLockRecord>;
+    if (value.version !== 1 || !Number.isSafeInteger(value.pid) || (value.pid ?? 0) <= 0
+      || typeof value.processInstance !== "string" || value.processInstance.length === 0
+      || typeof value.token !== "string" || value.token.length === 0
+      || typeof value.createdAt !== "number" || !Number.isFinite(value.createdAt)) return null;
+    const record = value as ServiceStateLockRecord;
+    if (entries[0] !== ownerFileName(record)) return null;
+    const currentLock = lstatSync(lockPath);
+    const currentOwner = lstatSync(ownerPath);
+    if (!currentLock.isDirectory() || !sameIdentity(lockIdentity, currentLock)
+      || !currentOwner.isFile() || !sameIdentity(ownerIdentity, currentOwner)
+      || currentOwner.size !== ownerIdentity.size) return null;
+    return { record, ownerPath, lockIdentity, ownerIdentity, mtimeMs: ownerIdentity.mtimeMs };
+  } catch {
+    return null;
+  }
+}
+
+function sameLock(left: ServiceStateLockSnapshot, right: ServiceStateLockSnapshot): boolean {
+  return left.record.token === right.record.token
+    && left.record.pid === right.record.pid
+    && left.record.processInstance === right.record.processInstance
+    && sameIdentity(left.lockIdentity, right.lockIdentity)
+    && sameIdentity(left.ownerIdentity, right.ownerIdentity)
+    && left.ownerIdentity.size === right.ownerIdentity.size;
+}
+
+function parsedIncompleteOwner(lockPath: string): { ownerPath: string | null; pid: number | null; mtimeMs: number } | null {
+  try {
+    const lock = lstatSync(lockPath);
+    if (!lock.isDirectory()) return null;
+    const entries = readdirSync(lockPath);
+    if (entries.length === 0) return { ownerPath: null, pid: null, mtimeMs: lock.mtimeMs };
+    if (entries.length !== 1) return null;
+    const parsed = parseOwnerFileName(entries[0]!);
+    if (!parsed) return null;
+    const ownerPath = join(lockPath, entries[0]!);
+    const owner = lstatSync(ownerPath);
+    return owner.isFile() ? { ownerPath, pid: parsed.pid, mtimeMs: owner.mtimeMs } : null;
+  } catch {
+    return null;
+  }
+}
+
+function reclaimStaleLock(lockPath: string, hooks: ServiceStateLockHooks): boolean {
+  const now = hooks.now ?? Date.now;
+  const processAlive = hooks.processAlive ?? lockOwnerProcessAlive;
+  const snapshot = readLockSnapshot(lockPath);
+  const incomplete = snapshot ? null : parsedIncompleteOwner(lockPath);
+  if (!snapshot && !incomplete) return false;
+  const ownerPath = snapshot?.ownerPath ?? incomplete!.ownerPath;
+  const ownerPid = snapshot?.record.pid ?? incomplete!.pid;
+  const createdAt = snapshot ? Math.max(snapshot.record.createdAt, snapshot.mtimeMs) : incomplete!.mtimeMs;
+  if (now() - createdAt <= SERVICE_STATE_LOCK_STALE_MS || (ownerPid !== null && processAlive(ownerPid))) {
+    return false;
+  }
+  if (snapshot) {
+    const current = readLockSnapshot(lockPath);
+    if (!current || !sameLock(snapshot, current)) return false;
+  }
+  hooks.beforeStaleDelete?.(lockPath);
+  try {
+    // The owner filename contains the holder's PID, process-instance nonce and token. A
+    // successor has a different name, so this unlink cannot delete the successor's owner.
+    if (ownerPath) unlinkSync(ownerPath);
+    rmdirSync(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function acquireOne(lockPath: string, hooks: ServiceStateLockHooks, waitMs: number): ServiceStateLockSnapshot {
+  const held = heldLocks.get(lockPath);
+  if (held) { held.depth += 1; return held.snapshot; }
+  const now = hooks.now ?? Date.now;
+  const sleep = hooks.sleep ?? (ms => Bun.sleepSync(ms));
+  const deadline = now() + waitMs;
+  if (!existsSync(dirname(lockPath))) mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+  for (;;) {
+    const record: ServiceStateLockRecord = {
+      version: 1,
+      pid: process.pid,
+      processInstance: PROCESS_INSTANCE,
+      token: randomUUID(),
+      createdAt: now(),
+    };
+    const ownerPath = join(lockPath, ownerFileName(record));
+    let createdDirectory = false;
+    let descriptor: number | null = null;
+    try {
+      mkdirSync(lockPath, { mode: 0o700 });
+      createdDirectory = true;
+      descriptor = openSync(ownerPath, "wx", 0o600);
+      writeFileSync(descriptor, `${JSON.stringify(record)}\n`, "utf8");
+      fsyncSync(descriptor);
+      closeSync(descriptor);
+      descriptor = null;
+      const snapshot = readLockSnapshot(lockPath);
+      if (!snapshot || snapshot.record.token !== record.token) throw new Error("service state lock ownership could not be verified");
+      heldLocks.set(lockPath, { depth: 1, snapshot });
+      return snapshot;
+    } catch (error) {
+      if (descriptor !== null) { try { closeSync(descriptor); } catch { /* best-effort */ } }
+      if (createdDirectory) {
+        try { unlinkSync(ownerPath); } catch { /* incomplete owner may remain for dead-PID recovery */ }
+        try { rmdirSync(lockPath); } catch { /* another entry or uncertain owner remains */ }
+      }
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "EEXIST") throw error;
+      if (reclaimStaleLock(lockPath, hooks)) continue;
+      if (now() >= deadline) {
+        throw new Error(`another process owns the service state lock at ${lockPath}; nothing was written`);
+      }
+      sleep(SERVICE_STATE_LOCK_POLL_MS);
+    }
+  }
+}
+
+function releaseOne(lockPath: string, hooks: ServiceStateLockHooks): void {
+  const held = heldLocks.get(lockPath);
+  if (!held) return;
+  held.depth -= 1;
+  if (held.depth > 0) return;
+  heldLocks.delete(lockPath);
+  hooks.beforeRelease?.(lockPath);
+  try {
+    const current = readLockSnapshot(lockPath);
+    if (!current || !sameLock(held.snapshot, current)) return;
+    unlinkSync(held.snapshot.ownerPath);
+    rmdirSync(lockPath);
+  } catch { /* a verified future holder or stale recovery owns cleanup */ }
+}
+
+export function assertServiceStateLocksOwned(statePaths: readonly string[]): void {
+  for (const path of statePaths) {
+    const lockPath = lockPathForStatePath(path);
+    const held = heldLocks.get(lockPath);
+    const current = readLockSnapshot(lockPath);
+    if (!held || !current || !sameLock(held.snapshot, current)) {
+      throw new Error(`service state lock ownership changed before commit: ${lockPath}`);
+    }
+  }
+}
+
+export function withServiceStateLocks<T>(
+  statePaths: readonly string[],
+  run: () => T,
+  options: { readonly waitMs?: number; readonly hooks?: ServiceStateLockHooks } = {},
+): T {
+  const hooks = options.hooks ?? {};
+  const lockPaths = [...new Set(statePaths.map(lockPathForStatePath))].sort();
+  const acquired: string[] = [];
+  try {
+    for (const lockPath of lockPaths) {
+      acquireOne(lockPath, hooks, options.waitMs ?? SERVICE_STATE_LOCK_WAIT_MS);
+      acquired.push(lockPath);
+    }
+    return run();
+  } finally {
+    for (const lockPath of acquired.reverse()) releaseOne(lockPath, hooks);
+  }
+}
diff --git a/src/service/state-record.d.mts b/src/service/state-record.d.mts
new file mode 100644
index 00000000000..6fa0eb77efd
--- /dev/null
+++ b/src/service/state-record.d.mts
@@ -0,0 +1,36 @@
+export interface ServiceOwnershipRecord {
+  readonly owner: "cli" | "desktop";
+  readonly installId: string;
+  readonly consentGeneration: number;
+  readonly [key: string]: unknown;
+}
+
+export declare const SERVICE_OWNERSHIP_PROTOCOL_VERSION: 1;
+export declare const SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION: "2.61.0";
+
+export interface ServiceInstallStateRecord {
+  readonly version: 1 | 2;
+  readonly codexHome: string;
+  readonly opencodexHome: string;
+  readonly revision?: number;
+  readonly ownership?: ServiceOwnershipRecord;
+  readonly [key: string]: unknown;
+}
+
+export type ServiceStateRecordEvidence =
+  | { readonly path: string; readonly kind: "absent" }
+  | { readonly path: string; readonly kind: "unreadable"; readonly reason: string }
+  | { readonly path: string; readonly kind: "invalid" }
+  | { readonly path: string; readonly kind: "valid"; readonly state: ServiceInstallStateRecord };
+
+export type AuthoritativeServiceStateRecord =
+  | { readonly kind: "none"; readonly revision: 0; readonly needsRepair: false }
+  | { readonly kind: "state"; readonly state: ServiceInstallStateRecord; readonly revision: number; readonly needsRepair: boolean }
+  | { readonly kind: "unknown"; readonly reason: string };
+
+export declare function parseServiceOwnershipRecord(value: unknown): ServiceOwnershipRecord | null;
+export declare function parseServiceInstallStateRecord(value: unknown): ServiceInstallStateRecord | null;
+export declare function serviceStatePathsForHomes(opencodexHome: string, defaultOpenCodexHome: string, platform?: NodeJS.Platform): string[];
+export declare function inspectServiceStateRecords(paths: readonly string[], read?: (path: string) => string): readonly ServiceStateRecordEvidence[];
+export declare function serviceStateFingerprint(value: unknown): string;
+export declare function selectAuthoritativeServiceState(evidence: readonly ServiceStateRecordEvidence[]): AuthoritativeServiceStateRecord;
diff --git a/src/service/state-record.mjs b/src/service/state-record.mjs
new file mode 100644
index 00000000000..dc0270cb469
--- /dev/null
+++ b/src/service/state-record.mjs
@@ -0,0 +1,138 @@
+import { readFileSync, realpathSync } from "node:fs";
+import { posix, win32 } from "node:path";
+
+export const SERVICE_OWNERSHIP_PROTOCOL_VERSION = 1;
+export const SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION = "2.61.0";
+
+const isObject = value => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const isNonNegativeSafeInteger = value => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const nonEmptyString = value => typeof value === "string" && value.length > 0;
+
+/** Parse the ownership payload shared by the Bun service code and the Node launcher. */
+export function parseServiceOwnershipRecord(value) {
+  if (!isObject(value)) return null;
+  if (value.owner !== "cli" && value.owner !== "desktop") return null;
+  if (!nonEmptyString(value.installId) || !isNonNegativeSafeInteger(value.consentGeneration)) return null;
+  return value;
+}
+
+/** Parse the COMPLETE install record; ownership alone is not enough to trust the file. */
+export function parseServiceInstallStateRecord(value) {
+  if (!isObject(value) || (value.version !== 1 && value.version !== 2)) return null;
+  if (!nonEmptyString(value.codexHome) || !nonEmptyString(value.opencodexHome)) return null;
+  for (const key of ["codexSqliteHome", "bunPath", "launcherPath", "winswVersion", "winswSha256"]) {
+    if (value[key] !== undefined && !nonEmptyString(value[key])) return null;
+  }
+  if (value.cliPath !== undefined && value.cliPath !== null && !nonEmptyString(value.cliPath)) return null;
+  if (value.revision !== undefined && !isNonNegativeSafeInteger(value.revision)) return null;
+  if (value.consentGenerationCeiling !== undefined && !isNonNegativeSafeInteger(value.consentGenerationCeiling)) return null;
+  if (value.ownershipProtocolVersion !== undefined && !isNonNegativeSafeInteger(value.ownershipProtocolVersion)) return null;
+  if (value.ownership !== undefined && parseServiceOwnershipRecord(value.ownership) === null) return null;
+  if (value.version === 1) {
+    if (value.backend !== undefined) return null;
+  } else if (value.backend !== "scheduler" && value.backend !== "native") return null;
+  return value;
+}
+
+export function serviceStatePathsForHomes(opencodexHome, defaultOpenCodexHome, platform = process.platform) {
+  const tools = platform === "win32" ? win32 : posix;
+  const primary = tools.join(opencodexHome, "service-state.json");
+  const legacy = tools.join(defaultOpenCodexHome, "service-state.json");
+  const key = path => {
+    let canonical;
+    try { canonical = realpathSync.native(path); }
+    catch {
+      try { canonical = tools.join(realpathSync.native(tools.dirname(path)), tools.basename(path)); }
+      catch { canonical = tools.resolve(path); }
+    }
+    return platform === "win32" ? canonical.toLowerCase() : canonical;
+  };
+  return key(primary) === key(legacy) ? [primary] : [primary, legacy];
+}
+
+function errorCode(error) {
+  return error && typeof error === "object" && "code" in error ? String(error.code ?? "") : "";
+}
+
+/** Read every supplied state path without collapsing absent, invalid and unreadable. */
+export function inspectServiceStateRecords(paths, read = path => readFileSync(path, "utf8")) {
+  return paths.map(path => {
+    let raw;
+    try {
+      raw = read(path);
+    } catch (error) {
+      const code = errorCode(error);
+      return code === "ENOENT"
+        ? { path, kind: "absent" }
+        : { path, kind: "unreadable", reason: code || String(error) };
+    }
+    try {
+      const state = parseServiceInstallStateRecord(JSON.parse(raw));
+      return state ? { path, kind: "valid", state } : { path, kind: "invalid" };
+    } catch {
+      return { path, kind: "invalid" };
+    }
+  });
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (!isObject(value)) return JSON.stringify(value);
+  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+}
+
+export function serviceStateFingerprint(value) {
+  return canonical(value);
+}
+
+/**
+ * Select one authoritative generation from mirrored state.
+ *
+ * The final path is authoritative. A lower-revision mirror is repairable; a same-or-newer
+ * disagreement is unordered evidence and fails closed. Before the authority exists, one valid
+ * active-home record is imported exactly once as migration input.
+ */
+export function selectAuthoritativeServiceState(evidence) {
+  const authority = evidence.at(-1);
+  if (!authority) return { kind: "none", revision: 0, needsRepair: false };
+  if (authority.kind === "unreadable") {
+    return { kind: "unknown", reason: `the authoritative service state could not be read (${authority.reason})` };
+  }
+  if (authority.kind === "invalid") {
+    return { kind: "unknown", reason: "the authoritative service install record is present but not valid" };
+  }
+  if (authority.kind === "valid") {
+    const fingerprint = canonical(authority.state);
+    const authorityRevision = authority.state.revision ?? 0;
+    const unorderedConflict = evidence.slice(0, -1).find(entry => entry.kind === "valid"
+      && (entry.state.revision ?? 0) >= authorityRevision
+      && canonical(entry.state) !== fingerprint);
+    if (unorderedConflict) {
+      return { kind: "unknown", reason: `a service state mirror conflicts with authority revision ${authorityRevision}` };
+    }
+    return {
+      kind: "state",
+      state: authority.state,
+      revision: authorityRevision,
+      needsRepair: evidence.slice(0, -1).some(entry => entry.kind !== "valid" || canonical(entry.state) !== fingerprint),
+    };
+  }
+
+  // The authority has never been established. A single valid active-home mirror is the
+  // migration source; after the first write it can no longer vote against the authority.
+  const migration = evidence.slice(0, -1);
+  const unreadable = migration.find(entry => entry.kind === "unreadable");
+  if (unreadable) return { kind: "unknown", reason: `a legacy service state path could not be read (${unreadable.reason})` };
+  if (migration.some(entry => entry.kind === "invalid")) {
+    return { kind: "unknown", reason: "a legacy service install record is present but not valid" };
+  }
+  const valid = migration.filter(entry => entry.kind === "valid");
+  if (valid.length === 0) return { kind: "none", revision: 0, needsRepair: false };
+  const revision = Math.max(...valid.map(entry => entry.state.revision ?? 0));
+  const newest = valid.filter(entry => (entry.state.revision ?? 0) === revision);
+  const fingerprint = canonical(newest[0].state);
+  if (newest.some(entry => canonical(entry.state) !== fingerprint)) {
+    return { kind: "unknown", reason: `legacy service state mirrors disagree at revision ${revision}` };
+  }
+  return { kind: "state", state: newest[0].state, revision, needsRepair: true };
+}
diff --git a/src/service/state.ts b/src/service/state.ts
index 415c3b7d761..dbd2520b07b 100644
--- a/src/service/state.ts
+++ b/src/service/state.ts
@@ -1,14 +1,33 @@
-import { accessSync, chmodSync, constants as fsConstants, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, constants as fsConstants, existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
 import { expandUserPath, getConfigDir } from "../config";
+import { atomicWriteFileStreamed } from "../config/atomic-write";
 import { resolveCodexHomeDir, type CodexHomeDeps } from "../codex/home";
 import { resolveCodexSqliteHome } from "../codex/paths";
 import { durableBunRuntime, type BunRuntimeSource, type DurableBunRuntime } from "../lib/bun-runtime";
 import { WINSW_SHA256, WINSW_VERSION } from "../lib/winsw";
-import { hardenSecretPath } from "../lib/windows-secret-acl";
-import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { isProtectedHomeUnderTest, isTestHomeGuardArmed } from "../lib/test-home-guard";
+import { isStandaloneBinary } from "../lib/standalone";
+import {
+  inspectInstallStateBytes,
+  parseInstallStateRecord,
+  parseOwnershipClaim,
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+  serviceStateFilesFor,
+} from "./install-state-contract.mjs";
+import type { ServiceStateRecordEvidence } from "./state-record.mjs";
+import { assertServiceStateLocksOwned, withServiceStateLocks, type ServiceStateLockHooks } from "./state-lock";
+import { withOwnershipMutationLease, type OwnershipMutationLeaseOptions } from "./ownership-mutation-lease.mjs";
+import {
+  assessServiceTakeoverCompatibility,
+  sameServiceTakeoverCompatibility,
+  type ManagingCliObservation,
+  type ServiceTakeoverCompatibility,
+} from "./ownership-compatibility";
 
 /**
  * Written only by the launchd plist and the systemd unit. `OCX_SERVICE=1` cannot stand in
@@ -19,6 +38,7 @@ export const SERVICE_MANAGED_ENV = "OCX_SERVICE_MANAGED";
 
 export const LABEL = "com.opencodex.proxy";
 export const TASK = "opencodex-proxy";
+export { SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION, SERVICE_OWNERSHIP_PROTOCOL_VERSION };
 
 // This module lives one level below the original src/service.ts, so path-relative
 // lookups anchored at that file's directory go through this constant instead.
@@ -26,14 +46,18 @@ export const serviceSourceDir = dirname(import.meta.dir);
 
 export type ServiceBackend = "scheduler" | "native";
 
-export function cliEntry(runtime: DurableBunRuntime = durableBunRuntime()): { bun: string; bunRuntimeSource: BunRuntimeSource; cli: string } {
+export function cliEntry(runtime: DurableBunRuntime = durableBunRuntime()): { bun: string; bunRuntimeSource: BunRuntimeSource; cli: string | null } {
   // Bake the bundled Bun (manager-owned global package directory, survives `ocx update`) rather than
   // a transient system Bun, so launchd/systemd/schtasks keep resolving even if a
   // standalone Bun is later removed. The CLI entry lives at src/cli/index.ts.
   //
   // Path and provenance come from ONE resolution so the marker can never describe a
   // different binary than the one actually baked.
-  return { bun: runtime.path, bunRuntimeSource: runtime.source, cli: join(serviceSourceDir, "cli", "index.ts") };
+  return {
+    bun: runtime.path,
+    bunRuntimeSource: runtime.source,
+    cli: runtime.source === "standalone" || isStandaloneBinary() ? null : join(serviceSourceDir, "cli", "index.ts"),
+  };
 }
 
 /**
@@ -130,10 +154,7 @@ function defaultOpenCodexHome(): string {
 }
 
 export function serviceStatePathsForOpenCodexHome(opencodexHome: string): string[] {
-  const paths = [join(opencodexHome, "service-state.json")];
-  const defaultPath = join(defaultOpenCodexHome(), "service-state.json");
-  if (normalizePathForCompare(defaultPath) !== normalizePathForCompare(paths[0])) paths.push(defaultPath);
-  return paths;
+  return serviceStateFilesFor(opencodexHome, defaultOpenCodexHome());
 }
 
 export function serviceStatePaths(): string[] {
@@ -223,7 +244,7 @@ export interface ServiceInstallState {
   codexSqliteHome?: string;
   /** Baked at install; lets status flag paths gone stale after npm prefix/nvm moves. */
   bunPath?: string;
-  cliPath?: string;
+  cliPath?: string | null;
   /**
    * launchd and systemd. The stable `ocx` launcher the service definition actually invokes,
    * when one was found. Present means `bunPath`/`cliPath` are provenance for the install,
@@ -236,59 +257,573 @@ export interface ServiceInstallState {
   backend?: ServiceBackend;
   winswVersion?: string;
   winswSha256?: string;
+  /**
+   * Bumped by every write through {@link swapServiceInstallState}; the compare-and-swap
+   * token. Absent means a record written before this field existed, which compares equal
+   * to 0 so the first swap over it still lands.
+   */
+  revision?: number;
+  /** Who owns the running proxy. Absent means the CLI install that registered the service. */
+  ownership?: ServiceOwnership;
+  /**
+   * The highest consent generation this record has ever carried, kept across a release.
+   *
+   * Without it the counter is an ABA token: granting, releasing and granting again produces
+   * generation 1 twice, and an app-local record holding the first 1 would read the second
+   * one as its own prior consent.
+   */
+  consentGenerationCeiling?: number;
+  /** Written only by CLIs whose start/repair/update paths honor a desktop claim. */
+  ownershipProtocolVersion?: number;
+}
+
+/**
+ * The two kinds of installation that can own the proxy.
+ *
+ * `cli` is the npm (or standalone) `ocx` install that registered the background service.
+ * `desktop` is the packaged app, which brings its own bundled runtime.
+ */
+export type ServiceOwner = "cli" | "desktop";
+
+/**
+ * Durable ownership, recorded in the shared service install state.
+ *
+ * Ownership used to be a boolean the desktop shell recomputed at every launch from whether
+ * it happened to spawn a child, so a restart silently demoted the app back to guest and
+ * "ask once, then own permanently" could not be expressed at all. This record is the thing
+ * that survives the restart.
+ *
+ * ABSENT IS NOT UNOWNED. Every installation that predates this field has no record, and the
+ * npm service registration is what owns the runtime there, so absence has to keep meaning
+ * exactly that.
+ */
+export interface ServiceOwnership {
+  readonly owner: ServiceOwner;
+  /**
+   * Opaque identity of the owning INSTALLATION — not of the user, the machine or the
+   * account. The desktop app keeps the same value in its own app-local store, and comparing
+   * the two through {@link ownershipGrantedTo} is how a reinstalled app tells its own prior
+   * consent from another installation's.
+   */
+  readonly installId: string;
+  /**
+   * Increments once per ownership grant. Re-recording the same owner and install id leaves
+   * it alone, so a relaunch cannot inflate it and "exactly one increment per takeover" is
+   * an assertion a test can make.
+   */
+  readonly consentGeneration: number;
+}
+
+/**
+ * Validate an ownership claim read off disk.
+ *
+ * Returns the ORIGINAL object rather than a rebuilt one: a newer writer may carry fields
+ * this version does not know about, and rebuilding would drop them on the next preserve —
+ * which is the same lost-field failure this whole record exists to stop.
+ */
+export function parseServiceOwnership(value: unknown): ServiceOwnership | null {
+  return parseOwnershipClaim(value) as ServiceOwnership | null;
 }
 
+/**
+ * The record contract lives in `install-state-contract.mjs` so the Node launcher validates
+ * exactly what this reader validates. It used to keep a weaker copy, and a record that fails
+ * this contract while merely lacking an `ownership` field read there as "nobody owns the
+ * runtime" — which is permission to stop a foreign runtime and reactivate the npm service.
+ */
 export function parseServiceInstallState(value: unknown): ServiceInstallState | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const state = value as Record<string, unknown>;
-  if (state.version !== 1 && state.version !== 2) return null;
-  if (typeof state.codexHome !== "string" || state.codexHome.length === 0) return null;
-  if (typeof state.opencodexHome !== "string" || state.opencodexHome.length === 0) return null;
-  for (const key of ["codexSqliteHome", "bunPath", "cliPath", "launcherPath", "winswVersion", "winswSha256"] as const) {
-    if (state[key] !== undefined && (typeof state[key] !== "string" || state[key].length === 0)) return null;
-  }
-  if (state.version === 1) {
-    if (state.backend !== undefined) return null;
-  } else if (state.backend !== "scheduler" && state.backend !== "native") {
-    return null;
-  }
-  return state as unknown as ServiceInstallState;
+  return parseInstallStateRecord(value) as ServiceInstallState | null;
 }
 
-export function writeServiceInstallState(backend: ServiceBackend = "scheduler", launcherPath?: string | null): void {
+/**
+ * What an install bakes into the record: the homes, the provenance paths and the backend.
+ *
+ * Everything here is rebuilt from the CURRENT process on every write, which is the point —
+ * it describes the install that just ran. {@link ServiceInstallState.ownership} deliberately
+ * is not part of it.
+ */
+function installProvenanceRecord(backend: ServiceBackend, launcherPath?: string | null): ServiceInstallState {
   const { bun, cli } = cliEntry();
   const codexHome = currentCodexHome();
-  const state: ServiceInstallState = {
+  return {
     version: 2,
     codexHome,
     opencodexHome: currentOpenCodexHome(),
     codexSqliteHome: resolveCodexSqliteHome({ codexHome }),
     bunPath: bun,
     cliPath: cli,
+    ownershipProtocolVersion: SERVICE_OWNERSHIP_PROTOCOL_VERSION,
     ...(launcherPath ? { launcherPath } : {}),
     backend,
     ...(backend === "native" ? { winswVersion: WINSW_VERSION, winswSha256: WINSW_SHA256 } : {}),
   };
-  for (const path of serviceStateWritePaths()) {
-    const dir = dirname(path);
-    recordOwnedConfigPath(getConfigDir(), path);
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
-    writeFileSync(path, JSON.stringify(state, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
-    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
-    if (process.platform === "win32") hardenSecretPath(path, { required: true });
-  }
+}
+
+/**
+ * Record an install, PRESERVING whatever owns the runtime.
+ *
+ * Every install, repair, update and stop path ends here, and each one used to hand this
+ * function a freshly rebuilt record that simply replaced the file. That is why ownership
+ * cannot be an ordinary field written by whoever ran last: a repair kicked off by a tray
+ * helper, or by `ocx update`, would erase a takeover the user had consented to and hand the
+ * runtime back to the npm launcher without saying anything. Preserving it here is what makes
+ * the consent durable.
+ */
+export function writeServiceInstallState(
+  backend: ServiceBackend = "scheduler",
+  launcherPath?: string | null,
+  deps: ServiceStateSwapDeps = {},
+): void {
+  swapServiceInstallState(current => ({
+    ...installProvenanceRecord(backend, launcherPath),
+    ...preservedConsent(current),
+  }), deps);
+}
+
+/** The ownership half of a record: the claim itself plus the generation high-water mark. */
+function preservedConsent(
+  current: ServiceInstallState | null,
+): Pick<ServiceInstallState, "ownership" | "consentGenerationCeiling"> {
+  const ownership = current?.ownership;
+  const ceiling = Math.max(current?.consentGenerationCeiling ?? 0, ownership?.consentGeneration ?? 0);
+  return {
+    ...(ownership ? { ownership } : {}),
+    ...(ceiling > 0 ? { consentGenerationCeiling: ceiling } : {}),
+  };
 }
 
 export function readServiceInstallState(): ServiceInstallState | null {
-  for (const path of serviceStatePaths()) {
-    try {
-      const parsed = parseServiceInstallState(JSON.parse(readFileSync(path, "utf8")));
-      if (parsed) return parsed;
-    } catch {
-      /* try the next known state path */
+  const resolved = resolveServiceState();
+  return resolved.kind === "state" ? resolved.state : null;
+}
+
+/** Raised when a non-cooperating writer prevents a stable authoritative commit. */
+export class ServiceStateConflictError extends Error {
+  constructor(readonly path: string, readonly attempts: number) {
+    super(
+      `service install state at ${path} was rewritten by another process during all ${attempts} `
+      + "compare-and-swap attempts; a stable commit could not be verified. Re-run the command.",
+    );
+    this.name = "ServiceStateConflictError";
+  }
+}
+
+export interface ServiceStateSwapDeps {
+  /** Test seam: which state paths to write. Defaults to every writable state path. */
+  paths?: readonly string[];
+  /** How many times to re-read and recompute before giving up. */
+  attempts?: number;
+  /**
+   * Test seam: runs immediately before each commit. It is the only place a competing writer
+   * can be interleaved deterministically, which is what makes the revision check testable
+   * rather than a claim in a comment.
+   */
+  beforeCommit?: (attempt: number) => void;
+  /** How long to wait for another process to release the anchor lock. */
+  lockWaitMs?: number;
+  /** Deterministic lock seams for failure-order tests. */
+  lockHooks?: ServiceStateLockHooks;
+  /** Atomic publisher seam. The callback must run immediately before its commit point. */
+  commitStateFile?: (path: string, serialized: string, validate: () => void) => void;
+  /** A mirror failure occurs after the authority committed and is therefore diagnostic. */
+  onMirrorError?: (path: string, error: unknown) => void;
+  /** Allows consented mutations to preserve a machine-readable unknown-subject error. */
+  unknownStateError?: (reason: string) => Error;
+  /** Shared with update/install/start so replacement and ownership mutation cannot overlap. */
+  mutationLease?: OwnershipMutationLeaseOptions;
+}
+
+export interface ServiceStateMutationContext {
+  readonly revision: number;
+}
+
+const SERVICE_STATE_SWAP_ATTEMPTS = 5;
+
+function authoritativeState(
+  paths: readonly string[],
+  unknownStateError?: (reason: string) => Error,
+): { current: ServiceInstallState | null; revision: number; fingerprint: string } {
+  const selected = selectAuthoritativeServiceState(
+    inspectServiceStateEvidence(paths) as readonly ServiceStateRecordEvidence[],
+  );
+  if (selected.kind === "unknown") {
+    throw unknownStateError?.(selected.reason) ?? new Error(`${selected.reason}; nothing was written`);
+  }
+  if (selected.kind === "none") return { current: null, revision: 0, fingerprint: "none" };
+  const current = selected.state as ServiceInstallState;
+  return { current, revision: selected.revision, fingerprint: serviceStateFingerprint(current) };
+}
+
+function commitServiceStateFile(path: string, serialized: string, validate: () => void): void {
+  atomicWriteFileStreamed(path, descriptor => {
+    writeFileSync(descriptor, serialized, { encoding: "utf8" });
+  }, { validateBeforeRename: validate });
+}
+
+/**
+ * Read the recorded state, compute the next one from it, and commit it only if nothing else
+ * moved the record in between.
+ *
+ * `mutate` may return null to mean "nothing to change", which writes nothing and leaves the
+ * file — including its absence — exactly as it was.
+ *
+ * WHAT THE REVISION CHECK IS. The anchor is re-read immediately before the commit and the
+ * committed bytes are read back immediately after, so a writer that landed on either side of
+ * the window is DETECTED and the whole read-modify-write runs again against the new base.
+ * The comparison is over the serialized record rather than the revision number alone,
+ * because two writers racing from one base both compute the same next revision — identical
+ * bytes mean nothing was lost, and differing bytes mean something was.
+ *
+ * The final path is the authority. With a custom home that is the legacy default-home path —
+ * the only path every writer can derive — and the active-home path is a compatibility mirror.
+ * The authority's atomic rename is the commit point. A mirror failure is reported but cannot
+ * roll back or reclassify the already committed mutation; the next writer repairs the mirror.
+ */
+export function swapServiceInstallState(
+  mutate: (current: ServiceInstallState | null, context: ServiceStateMutationContext) => ServiceInstallState | null,
+  deps: ServiceStateSwapDeps = {},
+): ServiceInstallState | null {
+  const paths = deps.paths ?? serviceStateWritePaths();
+  const authority = paths.at(-1);
+  if (authority === undefined) throw new Error("refusing to swap service install state with no state path");
+  const mirrors = paths.filter(path => path !== authority);
+  const attempts = deps.attempts ?? SERVICE_STATE_SWAP_ATTEMPTS;
+  const publish = deps.commitStateFile ?? commitServiceStateFile;
+  return withOwnershipMutationLease(paths, () => withServiceStateLocks(paths, () => {
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      const base = authoritativeState(paths, deps.unknownStateError);
+      const candidate = mutate(base.current, { revision: base.revision });
+      if (candidate === null) return base.current;
+      if (base.revision >= Number.MAX_SAFE_INTEGER) {
+        throw new Error("service state revision is exhausted; refusing to publish an unversioned mutation");
+      }
+      const next: ServiceInstallState = { ...candidate, revision: base.revision + 1 };
+      const serialized = JSON.stringify(next, null, 2) + "\n";
+      deps.beforeCommit?.(attempt);
+      assertServiceStateLocksOwned(paths);
+      const fresh = authoritativeState(paths, deps.unknownStateError);
+      if (fresh.revision !== base.revision || fresh.fingerprint !== base.fingerprint) continue;
+      const validate = () => assertServiceStateLocksOwned(paths);
+      publish(authority, serialized, validate);
+      const committed = authoritativeState([authority]);
+      if (committed.revision !== next.revision || committed.fingerprint !== serviceStateFingerprint(next)) continue;
+      for (const mirror of mirrors) {
+        try { publish(mirror, serialized, validate); }
+        catch (error) {
+          (deps.onMirrorError ?? ((path, cause) => console.warn(
+            `service state committed, but compatibility mirror ${path} could not be refreshed: ${cause instanceof Error ? cause.message : String(cause)}`,
+          )))(mirror, error);
+        }
+      }
+      return next;
     }
+    throw new ServiceStateConflictError(authority, attempts);
+  }, { waitMs: deps.lockWaitMs, hooks: deps.lockHooks }), deps.mutationLease);
+}
+
+export interface RemoveServiceStateDeps {
+  readonly paths?: readonly string[];
+  readonly unlink?: (path: string) => void;
+  readonly lockWaitMs?: number;
+  readonly lockHooks?: ServiceStateLockHooks;
+}
+
+/**
+ * Delete mirrors first and the authority last under the same ownership locks.
+ *
+ * A crash or mirror error before the final unlink leaves the authority in place, so a stale
+ * mirror can never become a migration source and resurrect a released desktop claim.
+ */
+export function removeServiceInstallStateRecords(deps: RemoveServiceStateDeps = {}): void {
+  const paths = deps.paths ?? serviceStateWritePaths();
+  const authority = paths.at(-1);
+  if (!authority) return;
+  const unlink = deps.unlink ?? unlinkSync;
+  withOwnershipMutationLease(paths, () => withServiceStateLocks(paths, () => {
+    for (const mirror of paths.slice(0, -1)) {
+      assertServiceStateLocksOwned(paths);
+      if (existsSync(mirror)) unlink(mirror);
+    }
+    assertServiceStateLocksOwned(paths);
+    if (existsSync(authority)) unlink(authority);
+  }, { waitMs: deps.lockWaitMs, hooks: deps.lockHooks }), { waitMs: deps.lockWaitMs });
+}
+
+/** The recorded owner of ONE already-read record, or null. Prefer {@link resolveServiceOwnership}. */
+export function serviceOwnership(state: ServiceInstallState | null = readServiceInstallState()): ServiceOwnership | null {
+  return state?.ownership ?? null;
+}
+
+/**
+ * What every state path, together, says about who owns the runtime.
+ *
+ * An unknown resolution is the answer that matters. \`readServiceInstallState\` collapses
+ * unreadable, malformed and absent into one null, and a caller that reads that null as "the
+ * CLI owns it" will re-enable the npm launcher over a claim it merely failed to read — the
+ * exact demotion the record exists to prevent. Absence is the only thing that may mean no
+ * claim.
+ */
+export type ServiceStateResolution =
+  | { readonly kind: "none"; readonly revision: 0; readonly needsRepair: false }
+  | { readonly kind: "state"; readonly state: ServiceInstallState; readonly revision: number; readonly needsRepair: boolean }
+  | { readonly kind: "unknown"; readonly reason: string };
+
+export type ServiceOwnershipSubject =
+  | { readonly kind: "none"; readonly revision: number }
+  | { readonly kind: "owned"; readonly ownership: ServiceOwnership; readonly revision: number };
+
+export type ServiceOwnershipResolution = ServiceOwnershipSubject
+  | { readonly kind: "unknown"; readonly reason: string };
+
+export function resolveServiceState(
+  evidence: readonly ServiceStateEvidence[] = inspectServiceStateEvidence(),
+): ServiceStateResolution {
+  const selected = selectAuthoritativeServiceState(evidence as readonly ServiceStateRecordEvidence[]);
+  if (selected.kind === "unknown") return selected;
+  if (selected.kind === "none") return selected;
+  return {
+    kind: "state",
+    state: selected.state as ServiceInstallState,
+    revision: selected.revision,
+    needsRepair: selected.needsRepair,
+  };
+}
+
+export function resolveServiceOwnership(
+  evidence: readonly ServiceStateEvidence[] = inspectServiceStateEvidence(),
+): ServiceOwnershipResolution {
+  const state = resolveServiceState(evidence);
+  if (state.kind === "unknown") return state;
+  if (state.kind === "none" || !state.state.ownership) return { kind: "none", revision: state.revision };
+  return { kind: "owned", ownership: state.state.ownership, revision: state.revision };
+}
+
+export function sameServiceOwnershipSubject(
+  left: ServiceOwnershipSubject,
+  right: ServiceOwnershipSubject,
+): boolean {
+  if (left.kind !== right.kind || left.revision !== right.revision) return false;
+  if (left.kind === "none" || right.kind === "none") return true;
+  return left.ownership.owner === right.ownership.owner
+    && left.ownership.installId === right.ownership.installId
+    && left.ownership.consentGeneration === right.ownership.consentGeneration;
+}
+
+function sameServiceOwnershipIdentity(left: ServiceOwnershipSubject, right: ServiceOwnershipSubject): boolean {
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "none" || right.kind === "none") return true;
+  return left.ownership.owner === right.ownership.owner
+    && left.ownership.installId === right.ownership.installId
+    && left.ownership.consentGeneration === right.ownership.consentGeneration;
+}
+
+function serviceOwnershipSubject(
+  state: ServiceInstallState | null,
+  revision: number,
+): ServiceOwnershipSubject {
+  return state?.ownership
+    ? { kind: "owned", ownership: state.ownership, revision }
+    : { kind: "none", revision };
+}
+
+export class ServiceOwnershipSubjectMismatchError extends Error {
+  readonly code = "service-ownership-subject-mismatch" as const;
+  constructor(readonly expected: ServiceOwnershipSubject, readonly actual: ServiceOwnershipSubject) {
+    super("service ownership changed after consent; resolve again and ask for fresh approval");
+    this.name = "ServiceOwnershipSubjectMismatchError";
   }
-  return null;
+}
+
+export class ServiceOwnershipSubjectUnknownError extends Error {
+  readonly code = "service-ownership-subject-unknown" as const;
+  constructor(readonly expected: ServiceOwnershipSubject, readonly reason: string) {
+    super(`service ownership could not be revalidated after consent (${reason}); nothing was written`);
+    this.name = "ServiceOwnershipSubjectUnknownError";
+  }
+}
+
+export class ServiceTakeoverCompatibilityChangedError extends Error {
+  readonly code = "service-takeover-compatibility-changed" as const;
+  constructor(readonly actual: ServiceTakeoverCompatibility) {
+    super("the managing CLI compatibility changed after consent; resolve again and ask for fresh approval");
+    this.name = "ServiceTakeoverCompatibilityChangedError";
+  }
+}
+
+/**
+ * Whether the packaged desktop app owns the runtime.
+ *
+ * This is the predicate `ocx service repair` and `ocx update` consult before they would
+ * re-enable, rewrite or restart the npm service registration. The registration itself is
+ * kept either way — the maintainer's decision is that the user's install is never deleted,
+ * so this marker is the only thing that makes the takeover durable.
+ */
+export function desktopOwnsService(state: ServiceInstallState | null = readServiceInstallState()): boolean {
+  return serviceOwnership(state)?.owner === "desktop";
+}
+
+/**
+ * THE COMPARISON RULE. An installation holds the recorded grant only when both the kind of
+ * owner and the install id match its own.
+ *
+ * The desktop app calls this at launch with the install id from its app-local store. True
+ * means this very installation already has consent and must not ask again. False with a
+ * non-null `ownership` means a DIFFERENT installation owns the runtime — a reinstalled app,
+ * or a second copy — and consent has to be asked before taking over. Null means nothing is
+ * recorded and the npm install still owns it.
+ */
+export function ownershipGrantedTo(
+  ownership: ServiceOwnership | null,
+  owner: ServiceOwner,
+  installId: string,
+): boolean {
+  return ownership !== null && ownership.owner === owner && ownership.installId === installId;
+}
+
+/**
+ * The record an ownership write lands on when no install state exists yet.
+ *
+ * Deliberately carries no `bunPath`, `cliPath` or `launcherPath`: those are baked BY AN
+ * INSTALL, and a takeover is not one. Recording the claiming process's own paths as install
+ * provenance would make `ocx service status` describe a registration nobody created.
+ */
+function ownershipBaseRecord(current: ServiceInstallState | null): ServiceInstallState {
+  if (current) return current;
+  const codexHome = currentCodexHome();
+  return {
+    version: 2,
+    codexHome,
+    opencodexHome: currentOpenCodexHome(),
+    codexSqliteHome: resolveCodexSqliteHome({ codexHome }),
+    backend: "scheduler",
+  };
+}
+
+/**
+ * Record `claim` as the runtime's owner and return what was written.
+ *
+ * Idempotent by design: re-recording the same owner and install id leaves the consent
+ * generation alone, so every relaunch of an app that already has consent is a no-op on the
+ * number. A different owner or a different install id is a new grant and increments it once.
+ */
+export interface RecordServiceOwnerRequest {
+  readonly owner: ServiceOwner;
+  readonly installId: string;
+  readonly expectedSubject: ServiceOwnershipSubject;
+  readonly expectedCompatibility: Extract<ServiceTakeoverCompatibility, { kind: "supported" }>;
+}
+
+export interface RecordServiceOwnerDeps extends ServiceStateSwapDeps {
+  /** Re-observes BOTH the registered manager and the current PATH manager inside the lock. */
+  readonly observeManagers: () => Readonly<Record<"service-registration" | "path", ManagingCliObservation>>;
+}
+
+export function recordServiceOwner(
+  request: RecordServiceOwnerRequest,
+  deps: RecordServiceOwnerDeps,
+): Extract<ServiceOwnershipSubject, { kind: "owned" }> {
+  if (!request.installId) throw new Error("refusing to record service ownership without an install id");
+  if (!request.expectedSubject || request.expectedCompatibility?.kind !== "supported") {
+    throw new Error("refusing to record service ownership without the exact approved subject and compatibility token");
+  }
+  if (!deps || typeof deps.observeManagers !== "function") {
+    throw new Error("refusing to record service ownership without a managing-CLI revalidation callback");
+  }
+  const { observeManagers, ...swapDeps } = deps;
+  let recorded: ServiceOwnership | null = null;
+  const committed = swapServiceInstallState((current, context) => {
+    const actualSubject = serviceOwnershipSubject(current, context.revision);
+    if (!sameServiceOwnershipSubject(request.expectedSubject, actualSubject)) {
+      throw new ServiceOwnershipSubjectMismatchError(request.expectedSubject, actualSubject);
+    }
+    let managers: Readonly<Record<"service-registration" | "path", ManagingCliObservation>>;
+    try { managers = observeManagers(); }
+    catch (error) {
+      throw new ServiceTakeoverCompatibilityChangedError({
+        kind: "blocked",
+        reason: "managing-cli-unknown",
+        detail: error instanceof Error ? error.message : String(error),
+        minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+      });
+    }
+    const compatibility = assessServiceTakeoverCompatibility({
+      state: current,
+      subject: actualSubject,
+      managers,
+    });
+    if (!sameServiceTakeoverCompatibility(request.expectedCompatibility, compatibility)) {
+      throw new ServiceTakeoverCompatibilityChangedError(compatibility);
+    }
+    const previous = current?.ownership ?? null;
+    // The ceiling, not just the live claim: a grant that was released left its number
+    // behind on purpose, so a later grant cannot reuse it.
+    const floor = Math.max(previous?.consentGeneration ?? 0, current?.consentGenerationCeiling ?? 0);
+    if (floor >= Number.MAX_SAFE_INTEGER) {
+      throw new Error("service ownership consent generation is exhausted; nothing was written");
+    }
+    recorded = {
+      owner: request.owner,
+      installId: request.installId,
+      consentGeneration: previous && ownershipGrantedTo(previous, request.owner, request.installId)
+        ? previous.consentGeneration
+        : floor + 1,
+    };
+    return {
+      ...ownershipBaseRecord(current),
+      ownership: recorded,
+      consentGenerationCeiling: Math.max(floor, recorded.consentGeneration),
+    };
+  }, {
+    ...swapDeps,
+    unknownStateError: reason => new ServiceOwnershipSubjectUnknownError(request.expectedSubject, reason),
+  });
+  if (recorded === null || !committed?.ownership || committed.revision === undefined) {
+    throw new Error("service ownership was not recorded");
+  }
+  return { kind: "owned", ownership: committed.ownership, revision: committed.revision };
+}
+
+/**
+ * Drop a recorded owner and return what was dropped, or null when nothing was recorded.
+ *
+ * Writes nothing when there is no claim to release, so asking about an unowned runtime never
+ * creates an install record describing a service nobody registered.
+ */
+export interface ReleaseServiceOwnerDeps extends ServiceStateSwapDeps {
+  /** Service install refreshes provenance first; that known write may advance only revision. */
+  readonly allowRevisionAdvance?: boolean;
+}
+
+export function releaseServiceOwner(
+  expectedSubject: ServiceOwnershipSubject,
+  deps: ReleaseServiceOwnerDeps = {},
+): ServiceOwnership | null {
+  const { allowRevisionAdvance = false, ...swapDeps } = deps;
+  let released: ServiceOwnership | null = null;
+  swapServiceInstallState((current, context) => {
+    const actualSubject = serviceOwnershipSubject(current, context.revision);
+    const matches = allowRevisionAdvance
+      ? sameServiceOwnershipIdentity(expectedSubject, actualSubject) && actualSubject.revision >= expectedSubject.revision
+      : sameServiceOwnershipSubject(expectedSubject, actualSubject);
+    if (!matches) throw new ServiceOwnershipSubjectMismatchError(expectedSubject, actualSubject);
+    released = current?.ownership ?? null;
+    if (!current?.ownership) return null;
+    const { ownership: _released, ...withoutOwnership } = current;
+    // Keep the number. Dropping it makes the generation an ABA token: grant, release, grant
+    // again would produce 1 twice, and an app-local record still holding the first 1 would
+    // read the second grant as its own prior consent.
+    return {
+      ...withoutOwnership,
+      consentGenerationCeiling: Math.max(
+        current.consentGenerationCeiling ?? 0,
+        current.ownership.consentGeneration,
+      ),
+    };
+  }, {
+    ...swapDeps,
+    unknownStateError: reason => new ServiceOwnershipSubjectUnknownError(expectedSubject, reason),
+  });
+  return released;
 }
 
 /** What ONE state path said. Absent, unreadable and invalid are different answers. */
@@ -301,37 +836,16 @@ export type ServiceStateEvidence =
 /**
  * Every state path, with what each one said.
  *
- * `readServiceInstallState` returns the FIRST path that parsed and discards the
- * rest, so a valid mirror beside a corrupt one reads as clean. That is the right
- * behavior for callers that just need the install state; it is the wrong input
- * for deciding ownership, where a disagreement between mirrors is exactly the
- * evidence that matters.
+ * The final path is authoritative; earlier paths are compatibility mirrors and the
+ * migration source only while the authority is absent. Keeping the raw evidence separate
+ * lets the selector distinguish migration, degraded mirrors and unordered conflicts.
  */
 export function inspectServiceStateEvidence(
   paths: readonly string[] = serviceStatePaths(),
 ): readonly ServiceStateEvidence[] {
-  return paths.map((path): ServiceStateEvidence => {
-    let raw: string;
-    try {
-      raw = readFileSync(path, "utf8");
-    } catch (error) {
-      const code = error && typeof error === "object" && "code" in error
-        ? String((error as { code?: unknown }).code)
-        : "";
-      // ENOENT is an answer. EACCES, ENOTDIR and the rest are a failure to ask,
-      // and collapsing them into absence is how a locked-down state file would
-      // become permission to write.
-      if (code === "ENOENT") return { path, kind: "absent" };
-      return { path, kind: "unreadable", reason: code || String(error) };
-    }
-    let parsed: ServiceInstallState | null;
-    try {
-      parsed = parseServiceInstallState(JSON.parse(raw));
-    } catch {
-      return { path, kind: "invalid" };
-    }
-    return parsed ? { path, kind: "valid", state: parsed } : { path, kind: "invalid" };
-  });
+  return paths.map(path => (
+    inspectInstallStateBytes(path, at => readFileSync(at, "utf8")) as ServiceStateEvidence
+  ));
 }
 
 /** The homes this process is actually using, for comparison against a claim. */
diff --git a/src/service/windows-taskxml.ts b/src/service/windows-taskxml.ts
index e3ede372d21..38d8286d5b9 100644
--- a/src/service/windows-taskxml.ts
+++ b/src/service/windows-taskxml.ts
@@ -79,10 +79,11 @@ export function buildWindowsServiceScript(
     windowsBatchSet("OCX_API_TOKEN_FILE", serviceApiTokenFilePath(), "path"),
     windowsBatchSet("OCX_SERVICE_LOG", serviceLogPath(), "path"),
     windowsBatchSet("OCX_BUN", bun, "path"),
-    windowsBatchSet("OCX_CLI", cli, "path"),
+    windowsBatchSet("OCX_CLI", cli ?? undefined, "path"),
+    // Standalone executables have no npm package tree; recovery is "replace the executable", so no OCX_PKG_DIR/restore_backup wiring.
     // Package root for the transactional-update restore path (#1942): cli is
     // <pkg>\src\cli\index.ts, so the package dir is three levels up.
-    'for %%I in ("%OCX_CLI%\\..\\..\\..") do set "OCX_PKG_DIR=%%~fI"',
+    cli ? 'for %%I in ("%OCX_CLI%\\..\\..\\..") do set "OCX_PKG_DIR=%%~fI"' : null,
     'if exist "%OCX_API_TOKEN_FILE%" (',
     '  set /p OPENCODEX_API_AUTH_TOKEN=<"%OCX_API_TOKEN_FILE%"',
     ")",
@@ -101,14 +102,14 @@ export function buildWindowsServiceScript(
     '  >>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] installation is incomplete: bundled Bun is missing; reinstall opencodex, then run ocx service repair',
     "  exit /b 3",
     ")",
-    'if not exist "%OCX_CLI%" (',
-    "  call :restore_backup",
-    ")",
-    'if not exist "%OCX_CLI%" (',
-    '  >>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] installation is incomplete: CLI entry is missing; reinstall opencodex, then run ocx service repair',
-    "  exit /b 3",
-    ")",
-    `"%OCX_BUN%" "%OCX_CLI%" start --port ${port} >>"%OCX_SERVICE_LOG%" 2>&1`,
+    cli ? 'if not exist "%OCX_CLI%" (' : null,
+    cli ? "  call :restore_backup" : null,
+    cli ? ")" : null,
+    cli ? 'if not exist "%OCX_CLI%" (' : null,
+    cli ? '  >>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] installation is incomplete: CLI entry is missing; reinstall opencodex, then run ocx service repair' : null,
+    cli ? "  exit /b 3" : null,
+    cli ? ")" : null,
+    cli ? `"%OCX_BUN%" "%OCX_CLI%" start --port ${port} >>"%OCX_SERVICE_LOG%" 2>&1` : `"%OCX_BUN%" start --port ${port} >>"%OCX_SERVICE_LOG%" 2>&1`,
     "if %ERRORLEVEL% NEQ 0 (",
     '  >>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] child exited with code %ERRORLEVEL%; restarting in 5s',
     // `timeout` needs console stdin and dies with "Input redirection is not supported"
diff --git a/src/tray/windows-tray.ps1 b/src/tray/windows-tray.ps1
index 8ebb9c05380..e2ee8727c7c 100644
--- a/src/tray/windows-tray.ps1
+++ b/src/tray/windows-tray.ps1
@@ -5,7 +5,7 @@ param(
   [Parameter(Mandatory = $true)][string]$OpenCodexHome,
   # Provenance of $BunPath, chosen when the tray entry was built. Optional so an
   # already-installed launcher command from an older version still starts.
-  [ValidateSet("", "override", "bundled", "process")][string]$BunRuntimeSource = "",
+  [ValidateSet("", "override", "bundled", "process", "standalone")][string]$BunRuntimeSource = "",
   [ValidateSet("Run", "Stop")][string]$Mode = "Run",
   [int]$HostPid = 0
 )
diff --git a/src/types.ts b/src/types.ts
index 93390ce6063..a779713dcc9 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -17,6 +17,7 @@ export {
   isAllowedToolChoice,
   toolChoiceToolPredicate,
   declaresCodeModeExec,
+  toolRestrictsCallers,
   NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES,
 } from "./types/tools";
 
@@ -43,6 +44,7 @@ export type {
   OcxToolResultMessage,
   OcxTextContent,
   OcxImageContent,
+  OcxDocumentContent,
   OcxContentPart,
   OcxThinkingContent,
   OcxToolCall,
@@ -104,6 +106,7 @@ export type {
   ResponsesItemIdRepairConfig,
   RateLimitRetryPolicy,
   TransientRetryPolicy,
+  ResetReplayPolicy,
   ProviderWebSearchBridgeBackend,
   ProviderWebSearchBridgeConfig,
   ProviderCostOverlay,
diff --git a/src/types/config.ts b/src/types/config.ts
index 977bdb266f6..6f73b99cd42 100644
--- a/src/types/config.ts
+++ b/src/types/config.ts
@@ -137,6 +137,13 @@ export interface OcxClaudeCodeConfig {
   autoContext?: boolean;
   /** Compact-window tokens for auto-context. Default 829_800 (AUTO_COMPACT_WINDOW_DEFAULT). */
   autoCompactWindow?: number;
+  /**
+   * Local CONNECT proxy + TLS listener that intercepts Claude Code's own `api.anthropic.com`
+   * traffic without any `ANTHROPIC_BASE_URL` rewrite (src/claude/intercept). Claude Code reaches
+   * it via `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` in its settings env. Default: enabled on a
+   * hub; the proxy port defaults to the public port + 100.
+   */
+  intercept?: { enabled?: boolean; port?: number };
   /**
    * Bundled-skill content elision for ROUTED (non-Anthropic) models (devlog 260712
    * 060): Skill-tool results whose skill name matches an entry here are replaced
@@ -166,6 +173,14 @@ export interface OcxClaudeCodeConfig {
   visionSidecar?: { backend?: "openai" | "anthropic" | "routed"; model?: string };
   /** Persisted Claude Desktop four-family routing profile. */
   desktopProfile?: OcxClaudeDesktopProfile;
+  /**
+   * How Claude Desktop reaches opencodex (src/claude/desktop-first-party.ts).
+   * `first-party` (default) leaves the app on its normal claude.ai login and redirects only the
+   * Code tab's Claude Code process through the intercept pair via settings.json env.
+   * `gateway` installs the third-party deployment profile (desktop-3p) for the whole app.
+   * Unset on an install that already applied a gateway profile resolves to `gateway`.
+   */
+  desktopMode?: "first-party" | "gateway";
   /** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
   desktopAutoApply?: boolean;
   /**
@@ -253,6 +268,21 @@ export interface OcxApiKeyEntry {
   key: string;
   createdAt: string;
   pendingRotation?: OcxPendingApiKeyRotation;
+  /**
+   * Resolved provider names this key may reach. Absent or empty means every
+   * provider, which is what every existing key has, so adding the field
+   * changes nothing until an operator sets one.
+   */
+  allowedProviders?: string[];
+  /**
+   * Resolved destinations this key may reach, as a bare model id or a
+   * `provider/model` pair. Absent or empty means every model.
+   *
+   * These name destinations, not the selectors a client sends: they are
+   * checked after alias, combo, fallback and compaction resolution, because
+   * that is the only point at which the model about to be billed is known.
+   */
+  allowedModels?: string[];
 }
 
 export interface OcxPendingApiKeyRotation {
@@ -794,6 +824,13 @@ export interface OcxConfig {
    * See `src/storage/policy.ts`.
    */
   storageCleanupPolicy?: StorageCleanupPolicy;
+  /**
+   * Opt-in ceiling in bytes for `usage.jsonl`. Absent means the ledger grows without limit,
+   * which stays the default: history an operator did not ask to delete is not deleted. Values
+   * below the documented floor are treated as unset rather than enforced, because a ceiling
+   * smaller than a row cannot be met without emptying the file.
+   */
+  usageLedgerMaxBytes?: number;
   /** Generated API keys for external access to the proxy's /v1/responses endpoint. */
   apiKeys?: OcxApiKeyEntry[];
   /** Auto-start/sync the proxy from the Codex shim before launching Codex. Default true. */
diff --git a/src/types/provider.ts b/src/types/provider.ts
index e67041ee5dd..3dbf793d9fd 100644
--- a/src/types/provider.ts
+++ b/src/types/provider.ts
@@ -67,6 +67,31 @@ export interface TransientRetryPolicy {
   attempts?: number;
 }
 
+/**
+ * Opt-in replacement of a native Responses send whose upstream connection closed while the
+ * caller had observed nothing (`providers.<name>.retryOnReset`).
+ *
+ * Covers both ambiguous stages the proxy can be in: no response head at all, and a head whose
+ * SSE body carried only control events. Disabled unless the object is present; a bare `{}`
+ * opts in with defaults. Only a request the proxy can judge self-contained is ever replaced;
+ * see `src/server/responses/reset-replay.ts`. The replacement inference may still be billed if
+ * the origin had already started the first one, which is what makes this opt-in rather than
+ * default.
+ */
+export interface ResetReplayPolicy {
+  /** Master switch. Presence of the object also enables the policy (default true). */
+  enabled?: boolean;
+  /**
+   * Replacement sends one LOGICAL request may make, across every leg and every combo child
+   * (1..2, default 1).
+   *
+   * Not a per-leg retry count and not a send budget. A request that resets before the head and
+   * again after it draws on this one number, and each replacement still has to fit inside the
+   * send allowance the leg already had.
+   */
+  replacements?: number;
+}
+
 /**
  * Same-target 429 wait-and-retry policy (`providers.<name>.retryOn429`). When present and not
  * explicitly disabled, the proxy waits and replays the identical request on the same key before
@@ -388,6 +413,35 @@ export interface OcxProviderConfig {
    * link-local, or unique-local upstreams. Metadata endpoints remain blocked.
    */
   allowPrivateNetwork?: boolean;
+  /**
+   * Outbound egress for THIS provider, overriding the process-wide `proxy` decision.
+   *
+   * The global `proxy` is one value for every upstream, so it cannot express the split
+   * operators actually need: reach one gateway through a regional proxy while another stays
+   * direct on the local network (#2894). Accepted values:
+   *
+   * - absent — inherit the global proxy decision. Unchanged behaviour.
+   * - `"direct"` or `null` — never use the global proxy for this provider.
+   * - `"http://…"` / `"https://…"` — this provider's own HTTP(S) proxy.
+   * - `"socks5://…"` / `"socks5h://…"` — this provider's own SOCKS5 proxy.
+   *
+   * An empty string is rejected rather than read as DIRECT: a cleared dashboard field must not
+   * silently switch a provider from inheriting the global proxy to refusing it. A malformed
+   * value is rejected at configuration time and again at request time; it never degrades to
+   * either neighbour, because both degradations look like success at the call site.
+   *
+   * Not every transport can carry this. `structure/transports/inventory.md` records which
+   * request paths honour it and which still follow the process-wide value only.
+   */
+  proxy?: string | null;
+  /**
+   * Destinations this provider reaches without a proxy, in `NO_PROXY` syntax.
+   *
+   * Applied to whichever route `proxy` resolved to, so it carves an exemption out of this
+   * provider's own proxy AND out of an inherited global one. That second case is how a
+   * provider exempts a single host without owning a proxy of its own.
+   */
+  noProxy?: string | string[];
   /**
    * Pin the HTTP version used for upstream provider requests. Bun's fetch negotiates
    * HTTP/2 via TLS ALPN by default; some Cloudflare-fronted SSE endpoints hang on
@@ -816,6 +870,19 @@ export interface OcxProviderConfig {
    * incomplete JSON, missing arguments, and empty streams remain truncation errors.
    */
   openaiChatEofTolerance?: boolean;
+  /**
+   * Opt-in: fold a `developer` message into a `system` message instead of forwarding the role.
+   *
+   * `developer` is part of the Chat Completions message role set, so forwarding it is the
+   * default. The role used to be decided by testing the base URL host against
+   * `api.openai.com`, which assumed every OpenAI-compatible gateway rejects a standard role
+   * until proven otherwise — including gateways that proxy OpenAI itself — and quietly gave the
+   * instruction `system` precedence instead (#5213). This flag exists for a destination that
+   * genuinely rejects the role, so the conversion is a recorded decision about that destination
+   * rather than an inference from its hostname. Position is unaffected either way: the message
+   * keeps its slot in the conversation.
+   */
+  foldDeveloperRoleToSystem?: boolean;
   /**
    * Opt-in: forward `prompt_cache_key` to the upstream `/chat/completions` body.
    * OpenAI-specific extension; strict backends (Groq, Cerebras, etc.) reject unknown
@@ -872,6 +939,12 @@ export interface OcxProviderConfig {
    * with defaults. Key-auth `openai-chat` only.
    */
   transientRetryOn5xx?: TransientRetryPolicy;
+  /**
+   * Opt-in replacement of a native Responses send that died while the caller had observed
+   * nothing (`providers.<name>.retryOnReset`). Disabled unless present; a bare `{}` opts in
+   * with defaults. Native Responses sends only, and only for self-contained requests.
+   */
+  retryOnReset?: ResetReplayPolicy;
   /**
    * Model ids whose OpenAI-compatible chat endpoint accepts `reasoning_split: true` and returns
    * thinking separately in `reasoning_content` / `reasoning_details` instead of visible content.
diff --git a/src/types/request.ts b/src/types/request.ts
index 73bc671c8c2..7a73eaa5987 100644
--- a/src/types/request.ts
+++ b/src/types/request.ts
@@ -210,8 +210,34 @@ export interface OcxVideoContent {
   videoUrl: string;
 }
 
-/** A user/developer message content part: text or native media. */
-export type OcxContentPart = OcxTextContent | OcxImageContent | OcxVideoContent;
+/**
+ * An attached document carried as bytes rather than as a description of itself.
+ *
+ * Both inbound parsers used to reduce an attachment to a title before any adapter ran, so no
+ * adapter could forward one even to a target that has a representation for it, and the caller
+ * could not tell "the model read the document" from "the model was told a document existed"
+ * (#5212).
+ *
+ * `text` is that marker, derived once from what the part knows and kept on the part itself.
+ * Every text-only consumer in the tree reaches a `.text` fallback for a part it does not
+ * recognize, so carrying it here means a wire with no document representation still states the
+ * attachment instead of emitting `undefined` or a mislabelled `[video]`. Only the wires that
+ * have a counterpart read `data`.
+ */
+export interface OcxDocumentContent {
+  type: "document";
+  /** `[document: name]` marker, for every wire with no document representation. */
+  text: string;
+  /** IANA media type of the payload, for example `application/pdf`. */
+  mediaType: string;
+  /** Base64 payload with no `data:` prefix. */
+  data: string;
+  /** The document's own name: an Anthropic document title or a Chat file part's filename. */
+  filename?: string;
+}
+
+/** A user/developer message content part: text, native media, or an attached document. */
+export type OcxContentPart = OcxTextContent | OcxImageContent | OcxVideoContent | OcxDocumentContent;
 
 export interface OcxThinkingContent {
   type: "thinking";
diff --git a/src/types/tools.ts b/src/types/tools.ts
index 83decd85b14..70d777d7491 100644
--- a/src/types/tools.ts
+++ b/src/types/tools.ts
@@ -3,6 +3,12 @@ export interface OcxTool {
   description: string;
   parameters: Record<string, unknown>;
   strict?: boolean;
+  /**
+   * Anthropic `tools[*].allowed_callers`: which callers may invoke this tool. Carried rather
+   * than diagnosed, because rebuilding the declaration without it hands the model a tool the
+   * caller had restricted and returns a normal response (#5210).
+   */
+  allowedCallers?: string[];
   /** MCP namespace (e.g. "mcp__context7") for tools flattened out of a Responses "namespace" tool. */
   namespace?: string;
   /** Freeform/custom tool (e.g. apply_patch): the model's call must be relayed as a custom_tool_call. */
@@ -31,6 +37,19 @@ export function namespacedToolName(namespace: string | undefined, name: string):
   return namespace ? `${namespace}__${name}` : name;
 }
 
+/**
+ * Whether a declaration actually narrows who may call the tool.
+ *
+ * `["direct"]` is the state every unrestricted tool is already in, so treating it as a
+ * restriction would refuse ordinary traffic. Mirrors the `caller_mode` predicate in
+ * src/claude/compatibility.ts, which draws the same line.
+ */
+export function toolRestrictsCallers(tool: Pick<OcxTool, "allowedCallers">): boolean {
+  const callers = tool.allowedCallers;
+  if (callers === undefined) return false;
+  return !(callers.length === 1 && callers[0] === "direct");
+}
+
 /**
  * Dotted alias of a namespaced tool's wire name. Some routed providers (observed: muse-spark
  * via opencode-go) echo a namespaced tool call as "<namespace>.<name>" instead of the flattened
diff --git a/src/update/index.ts b/src/update/index.ts
index 2197ef0f34b..a8af29661dc 100644
--- a/src/update/index.ts
+++ b/src/update/index.ts
@@ -9,6 +9,9 @@ import { dirname, join, resolve } from "node:path";
 import { getConfigDir, loadConfig } from "../config";
 import { readPid, readRuntimePort } from "../config/process-state";
 import { pendingTeardownOutstanding } from "../config/pending-teardown";
+import type { ServiceOwnership } from "../service/state";
+import { planUpdateRuntimeHandling } from "./runtime-ownership.mjs";
+import { acquireOwnershipMutationLease } from "../service/ownership-mutation-lease.mjs";
 import { npmInvocation } from "./npm-invocation.mjs";
 import { pnpmInvocation, pnpmInvocationForPath, resolvePnpmCommands } from "./pnpm-invocation.mjs";
 import { detectInstallFromPath } from "./install-detection.mjs";
@@ -26,6 +29,7 @@ import {
 } from "./npm-cache-preflight.mjs";
 import { handoffWindowsTrayForUpdate, planWindowsTrayUpdate } from "./tray-update-plan.mjs";
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
+import { packageVersion } from "../lib/package-version";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
 
 /**
@@ -143,11 +147,7 @@ export function resolvePnpmActiveLauncher(owner: PnpmGlobalOwner): string | null
 }
 
 export function currentVersion(): string {
-  try {
-    return (JSON.parse(readFileSync(join(HERE, "..", "..", "package.json"), "utf8")).version as string) ?? "?";
-  } catch {
-    return "?";
-  }
+  return packageVersion("?");
 }
 
 export function defaultUpdateTag(current: string): Channel {
@@ -320,6 +320,39 @@ export function checkUpdatePackageIntegrity(
   return result;
 }
 
+/**
+ * The recorded runtime owner, in the shape the shared update rule reads.
+ *
+ * Fails CLOSED. A resolution this process could not obtain is not evidence that nobody owns
+ * the runtime, and treating it as such is how an unreadable record reactivates the npm
+ * launcher over a takeover the user consented to.
+ */
+interface RuntimeOwnershipObservation {
+  readonly ownership: ServiceOwnership | null;
+  readonly ownershipUnknown: boolean;
+  readonly subjectToken: string;
+}
+
+async function resolvedRuntimeOwnership(): Promise<RuntimeOwnershipObservation> {
+  try {
+    const { resolveServiceOwnership } = await import("../service");
+    const resolution = resolveServiceOwnership();
+    if (resolution.kind === "owned") return {
+      ownership: resolution.ownership,
+      ownershipUnknown: false,
+      subjectToken: JSON.stringify(["owned", resolution.revision, resolution.ownership]),
+    };
+    if (resolution.kind === "none") return {
+      ownership: null,
+      ownershipUnknown: false,
+      subjectToken: JSON.stringify(["none", resolution.revision]),
+    };
+    return { ownership: null, ownershipUnknown: true, subjectToken: "unknown" };
+  } catch {
+    return { ownership: null, ownershipUnknown: true, subjectToken: "unknown" };
+  }
+}
+
 /**
  * `ocx update` fallback for source checkouts and Bun global installs. npm and pnpm global installs
  * are updated in the Node bin launcher before Bun starts, so Windows does not replace the running
@@ -385,6 +418,18 @@ export async function runUpdate(): Promise<void> {
     const { isServiceInstalled } = await import("../service");
     serviceWasInstalled = isServiceInstalled();
   } catch { /* best-effort */ }
+  // What this update may do to the runtime. A desktop takeover vetoes both the stop and the
+  // service refresh below; see `planUpdateRuntimeHandling` for why each half is wrong.
+  const initialOwnership = await resolvedRuntimeOwnership();
+  const runtimePlan = planUpdateRuntimeHandling({
+    ...initialOwnership,
+    serviceInstalled: serviceWasInstalled,
+  });
+  if (runtimePlan.notice) console.log(runtimePlan.notice);
+  if (!runtimePlan.mayReplacePackage) {
+    console.error("⚠️  Update stopped before tray handoff, runtime stop, or package replacement because runtime ownership is unknown.");
+    process.exit(1);
+  }
   let trayWasInstalled = false;
   let trayWasRunning = false;
   if (process.platform === "win32") {
@@ -432,7 +477,7 @@ export async function runUpdate(): Promise<void> {
   // silently skips the recovery the receipt was written to trigger (#3008).
   // Full `ocx stop` semantics (drain, service stop, restore).
   let stopAttempted = false;
-  if (serviceWasInstalled || readPid() || readRuntimePort() || pendingTeardownOutstanding()) {
+  if (runtimePlan.mayStopRuntime && (serviceWasInstalled || readPid() || readRuntimePort() || pendingTeardownOutstanding())) {
     stopAttempted = true;
     console.log("⏹  Stopping the running proxy before updating...");
     const stopStdio = updateChildStdio();
@@ -493,26 +538,45 @@ export async function runUpdate(): Promise<void> {
     }
   }
 
-  console.log(`Updating${latest ? ` to v${latest}` : ""}…\n$ ${bin} ${cmdArgs.join(" ")}`);
-
   const installStdio = updateChildStdio();
-  // Every post-update action below receives this path. For pnpm it is replaced only
-  // by a path returned after tree+shim verification; on rollback, activePath is
-  // likewise returned only after the old group has been verified again.
-  let postUpdateLauncher = join(packageRoot(), "bin", "ocx.mjs");
-  // The pnpm owner preflight has verified this package tree and global group. Keep that exact
-  // package path as the recovery starting point; the path returned by the update transaction
-  // replaces it only after post-update tree+shim verification succeeds.
-  if (installer === "pnpm" && owner) {
-    postUpdateLauncher = join(owner.packagePath, "bin", "ocx.mjs");
-  }
+  let postUpdateLauncher = installer === "pnpm" && owner
+    ? join(owner.packagePath, "bin", "ocx.mjs")
+    : join(packageRoot(), "bin", "ocx.mjs");
   let postUpdateLauncherUsable = true;
   let r: {
     status: number | null;
     signal?: NodeJS.Signals | null;
     stdout?: string | Buffer | null;
     stderr?: string | Buffer | null;
-  };
+  } | null = null;
+  const { serviceStatePaths } = await import("../service");
+  const replacementLease = acquireOwnershipMutationLease(serviceStatePaths());
+  let replacementRefusal: string | null = null;
+  try {
+  // Ownership can change while registry and stop work is in flight. Unknown at this exact
+  // boundary blocks replacement; a confirmed desktop claim still permits updating the idle
+  // npm installation while leaving the bundled sidecar alone.
+  const replacementOwnership = await resolvedRuntimeOwnership();
+  const replacementPlan = planUpdateRuntimeHandling({
+    ...replacementOwnership,
+    serviceInstalled: serviceWasInstalled,
+  });
+  const replacementLiveness = runtimePlan.mayStopRuntime
+    ? (await proxyIdentityAt(capturedListen.port, { hostname: capturedListen.hostname })
+        ? "live"
+        : probeProxyLiveness(capturedListen.port, capturedListen.hostname))
+    : "dead";
+  if (replacementOwnership.subjectToken !== initialOwnership.subjectToken
+    || !replacementPlan.mayReplacePackage
+    || replacementLiveness !== "dead") {
+    replacementRefusal = replacementPlan.notice
+      ?? (replacementLiveness === "live"
+        ? "⚠️  Update stopped because a proxy became live after the stop decision; rerun from the beginning."
+        : "⚠️  Update stopped because runtime ownership or liveness changed after the stop decision; rerun from the beginning.");
+  } else {
+  console.log(`Updating${latest ? ` to v${latest}` : ""}…\n$ ${bin} ${cmdArgs.join(" ")}`);
+
+  // Every post-update action below receives the verified active launcher.
   if (installer === "pnpm") {
     let update: ReturnType<typeof runPnpmGlobalUpdate>;
     try {
@@ -560,7 +624,26 @@ export async function runUpdate(): Promise<void> {
       ...target.options,
     });
   }
-  if (installStdio === "pipe") logSpawnOutput("", r);
+  if (r && installStdio === "pipe") logSpawnOutput("", r);
+  }
+  } finally {
+    replacementLease.release();
+  }
+  if (replacementRefusal) {
+    if (trayWasRunning) {
+      try {
+        const { startWindowsTray } = await import("../tray/windows");
+        startWindowsTray();
+      } catch { /* preserve the ownership refusal */ }
+    }
+    console.error(replacementRefusal);
+    process.exit(1);
+  }
+  if (!r) throw new Error("update replacement returned no result");
+  const postInstallPlan = planUpdateRuntimeHandling({
+    ...(await resolvedRuntimeOwnership()),
+    serviceInstalled: serviceWasInstalled,
+  });
   if (r.status === 0) {
     console.log(`\n✅ Updated${latest ? ` to v${latest}` : ""}.`);
     // Re-enter through the verified active package launcher. This keeps the Codex
@@ -591,7 +674,7 @@ export async function runUpdate(): Promise<void> {
     // The stop above unloaded any managed service; repair it with the NEW files
     // (spawn the fresh cli.ts so updated code writes the baked paths) so a
     // launchd/schtasks/systemd user isn't left with the background proxy down.
-    if (serviceWasInstalled) {
+    if (postInstallPlan.mayRestoreService) {
       console.log("🔁 Refreshing the background service with the updated files...");
       const { serviceReinstallArgs } = await import("../service");
       const { reclaimListenPort } = await import("../server/port-reclaim");
@@ -641,6 +724,17 @@ export async function runUpdate(): Promise<void> {
               ? `   Run 'ocx service repair', then 'ocx start --port ${capturedListen.port}'.`
               : `   Run 'ocx service repair' to see the reason, then 'ocx start --port ${capturedListen.port}'.`);
           } else {
+            // Re-read rather than reuse the plan from before the package install: the app can
+            // claim the runtime during an update that takes minutes, and the refusal the
+            // repair above just returned is indistinguishable from any other failure here.
+            const nowOwned = planUpdateRuntimeHandling({
+              ...(await resolvedRuntimeOwnership()),
+              serviceInstalled: true,
+            });
+            if (!nowOwned.mayStopRuntime) {
+              console.warn(nowOwned.notice ?? "⚠️  The background runtime is owned elsewhere; not starting a second proxy.");
+              return;
+            }
             console.warn(
               serviceRefreshed
                 ? "⚠️  Service refresh left a non-viable manager (stale or missing assets) — starting the proxy directly instead."
@@ -668,20 +762,20 @@ export async function runUpdate(): Promise<void> {
         if (prevBake === undefined) delete process.env.OCX_BAKE_PORT;
         else process.env.OCX_BAKE_PORT = prevBake;
       }
-    } else {
+    } else if (postInstallPlan.mayStopRuntime) {
       console.log(`Restart the proxy:  ${launcherStartHint(postUpdateLauncher, capturedListen.port)}`);
     }
   } else {
     if (stopAttempted && trayWasRunning && postUpdateLauncherUsable) {
       spawnSync(process.execPath, [postUpdateLauncher, "tray", "start"], { stdio: "ignore", windowsHide: true });
     }
-    if (stopAttempted && serviceWasInstalled && postUpdateLauncherUsable) {
+    if (stopAttempted && postInstallPlan.mayRestoreService && postUpdateLauncherUsable) {
       const service = spawnSync(process.execPath, [postUpdateLauncher, "service", "repair"], {
         stdio: "inherit",
         windowsHide: true,
       });
       if (service.status !== 0) console.warn("⚠️  Previous background service could not be restored; run 'ocx service repair'.");
-    } else if (stopAttempted && postUpdateLauncherUsable) {
+    } else if (stopAttempted && postUpdateLauncherUsable && postInstallPlan.mayStopRuntime) {
       const env = { ...process.env };
       delete env.OCX_SERVICE;
       const child = spawn(process.execPath, [postUpdateLauncher, "start", "--port", String(capturedListen.port)], {
@@ -691,6 +785,8 @@ export async function runUpdate(): Promise<void> {
         env: withProcessRuntimeProvenance(env),
       });
       child.unref();
+    } else if (stopAttempted && !postInstallPlan.mayStopRuntime) {
+      console.warn(postInstallPlan.notice ?? "⚠️  Runtime ownership changed during the update; not starting a second proxy.");
     } else if (stopAttempted) {
       console.error("opencodex: no verified active launcher remains for automatic recovery; reinstall opencodex manually.");
     }
diff --git a/src/update/job.ts b/src/update/job.ts
index 16310cad824..dd8e47748e5 100644
--- a/src/update/job.ts
+++ b/src/update/job.ts
@@ -26,6 +26,7 @@ import { listListenPids, reclaimListenPort, scanListenPids, type ListenPidScan }
 import { dropWindowsTcpRowsForLocalPort } from "../server/windows-tcp-drop";
 import { isOpencodexHealthz, probeHostname, proxyIdentityAt, type HealthzIdentity } from "../server/proxy-liveness";
 import { isServiceInstalled, isServiceViable, readServiceBackend, stopWindows } from "../service";
+import { runUpdateRestartWithOwnershipLease, type ServiceOwnershipResolution } from "./restart-ownership";
 import {
   type Channel,
   type Installer,
@@ -1804,6 +1805,8 @@ export interface GuiUpdateWorkerIo {
   resolvePnpmActiveLauncherFn?: (owner: PnpmGlobalOwner) => string | null;
   /** Restart seams used by focused worker tests; the verified launcher is always injected. */
   restartIo?: RestartIo;
+  /** Resolves who owns the runtime; defaults to the shared service install state. */
+  resolveOwnershipFn?: () => ServiceOwnershipResolution;
   runCommandFn?: (
     job: UpdateJobState,
     bin: string,
@@ -1967,11 +1970,12 @@ export async function runGuiUpdateWorker(
     }
 
     if (restart) {
-      job = updateJob(job, { status: "restarting" }, "Update installed. Restarting proxy...");
-      if (!(await finishGuiUpdateRestart(job, captured, check.installer, {
-        ...io.restartIo,
-        packageLauncherPathFn: () => activeLauncher,
-      }))) return;
+      const outcome = await runUpdateRestartWithOwnershipLease(io.resolveOwnershipFn, async () => {
+        job = updateJob(job!, { status: "restarting" }, "Update installed. Restarting proxy...");
+        return finishGuiUpdateRestart(job!, captured, check.installer, { ...io.restartIo, packageLauncherPathFn: () => activeLauncher });
+      });
+      if (outcome.kind === "veto") { updateJob(job, { status: "succeeded", restarted: false }, outcome.notice); return; }
+      if (!outcome.value) return;
       updateJob(job, { status: "succeeded", restarted: true }, "Restart requested and proxy is healthy.");
       return;
     }
diff --git a/src/update/restart-ownership.ts b/src/update/restart-ownership.ts
new file mode 100644
index 00000000000..32cafee1e6e
--- /dev/null
+++ b/src/update/restart-ownership.ts
@@ -0,0 +1,54 @@
+import { resolveServiceOwnership } from "../service";
+import type { ServiceOwnershipResolution } from "../service";
+import { serviceStatePaths } from "../service/state";
+import {
+  acquireOwnershipMutationLease,
+  OWNERSHIP_MUTATION_LEASE_TOKEN_ENV,
+} from "../service/ownership-mutation-lease.mjs";
+import { planUpdateRuntimeHandling } from "./runtime-ownership.mjs";
+
+export type { ServiceOwnershipResolution };
+
+/**
+ * Why a dashboard update must not restart a runtime it did not stop.
+ *
+ * The worker defaults to restarting. When the package updater it just ran left a
+ * foreign-owned runtime alone — which is the correct behaviour under a desktop takeover —
+ * the sidecar's unchanged pid fails the worker's restart evidence, so it reclaims the port,
+ * runs the repair that now refuses, and falls through to a direct start. The app's runtime
+ * ends up replaced by an npm proxy immediately after the update declined to touch it.
+ *
+ * Returns the line to report, or null when the restart may proceed. It lives beside the
+ * worker rather than inside it because `src/update/job.ts` is one line under the repository
+ * size cap.
+ */
+export function updateRestartVeto(
+  resolve: () => ServiceOwnershipResolution = resolveServiceOwnership,
+): string | null {
+  const owner = resolve();
+  const plan = planUpdateRuntimeHandling({
+    ownership: owner.kind === "owned" ? owner.ownership : null,
+    ownershipUnknown: owner.kind === "unknown",
+    // The restart decision does not refresh the service; only the stop veto is read here.
+    serviceInstalled: false,
+  });
+  if (plan.mayStopRuntime) return null;
+  return plan.notice ?? "The background runtime is owned elsewhere; it was left running.";
+}
+
+export async function runUpdateRestartWithOwnershipLease<T>(
+  resolve: (() => ServiceOwnershipResolution) | undefined,
+  restart: () => Promise<T>,
+): Promise<{ readonly kind: "veto"; readonly notice: string } | { readonly kind: "ran"; readonly value: T }> {
+  const lease = acquireOwnershipMutationLease(serviceStatePaths());
+  const previous = process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+  process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV] = lease.token;
+  try {
+    const veto = updateRestartVeto(resolve);
+    return veto ? { kind: "veto", notice: veto } : { kind: "ran", value: await restart() };
+  } finally {
+    if (previous === undefined) delete process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+    else process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV] = previous;
+    lease.release();
+  }
+}
diff --git a/src/update/runtime-ownership.d.mts b/src/update/runtime-ownership.d.mts
new file mode 100644
index 00000000000..754c3499a4d
--- /dev/null
+++ b/src/update/runtime-ownership.d.mts
@@ -0,0 +1,40 @@
+export declare function planUpdateRuntimeHandling(input: {
+  ownership: { owner: string; installId: string; consentGeneration: number } | null;
+  ownershipUnknown?: boolean;
+  serviceInstalled: boolean;
+}): {
+  mayReplacePackage: boolean;
+  mayStopRuntime: boolean;
+  mayRestoreService: boolean;
+  notice: string | null;
+};
+
+export declare function planStoppedRuntimeRecovery(input: {
+  stopAttempted: boolean;
+  ownership: { owner: string; installId: string; consentGeneration: number } | null;
+  ownershipUnknown?: boolean;
+  sameOwner: boolean;
+  liveness: "live" | "dead" | "unknown";
+  serviceInstalled: boolean;
+  launcherUsable: boolean;
+  hadRuntimeState: boolean;
+}): {
+  action: "none" | "manual" | "service" | "direct";
+  reason: string;
+};
+
+type RuntimeTarget = { port: number; hostname: string };
+type RuntimeLiveness = "live" | "dead" | "unknown";
+
+export declare function inspectPackageRuntimeLiveness(input: {
+  capturedTarget: RuntimeTarget;
+  readCurrentTarget():
+    | { kind: "target"; target: RuntimeTarget }
+    | { kind: "absent" }
+    | { kind: "unknown" };
+  probe(target: RuntimeTarget): RuntimeLiveness;
+}): {
+  current: RuntimeLiveness | "absent";
+  captured: RuntimeLiveness;
+  overall: RuntimeLiveness;
+};
diff --git a/src/update/runtime-ownership.mjs b/src/update/runtime-ownership.mjs
new file mode 100644
index 00000000000..c9eb52e5df8
--- /dev/null
+++ b/src/update/runtime-ownership.mjs
@@ -0,0 +1,122 @@
+/**
+ * Does an update own the runtime it is about to stop and restart?
+ *
+ * Both updaters ask this: `src/update/index.ts` on the Bun path and `bin/ocx.mjs` on the
+ * npm and pnpm path. It lives here as plain ESM for the same reason `stop-decision.mjs`
+ * does — the Node launcher has to be able to import it, and two lanes deciding the same
+ * situation separately is how a fix ships on one side only.
+ */
+
+/**
+ * Decide how an update treats a runtime it may not own.
+ *
+ * `ocx update` replaces the package's files and then puts the proxy back: it stops the
+ * running server first, and afterwards runs `ocx service repair` to re-register and restart
+ * the background service. Under a desktop owner both halves are wrong. The running server is
+ * the app's own bundled sidecar rather than anything this package installed, so stopping it
+ * takes down a runtime the update has no way to bring back; and the repair would re-enable
+ * the npm launcher the takeover superseded, which is the exact reactivation the ownership
+ * marker exists to prevent. Neither half is needed either — the app updates its own runtime.
+ *
+ * The service registration itself is untouched in every case. It is kept by decision, not by
+ * accident, so a user who later runs `ocx service install` gets their npm service back.
+ *
+ * THE COST OF A STALE MARKER. This reads the recorded claim, not liveness. An app deleted
+ * without releasing ownership leaves a marker behind, and an update then declines to stop or
+ * refresh a runtime no app is managing any more. That is the orphan-recovery cost the
+ * two-record ownership design accepted; `ocx service install` clears the marker and restores
+ * the ordinary path.
+ *
+ * The three returned flags are separate authorities, not commands. In particular, leaving
+ * a runtime running is not permission to replace the package it may be executing from.
+ *
+ * A recorded desktop claim does not prove which binary is live. Until the bundled resolver
+ * carries installation identity, it therefore blocks package replacement as well as stop and
+ * restoration; the notice tells a stale-marker user how to take ownership back explicitly.
+ *
+ * @param {{ ownership: { owner: string, installId: string, consentGeneration: number } | null, ownershipUnknown?: boolean, serviceInstalled: boolean }} input
+ * @returns {{ mayReplacePackage: boolean, mayStopRuntime: boolean, mayRestoreService: boolean, notice: string | null }}
+ */
+export function planUpdateRuntimeHandling({ ownership, ownershipUnknown = false, serviceInstalled }) {
+  // Unreadable, malformed or contradictory is not "nobody owns it". Reading it that way is
+  // how a permissions error reactivates the npm launcher over a consented takeover.
+  if (ownershipUnknown) {
+    return {
+      mayReplacePackage: false,
+      mayStopRuntime: false,
+      mayRestoreService: false,
+      notice: "⚠️  The background runtime's recorded owner could not be determined, so it was "
+        + "left running and the service registration was not touched. "
+        + "Run 'ocx service install' to re-register the service and take the runtime back.",
+    };
+  }
+  // Any owner that is not this CLI. Reading it this way rather than testing for "desktop"
+  // keeps a third kind of owner from silently falling into the branch that touches the npm
+  // registration.
+  if (ownership && ownership.owner !== "cli") {
+    return {
+      // A claim does not prove which binary is live. A stale desktop marker beside a
+      // manually started npm proxy would otherwise replace that proxy's executing files.
+      mayReplacePackage: false,
+      mayStopRuntime: false,
+      mayRestoreService: false,
+      notice: `🖥️  The desktop app owns the background runtime (install ${ownership.installId}, `
+        + `consent generation ${ownership.consentGeneration}). It and the npm package were left unchanged, and the `
+        + "service registration was neither re-enabled nor restarted. "
+        + "If the desktop app is gone, run 'ocx service install' to take the runtime back.",
+    };
+  }
+  return {
+    mayReplacePackage: true,
+    mayStopRuntime: true,
+    mayRestoreService: serviceInstalled,
+    notice: null,
+  };
+}
+
+/** Decide recovery after this updater already stopped the prior CLI-owned runtime. */
+export function planStoppedRuntimeRecovery({
+  stopAttempted,
+  ownership,
+  ownershipUnknown = false,
+  sameOwner,
+  liveness,
+  serviceInstalled,
+  launcherUsable,
+  hadRuntimeState,
+}) {
+  if (!stopAttempted) return { action: "none", reason: "not-stopped" };
+  if (ownershipUnknown) return { action: "manual", reason: "ownership-unknown" };
+  if (!sameOwner || (ownership && ownership.owner !== "cli")) {
+    return { action: "none", reason: "ownership-transferred" };
+  }
+  if (liveness !== "dead") return { action: "manual", reason: `runtime-${liveness}` };
+  if (!launcherUsable) return { action: "manual", reason: "launcher-unavailable" };
+  if (serviceInstalled) return { action: "service", reason: "same-cli-owner" };
+  if (hadRuntimeState) return { action: "direct", reason: "same-cli-owner" };
+  return { action: "none", reason: "nothing-to-restore" };
+}
+
+/**
+ * Re-read the current package runtime before probing. The result keeps an absent current
+ * record distinct from a dead captured endpoint while still projecting one fail-closed
+ * liveness verdict for replacement and recovery decisions.
+ */
+export function inspectPackageRuntimeLiveness({ capturedTarget, readCurrentTarget, probe }) {
+  const currentTarget = readCurrentTarget();
+  const observations = new Map();
+  const inspect = target => {
+    const key = `${target.hostname}:${target.port}`;
+    if (!observations.has(key)) observations.set(key, probe(target));
+    return observations.get(key);
+  };
+  // Probe the fresh record first. It is the address a replacement runtime may have
+  // published while the updater was waiting on the ownership lease.
+  const current = currentTarget.kind === "target" ? inspect(currentTarget.target) : currentTarget.kind;
+  const captured = inspect(capturedTarget);
+  const verdicts = current === "absent" ? [captured] : [current, captured];
+  const overall = verdicts.includes("live")
+    ? "live"
+    : verdicts.includes("unknown") ? "unknown" : "dead";
+  return { current, captured, overall };
+}
diff --git a/src/usage/attempt-delivery.ts b/src/usage/attempt-delivery.ts
new file mode 100644
index 00000000000..c1c011747f8
--- /dev/null
+++ b/src/usage/attempt-delivery.ts
@@ -0,0 +1,198 @@
+/**
+ * Counting what an attempt delivered, without recording what it said.
+ *
+ * The recorder below is bound to a request-scoped object and reaches the CURRENT attempt through
+ * a callback rather than holding one. An attempt can be rotated mid-request -- a key-account
+ * change seals the old one and starts a fresh one -- and a recorder holding a reference would
+ * keep crediting frames to an attempt that had already been finalized and snapshotted.
+ *
+ * Nothing here reads a payload's content. `semanticBytes` is a length; the event classification
+ * reads only a frame's type name and an item's type name, both of which are protocol constants.
+ */
+import type { AttemptDeliverySummary } from "./telemetry-contract";
+
+export interface AttemptDeliveryTarget {
+  deliverySummary?: AttemptDeliverySummary;
+}
+
+export interface RelayedEventObservation {
+  semanticBytes?: number;
+  sideEffect?: boolean;
+  terminal?: boolean;
+}
+
+export interface AttemptDeliveryRecorder {
+  noteAdapterEvent(): void;
+  noteRelayedEvent(observation?: RelayedEventObservation): void;
+  noteBufferedDelivery(body: Record<string, unknown>): void;
+}
+
+export function createAttemptDeliverySummary(): AttemptDeliverySummary {
+  return { adapterEvents: 0, relayedEvents: 0, semanticBytes: 0, sideEffectEvents: 0, terminalEvents: 0 };
+}
+
+/**
+ * Saturating addition.
+ *
+ * A counter that wraps or drifts into a non-integer is worse than one that stops: the row would
+ * be dropped by the normalizer and the whole summary lost. A long-lived stream that somehow
+ * reaches the safe-integer ceiling keeps a readable, if pinned, number.
+ */
+function bump(current: number, by: number): number {
+  if (!Number.isFinite(by) || by <= 0) return current;
+  return Math.min(Number.MAX_SAFE_INTEGER, current + Math.floor(by));
+}
+
+const SEMANTIC_DELTA_EVENTS: ReadonlySet<string> = new Set([
+  "response.output_text.delta",
+  "response.reasoning_summary_text.delta",
+  "response.reasoning_text.delta",
+  "response.function_call_arguments.delta",
+  "response.custom_tool_call_input.delta",
+]);
+
+const TERMINAL_EVENTS: ReadonlySet<string> = new Set([
+  "response.completed",
+  "response.incomplete",
+  "response.failed",
+]);
+
+const SIDE_EFFECT_ITEM_TYPES: ReadonlySet<string> = new Set([
+  "function_call",
+  "custom_tool_call",
+  "web_search_call",
+]);
+
+/**
+ * What one relayed frame contributes, read from its type name alone.
+ *
+ * A side effect is counted when the item STARTS, not on its argument fragments and not again on
+ * the matching done frame, so one tool call is one effect however many deltas carried its
+ * arguments.
+ */
+export function classifyRelayedResponseEvent(
+  name: string,
+  data: Record<string, unknown>,
+): RelayedEventObservation {
+  const observation: RelayedEventObservation = {};
+  if (SEMANTIC_DELTA_EVENTS.has(name) && typeof data.delta === "string") {
+    observation.semanticBytes = Buffer.byteLength(data.delta, "utf8");
+  }
+  if (name === "response.output_item.added") {
+    const item = data.item;
+    const type = item !== null && typeof item === "object"
+      ? (item as Record<string, unknown>).type
+      : undefined;
+    if (typeof type === "string" && SIDE_EFFECT_ITEM_TYPES.has(type)) observation.sideEffect = true;
+  }
+  if (TERMINAL_EVENTS.has(name)) observation.terminal = true;
+  return observation;
+}
+
+/**
+ * What one buffered response body delivered.
+ *
+ * A non-streaming turn has no frames: the whole answer reaches the client as one JSON body. Read
+ * naively that looks like total relay loss -- adapter events counted, nothing relayed -- which is
+ * precisely the signal these counters exist to raise, so a buffered response would raise it on
+ * every request and make it worthless. Everything the adapter produced DID reach the client here;
+ * it arrived in one piece. So the relayed total is set to the adapter total rather than left at
+ * zero, and the semantic facts are read from the body that was built.
+ *
+ * Fields are read defensively and by name. Keying this on the adapter event union would make a
+ * member added later a merge-time exhaustiveness failure in a counter that does not need one.
+ */
+function observeBufferedBody(body: Record<string, unknown>): { semanticBytes: number; sideEffects: number } {
+  const output = Array.isArray(body.output) ? body.output : [];
+  let semanticBytes = 0;
+  let sideEffects = 0;
+  for (const entry of output) {
+    if (entry === null || typeof entry !== "object") continue;
+    const item = entry as Record<string, unknown>;
+    if (typeof item.type === "string" && SIDE_EFFECT_ITEM_TYPES.has(item.type)) sideEffects += 1;
+    if (typeof item.arguments === "string") semanticBytes += Buffer.byteLength(item.arguments, "utf8");
+    const content = Array.isArray(item.content) ? item.content : [];
+    for (const part of content) {
+      if (part === null || typeof part !== "object") continue;
+      const text = (part as Record<string, unknown>).text;
+      if (typeof text === "string") semanticBytes += Buffer.byteLength(text, "utf8");
+    }
+  }
+  return { semanticBytes, sideEffects };
+}
+
+const recordersByScope = new WeakMap<object, AttemptDeliveryRecorder>();
+
+/**
+ * Bind a recorder to a request-scoped object.
+ *
+ * The scope is the request's translator budget, which every bridge on the delivery path already
+ * receives. Reusing it avoids threading a new parameter through six call sites where any one of
+ * them silently defaulting would leave a transport uncounted -- the failure mode that made
+ * `locallyAnswered` travel on the attempt instead of as an argument.
+ */
+export function bindAttemptDeliveryRecorder(
+  scope: object,
+  currentAttempt: () => AttemptDeliveryTarget | undefined,
+): AttemptDeliveryRecorder {
+  const summaryFor = (): AttemptDeliverySummary | undefined => {
+    const attempt = currentAttempt();
+    if (!attempt) return undefined;
+    return attempt.deliverySummary ??= createAttemptDeliverySummary();
+  };
+  const recorder: AttemptDeliveryRecorder = {
+    noteAdapterEvent(): void {
+      const summary = summaryFor();
+      if (summary) summary.adapterEvents = bump(summary.adapterEvents, 1);
+    },
+    noteRelayedEvent(observation): void {
+      const summary = summaryFor();
+      if (!summary) return;
+      summary.relayedEvents = bump(summary.relayedEvents, 1);
+      if (observation?.semanticBytes) summary.semanticBytes = bump(summary.semanticBytes, observation.semanticBytes);
+      if (observation?.sideEffect) summary.sideEffectEvents = bump(summary.sideEffectEvents, 1);
+      if (observation?.terminal) summary.terminalEvents = bump(summary.terminalEvents, 1);
+    },
+    noteBufferedDelivery(body): void {
+      const summary = summaryFor();
+      if (!summary) return;
+      const observed = observeBufferedBody(body);
+      summary.relayedEvents = Math.max(summary.relayedEvents, summary.adapterEvents);
+      summary.semanticBytes = bump(summary.semanticBytes, observed.semanticBytes);
+      summary.sideEffectEvents = bump(summary.sideEffectEvents, observed.sideEffects);
+      summary.terminalEvents = bump(summary.terminalEvents, 1);
+    },
+  };
+  recordersByScope.set(scope, recorder);
+  return recorder;
+}
+
+export function attemptDeliveryRecorder(scope: object | undefined): AttemptDeliveryRecorder | undefined {
+  return scope ? recordersByScope.get(scope) : undefined;
+}
+
+/**
+ * A persisted summary is trusted only when all five counts are non-negative safe integers.
+ *
+ * The whole record is dropped rather than repaired: a partially trusted count is a number an
+ * operator would compare against another number, and half a summary is how a loss signal turns
+ * into a false one.
+ */
+export function normalizeAttemptDeliverySummary(value: unknown): AttemptDeliverySummary | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const raw = value as Record<string, unknown>;
+  const counts = createAttemptDeliverySummary();
+  for (const key of Object.keys(counts) as Array<keyof AttemptDeliverySummary>) {
+    const count = raw[key];
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) return undefined;
+    counts[key] = count;
+  }
+  return counts;
+}
+
+/** A detached copy, so a snapshotted attempt cannot keep counting after it was finalized. */
+export function cloneAttemptDeliverySummary(
+  summary: AttemptDeliverySummary | undefined,
+): AttemptDeliverySummary | undefined {
+  return summary ? { ...summary } : undefined;
+}
diff --git a/src/usage/cache-diagnostic.ts b/src/usage/cache-diagnostic.ts
new file mode 100644
index 00000000000..cd087f6db53
--- /dev/null
+++ b/src/usage/cache-diagnostic.ts
@@ -0,0 +1,305 @@
+/** Privacy-bounded, process-local cache diagnostics. Enable with OPENCODEX_CACHE_DEBUG=1. */
+import { createHmac, randomBytes } from "node:crypto";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CODEX_AFFINITY_DEBUG_SAFE_HEADERS } from "../codex/affinity-debug";
+import { getConfigDir } from "../config";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+import type { CacheTelemetryProvenance } from "./log";
+
+const CACHE_DEBUG_KEY = randomBytes(32);
+const MAX_BLOCKS = 128;
+const MAX_DRAFTS = 512;
+export const CACHE_DEBUG_MAX_LINES = 200;
+export const CACHE_DEBUG_KEEP_LINES = 100;
+
+export type PromptCacheKeySource = "caller" | "metadata-derived" | "system-derived" | "proxy-synthesized";
+export interface TaggedPresence { present: boolean; tag?: string; source?: PromptCacheKeySource }
+export interface TaggedSequence { present: boolean; count: number; tags: string[]; truncated?: true }
+export interface PrefixFingerprint {
+  instructions: TaggedSequence;
+  tools: TaggedSequence;
+  messages: TaggedSequence;
+}
+export interface CacheDiagnosticDraft {
+  promptCacheKey?: { inbound?: TaggedPresence; outbound?: TaggedPresence };
+  session?: { inboundHeader?: TaggedPresence; outboundHeader?: TaggedPresence };
+  prefix?: { inbound?: PrefixFingerprint; outbound?: PrefixFingerprint };
+}
+
+export interface CacheDiagnosticFinalFacts {
+  requestId: string;
+  logicalRequestId?: string;
+  protocol: "responses" | "chat" | "messages";
+  provider: string;
+  model: string;
+  accountLogLabel?: string;
+  affinityMove?: string;
+  affinityReason?: string;
+  /**
+   * The cache counter exactly as the upstream usage object carried it, read before any
+   * client-wire defaulting. Undefined means the upstream object had no cache counter at
+   * all, which keeps a measured zero distinct from an absent-then-defaulted zero.
+   */
+  rawCacheCounterValue?: number;
+  normalizedCacheValue?: number;
+  cacheProvenance: CacheTelemetryProvenance;
+  draft?: CacheDiagnosticDraft;
+}
+
+const drafts = new Map<string, CacheDiagnosticDraft>();
+const bodyDrafts = new WeakMap<object, CacheDiagnosticDraft>();
+
+export function isCacheDiagnosticEnabled(): boolean {
+  return process.env.OPENCODEX_CACHE_DEBUG === "1";
+}
+
+export function cacheDiagnosticPath(): string {
+  return join(getConfigDir(), "cache-debug.jsonl");
+}
+
+function tag(domain: string, value: string): string {
+  return createHmac("sha256", CACHE_DEBUG_KEY)
+    .update(domain).update("\0").update(value).digest("hex").slice(0, 12);
+}
+
+export function tagCacheDiagnosticValue(domain: string, value: string): string {
+  return tag(`cache-debug:${domain}`, value);
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const record = value as Record<string, unknown>;
+  return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+}
+
+function taggedPresence(value: unknown, domain: string, source?: PromptCacheKeySource): TaggedPresence {
+  if (typeof value !== "string" || value.length === 0) return { present: false };
+  return { present: true, tag: tag(domain, value), ...(source ? { source } : {}) };
+}
+
+function sessionPresence(headers: Headers | HeadersInit): TaggedPresence {
+  const normalized = headers instanceof Headers ? headers : new Headers(headers);
+  const values = CODEX_AFFINITY_DEBUG_SAFE_HEADERS.flatMap(name => {
+    const value = normalized.get(name);
+    return value === null ? [] : [[name, value] as const];
+  });
+  return values.length === 0
+    ? { present: false }
+    : { present: true, tag: tag("cache-debug:session-headers", canonicalJson(values)) };
+}
+
+function sequence(blocks: unknown[], domain: string): TaggedSequence {
+  const bounded = blocks.slice(0, MAX_BLOCKS);
+  return {
+    present: blocks.length > 0,
+    count: blocks.length,
+    tags: bounded.map(block => tag(domain, canonicalJson(block))),
+    ...(blocks.length > MAX_BLOCKS ? { truncated: true as const } : {}),
+  };
+}
+
+function requestBlocks(body: Record<string, unknown>): { instructions: unknown[]; messages: unknown[] } {
+  const instructions = body.instructions;
+  // The spread is load-bearing: an array-valued instructions field must be copied, never
+  // aliased, because the pushes below would otherwise mutate the live request body that
+  // the adapter is about to serialize upstream.
+  const instructionRows = instructions === undefined || instructions === null
+    ? [] : Array.isArray(instructions) ? [...instructions] : [instructions];
+  const input = Array.isArray(body.input) ? body.input : Array.isArray(body.messages) ? body.messages : [];
+  const messages: unknown[] = [];
+  for (const block of input) {
+    if (block && typeof block === "object" && !Array.isArray(block)) {
+      const row = block as Record<string, unknown>;
+      if (row.role === "system" || row.role === "developer") {
+        const content = row.content;
+        instructionRows.push(...(Array.isArray(content) ? content : [content]));
+        continue;
+      }
+    }
+    messages.push(block);
+  }
+  return { instructions: instructionRows, messages };
+}
+
+export function prefixFingerprint(body: unknown): PrefixFingerprint {
+  const record = body && typeof body === "object" && !Array.isArray(body)
+    ? body as Record<string, unknown> : {};
+  const tools = Array.isArray(record.tools) ? record.tools : [];
+  const blocks = requestBlocks(record);
+  return {
+    instructions: sequence(blocks.instructions, "cache-debug:prefix:instructions"),
+    tools: sequence(tools, "cache-debug:prefix:tools"),
+    messages: sequence(blocks.messages, "cache-debug:prefix:messages"),
+  };
+}
+
+function firstDivergence(inbound: PrefixFingerprint, outbound: PrefixFingerprint):
+  { section: "instructions" | "tools" | "messages"; index: number } | undefined {
+  for (const section of ["instructions", "tools", "messages"] as const) {
+    const before = inbound[section].tags;
+    const after = outbound[section].tags;
+    const compared = Math.min(before.length, after.length);
+    for (let index = 0; index < compared; index += 1) {
+      if (before[index] !== after[index]) return { section, index };
+    }
+    if (inbound[section].count !== outbound[section].count) return { section, index: compared };
+  }
+  return undefined;
+}
+
+export function observe(requestId: string, observation: Partial<CacheDiagnosticDraft>): CacheDiagnosticDraft {
+  const draft = drafts.get(requestId) ?? {};
+  Object.assign(draft, observation);
+  drafts.delete(requestId);
+  drafts.set(requestId, draft);
+  while (drafts.size > MAX_DRAFTS) drafts.delete(drafts.keys().next().value!);
+  return draft;
+}
+
+export function observeInbound(
+  body: unknown,
+  headers: Headers,
+  source: PromptCacheKeySource = "caller",
+): CacheDiagnosticDraft {
+  if (!isCacheDiagnosticEnabled()) return {};
+  try {
+    const record = body && typeof body === "object" && !Array.isArray(body)
+      ? body as Record<string, unknown> : {};
+    const draft: CacheDiagnosticDraft = {
+      promptCacheKey: { inbound: taggedPresence(record.prompt_cache_key, "cache-debug:prompt-cache-key", source) },
+      session: { inboundHeader: sessionPresence(headers) },
+      prefix: { inbound: prefixFingerprint(body) },
+    };
+    if (body && typeof body === "object") bodyDrafts.set(body, draft);
+    return draft;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Alias a later form of the same request body (for example after previous-response
+ * expansion) to an existing draft, so the outbound observation at the adapter seam can
+ * find it. The inbound fingerprint intentionally stays the literal pre-expansion body.
+ */
+export function rebindCacheDiagnosticBodyAlias(body: unknown, draft: CacheDiagnosticDraft | undefined): void {
+  if (!isCacheDiagnosticEnabled() || !draft) return;
+  if (body && typeof body === "object") bodyDrafts.set(body, draft);
+}
+
+export function observeOutbound(
+  inboundBody: unknown,
+  outboundBody: unknown,
+  headers: HeadersInit,
+  source: PromptCacheKeySource = "proxy-synthesized",
+): void {
+  if (!isCacheDiagnosticEnabled()) return;
+  try {
+    if (!inboundBody || typeof inboundBody !== "object") return;
+    const draft = bodyDrafts.get(inboundBody);
+    if (!draft) return;
+    const record = outboundBody && typeof outboundBody === "object" && !Array.isArray(outboundBody)
+      ? outboundBody as Record<string, unknown> : {};
+    const outbound = taggedPresence(record.prompt_cache_key, "cache-debug:prompt-cache-key", source);
+    const inboundKey = draft.promptCacheKey?.inbound;
+    if (outbound.present && inboundKey && outbound.tag === inboundKey.tag) {
+      outbound.source = inboundKey.source;
+    }
+    (draft.promptCacheKey ??= {}).outbound = outbound;
+    (draft.session ??= {}).outboundHeader = sessionPresence(headers);
+    (draft.prefix ??= {}).outbound = prefixFingerprint(outboundBody);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}
+
+function ensureDir(): void {
+  const dir = getConfigDir();
+  recordOwnedConfigPath(dir, cacheDiagnosticPath());
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
+}
+
+function trimRollingFile(path: string): void {
+  const lines = readFileSync(path, "utf8").split(/\r?\n/).filter(Boolean);
+  if (lines.length <= CACHE_DEBUG_MAX_LINES) return;
+  writeFileSync(path, `${lines.slice(-CACHE_DEBUG_KEEP_LINES).join("\n")}\n`, { encoding: "utf8", mode: 0o600 });
+  try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+}
+
+export function appendFinalCacheDiagnostic(facts: CacheDiagnosticFinalFacts): void {
+  if (!isCacheDiagnosticEnabled()) return;
+  try {
+    const draft = facts.draft ? observe(facts.requestId, facts.draft) : drafts.get(facts.requestId) ?? {};
+    drafts.delete(facts.requestId);
+    const inboundKey = draft.promptCacheKey?.inbound;
+    const outboundKey = draft.promptCacheKey?.outbound;
+    const inboundPrefix = draft.prefix?.inbound ?? prefixFingerprint(undefined);
+    const outboundPrefix = draft.prefix?.outbound ?? prefixFingerprint(undefined);
+    const record = {
+      version: 1 as const,
+      ts: Date.now(),
+      requestId: facts.requestId,
+      ...(facts.logicalRequestId ? { logicalRequestId: facts.logicalRequestId } : {}),
+      protocol: facts.protocol,
+      provider: facts.provider,
+      model: facts.model,
+      promptCacheKey: {
+        inbound: inboundKey ?? { present: false },
+        outbound: outboundKey ?? { present: false },
+        ...(inboundKey?.present && outboundKey?.present ? { equal: inboundKey.tag === outboundKey.tag } : {}),
+      },
+      session: {
+        inboundHeader: draft.session?.inboundHeader ?? { present: false },
+        outboundHeader: draft.session?.outboundHeader ?? { present: false },
+      },
+      prefix: {
+        inbound: inboundPrefix,
+        outbound: outboundPrefix,
+        ...(firstDivergence(inboundPrefix, outboundPrefix)
+          ? { firstDivergentBlock: firstDivergence(inboundPrefix, outboundPrefix) }
+          : {}),
+      },
+      route: {
+        provider: facts.provider,
+        model: facts.model,
+        ...(facts.accountLogLabel
+          ? { accountTag: tag("cache-debug:account-log-label", facts.accountLogLabel) }
+          : {}),
+        ...(facts.affinityMove ? { affinityMove: facts.affinityMove } : {}),
+        ...(facts.affinityReason ? { affinityReason: facts.affinityReason } : {}),
+      },
+      cache: {
+        rawUpstream: facts.rawCacheCounterValue !== undefined
+          ? { present: true, value: facts.rawCacheCounterValue }
+          : { present: false },
+        normalized: {
+          present: facts.normalizedCacheValue !== undefined,
+          ...(facts.normalizedCacheValue !== undefined ? { value: facts.normalizedCacheValue } : {}),
+          provenance: facts.cacheProvenance,
+        },
+      },
+    };
+    ensureDir();
+    const path = cacheDiagnosticPath();
+    appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+    if (existsSync(path)) trimRollingFile(path);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}
+
+const CACHE_DIAGNOSTIC_HOOK = Symbol.for("opencodex.cache-diagnostic.v1");
+interface CacheDiagnosticHooks {
+  observeInbound(body: unknown, headers: Headers, source: PromptCacheKeySource): CacheDiagnosticDraft;
+  rebind(body: unknown, draft: CacheDiagnosticDraft | undefined): void;
+  finalize(facts: CacheDiagnosticFinalFacts): void;
+}
+(globalThis as Record<symbol, CacheDiagnosticHooks | undefined>)[CACHE_DIAGNOSTIC_HOOK] = {
+  observeInbound,
+  rebind: rebindCacheDiagnosticBodyAlias,
+  finalize: appendFinalCacheDiagnostic,
+};
diff --git a/src/usage/expected-prices.ts b/src/usage/expected-prices.ts
index 351b6a00d27..5ab640d88a0 100644
--- a/src/usage/expected-prices.ts
+++ b/src/usage/expected-prices.ts
@@ -286,6 +286,7 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   // kimi-code = API key surface (expected list price, not actual billing).
   { provider: "kimi", modelId: "k3", cost4: KIMI_K3, source: KIMI_PRICING, verifiedAt: "2026-07-20", status: "verified-derived" },
   { provider: "kimi", modelId: "k3[1m]", cost4: KIMI_K3, source: `derived: k3 (official docs: k3[1m] is the 1M-context compat notation for k3) ${KIMI_PRICING}`, verifiedAt: "2026-07-20", status: "verified-derived" },
+  { provider: "kimi", modelId: "k3-256k", cost4: KIMI_K3, source: `derived: k3 (verified live 260921: same K3 served under the explicit ceiling id; identical prompt scaffold as bare k3) ${KIMI_PRICING}`, verifiedAt: "2026-09-21", status: "verified-derived" },
   { provider: "kimi", modelId: "kimi-k2.7-code", cost4: KIMI_K27_CODE, source: KIMI_PRICING, verifiedAt: "2026-07-20", status: "verified-derived" },
   { provider: "kimi", modelId: "kimi-k2.7-code-highspeed", cost4: KIMI_K27_CODE_HIGHSPEED, source: KIMI_PRICING, verifiedAt: "2026-07-20", status: "verified-derived" },
   { provider: "kimi", modelId: "kimi-k2.6", cost4: KIMI_K26, source: KIMI_PRICING, verifiedAt: "2026-07-20", status: "verified-derived" },
@@ -298,6 +299,7 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   { provider: "moonshot", modelId: "kimi-k2.5", cost4: KIMI_K25, source: KIMI_PRICING, verifiedAt: "2026-07-20", status: "verified-derived" },
   { provider: "kimi-code", modelId: "k3", cost4: KIMI_K3, source: KIMI_PRICING, verifiedAt: "2026-07-20", status: "verified-derived" },
   { provider: "kimi-code", modelId: "k3[1m]", cost4: KIMI_K3, source: `derived: k3 ${KIMI_PRICING}`, verifiedAt: "2026-07-20", status: "verified-derived" },
+  { provider: "kimi-code", modelId: "k3-256k", cost4: KIMI_K3, source: `derived: k3 (verified live 260921: same K3 served under the explicit ceiling id) ${KIMI_PRICING}`, verifiedAt: "2026-09-21", status: "verified-derived" },
   { provider: "kimi-code", modelId: "kimi-k2.7-code", cost4: KIMI_K27_CODE, source: KIMI_PRICING, verifiedAt: "2026-07-20", status: "verified-derived" },
   { provider: "kimi-code", modelId: "kimi-k2.7-code-highspeed", cost4: KIMI_K27_CODE_HIGHSPEED, source: KIMI_PRICING, verifiedAt: "2026-07-20", status: "verified-derived" },
   { provider: "kimi-code", modelId: "kimi-k2.6", cost4: KIMI_K26, source: KIMI_PRICING, verifiedAt: "2026-07-20", status: "verified-derived" },
diff --git a/src/usage/failure-fingerprint.ts b/src/usage/failure-fingerprint.ts
new file mode 100644
index 00000000000..ea9524b1c19
--- /dev/null
+++ b/src/usage/failure-fingerprint.ts
@@ -0,0 +1,118 @@
+/**
+ * A versioned, content-free identity for one kind of request failure (#3748).
+ *
+ * #3748 proposed a second SQLite store under src/telemetry/ holding a free-text `signature`
+ * masked by regular expressions. Both halves are replaced here. The store is replaced by a
+ * projection rebuilt from usage.jsonl, and the masked signature is replaced by a tuple of closed
+ * roster members -- because a regular expression can only assert that it removed what it matched,
+ * while a tuple whose every slot is a member of a frozen list has nothing to remove.
+ *
+ * That is the whole design: the input type cannot express a provider alias, a model, an account,
+ * an error message, a prompt, a request id or a timestamp, so no amount of upstream text can
+ * reach a fingerprint.
+ */
+import { createHash } from "node:crypto";
+import type { RequestFailureCause } from "../lib/request-failure-model";
+import type { RequestCloseReason, RequestTerminalStatus } from "./request-outcome";
+import type { PersistedUsageEntry } from "./log";
+
+/**
+ * The tuple layout and its meaning are one contract.
+ *
+ * Adding, removing, reordering or reinterpreting a position changes what a stored fingerprint
+ * means, so any of those requires incrementing this. Tests import it rather than writing `1`,
+ * so a bump cannot be silently contradicted by a test that still expects the old prefix.
+ */
+export const FAILURE_FINGERPRINT_VERSION = 1 as const;
+
+/**
+ * The status reduced to its class.
+ *
+ * The exact code is not in the tuple: a 502 and a 503 that both failed for `upstream-fault` are
+ * one problem to an operator, and keeping the code would split every group by whichever number
+ * an origin happened to send.
+ */
+export const FAILURE_STATUS_CLASSES = Object.freeze([
+  "1xx", "2xx", "3xx", "4xx", "5xx", "unknown",
+] as const);
+
+export type FailureStatusClass = typeof FAILURE_STATUS_CLASSES[number];
+
+export type FailureFingerprint = `v${typeof FAILURE_FINGERPRINT_VERSION}:${string}`;
+
+/**
+ * Everything a fingerprint is allowed to read, and nothing else.
+ *
+ * Every slot is either a member of a frozen roster or `null`. `providerClass` is the one field
+ * that starts life as free text: the durable `provider` is a name the user chose, so it is
+ * resolved against the provider registry first and becomes `null` when it is not a registry
+ * member. A configured alias therefore cannot reach the key whatever it was named.
+ */
+export interface FailureFingerprintFacts {
+  readonly cause: RequestFailureCause;
+  readonly statusClass: FailureStatusClass;
+  readonly providerClass: string | null;
+  readonly inboundProtocol: NonNullable<PersistedUsageEntry["inboundProtocol"]> | null;
+  readonly terminalStatus: RequestTerminalStatus | null;
+  readonly closeReason: RequestCloseReason | null;
+  readonly transportPhase: NonNullable<PersistedUsageEntry["transportPhase"]> | null;
+  readonly terminalSource: NonNullable<PersistedUsageEntry["terminalSource"]> | null;
+}
+
+/**
+ * Fixed positions, with every absent fact written as an explicit `null`.
+ *
+ * Omitting an absent field, or joining the present ones with a delimiter, would let two
+ * different failures collide: `[a, null, b]` and `[a, b]` are the same string once the nulls
+ * are dropped. A fixed-arity tuple cannot collide that way, which is why the shape is a tuple
+ * rather than an object with optional keys.
+ */
+export type FailureFingerprintTuple = readonly [
+  version: typeof FAILURE_FINGERPRINT_VERSION,
+  cause: FailureFingerprintFacts["cause"],
+  statusClass: FailureFingerprintFacts["statusClass"],
+  providerClass: FailureFingerprintFacts["providerClass"],
+  inboundProtocol: FailureFingerprintFacts["inboundProtocol"],
+  terminalStatus: FailureFingerprintFacts["terminalStatus"],
+  closeReason: FailureFingerprintFacts["closeReason"],
+  transportPhase: FailureFingerprintFacts["transportPhase"],
+  terminalSource: FailureFingerprintFacts["terminalSource"],
+];
+
+export function failureStatusClass(status: unknown): FailureStatusClass {
+  if (typeof status !== "number" || !Number.isInteger(status) || status < 100 || status > 599) {
+    return "unknown";
+  }
+  const index = Math.floor(status / 100) - 1;
+  return FAILURE_STATUS_CLASSES[index] ?? "unknown";
+}
+
+export function canonicalFailureFingerprintTuple(
+  facts: FailureFingerprintFacts,
+): FailureFingerprintTuple {
+  return [
+    FAILURE_FINGERPRINT_VERSION,
+    facts.cause,
+    facts.statusClass,
+    facts.providerClass,
+    facts.inboundProtocol,
+    facts.terminalStatus,
+    facts.closeReason,
+    facts.transportPhase,
+    facts.terminalSource,
+  ];
+}
+
+/**
+ * The version travels in the value, not only in the hashed input.
+ *
+ * Both matter and for different reasons: hashing it means two versions of the same failure never
+ * collide, and prefixing it means a reader holding an old fingerprint can tell that it is old
+ * instead of concluding the failure stopped happening.
+ */
+export function computeFailureFingerprint(facts: FailureFingerprintFacts): FailureFingerprint {
+  const digest = createHash("sha256")
+    .update(JSON.stringify(canonicalFailureFingerprintTuple(facts)))
+    .digest("hex");
+  return `v${FAILURE_FINGERPRINT_VERSION}:${digest}`;
+}
diff --git a/src/usage/failure-projection-cache.ts b/src/usage/failure-projection-cache.ts
new file mode 100644
index 00000000000..953f292fe52
--- /dev/null
+++ b/src/usage/failure-projection-cache.ts
@@ -0,0 +1,174 @@
+/**
+ * The scan owner for the failure projection: one checkpointed pass over usage.jsonl.
+ *
+ * Shaped after `src/server/management/usage-aggregate-cache.ts`, which solved the same problem
+ * for the usage summary. That similarity is deliberate -- the correctness here is entirely in
+ * the checkpoint discipline, and two subtly different versions of it is how a projection quietly
+ * extends stale groups across a file that was replaced under it.
+ *
+ * Every bound this projection obeys belongs to the scanner it calls, not to itself: the 1 MiB
+ * row ceiling, the 1 MiB chunk, the cooperative yield, the opened-EOF snapshot boundary and the
+ * path/device/inode/birthtime identity with its 64 KiB boundary digest. A projection with its
+ * own limits would be a second storage policy, which is what this lane exists to avoid.
+ */
+import {
+  currentUsageLogRevision,
+  usageLogIdentityKey,
+  usageLogRevisionKey,
+  type UsageLogRevision,
+} from "./log";
+import {
+  scanUsageLedgerCooperatively,
+  UsageLedgerRebuildRequiredError,
+} from "./ledger-scanner";
+import {
+  createFailureProjectionAccumulator,
+  type FailureProjectionAccumulator,
+  type FailureProjectionSnapshot,
+} from "./failure-projection";
+
+export type FailureProjectionUpdate = "unchanged" | "append" | "rebuild";
+
+export interface FailureProjectionResult extends FailureProjectionSnapshot {
+  update: FailureProjectionUpdate;
+  /** True once any row was skipped for exceeding the scanner's row ceiling. Sticky. */
+  historyIncomplete: boolean;
+}
+
+interface RetainedProjection {
+  accumulator: FailureProjectionAccumulator;
+  historyIncomplete: boolean;
+  revision: UsageLogRevision | null;
+  identityKey: string;
+  revisionKey: string;
+  processedThroughBytes: number;
+  processedThroughDigest: string;
+}
+
+const MAX_REBUILD_ATTEMPTS = 2;
+let retained: RetainedProjection | null = null;
+let inFlight: Promise<FailureProjectionResult> | null = null;
+
+function resultFrom(state: RetainedProjection, update: FailureProjectionUpdate): FailureProjectionResult {
+  return { ...state.accumulator.snapshot(), update, historyIncomplete: state.historyIncomplete };
+}
+
+function retain(
+  accumulator: FailureProjectionAccumulator,
+  scan: Awaited<ReturnType<typeof scanUsageLedgerCooperatively>>,
+  historyIncomplete: boolean,
+): RetainedProjection {
+  return {
+    accumulator,
+    historyIncomplete: historyIncomplete || scan.oversizedRows > 0,
+    revision: scan.revision,
+    identityKey: usageLogIdentityKey(scan.revision),
+    revisionKey: usageLogRevisionKey(scan.revision),
+    processedThroughBytes: scan.processedThroughBytes,
+    processedThroughDigest: scan.processedThroughDigest,
+  };
+}
+
+async function rebuild(signal: AbortSignal | undefined): Promise<FailureProjectionResult> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_REBUILD_ATTEMPTS; attempt += 1) {
+    const accumulator = createFailureProjectionAccumulator();
+    try {
+      const scan = await scanUsageLedgerCooperatively({
+        ...(signal ? { signal } : {}),
+        onEntry: entry => accumulator.add(entry),
+      });
+      retained = retain(accumulator, scan, false);
+      return resultFrom(retained, "rebuild");
+    } catch (error) {
+      lastError = error;
+      if (!(error instanceof UsageLedgerRebuildRequiredError) || attempt + 1 >= MAX_REBUILD_ATTEMPTS) throw error;
+    }
+  }
+  throw lastError ?? new Error("failure projection rebuild did not settle");
+}
+
+/**
+ * Whether the observed ledger can still be read as an append onto the retained state.
+ *
+ * A same-size file whose revision metadata moved is a replacement or an in-place edit, not an
+ * append. Treating it as one would extend groups built from rows that no longer exist, so it
+ * forces a rebuild even though the byte count is unchanged.
+ */
+function requiresRebuild(state: RetainedProjection, observed: UsageLogRevision | null): boolean {
+  if (state.identityKey !== usageLogIdentityKey(observed)) return true;
+  if (!state.revision || !observed) return state.revision !== observed;
+  if (observed.size < state.revision.size) return true;
+  return observed.size === state.revision.size && usageLogRevisionKey(observed) !== state.revisionKey;
+}
+
+async function append(
+  state: RetainedProjection,
+  signal: AbortSignal | undefined,
+): Promise<FailureProjectionResult> {
+  // Clone first and publish only after the scanner verifies the captured suffix, so a mutation
+  // discovered mid-scan leaves the retained state exactly as it was.
+  const candidate = state.accumulator.clone();
+  try {
+    const scan = await scanUsageLedgerCooperatively({
+      ...(signal ? { signal } : {}),
+      startAtBytes: state.processedThroughBytes,
+      expectedIdentityKey: state.identityKey,
+      expectedProcessedThroughDigest: state.processedThroughDigest,
+      onEntry: entry => candidate.add(entry),
+    });
+    retained = retain(candidate, scan, state.historyIncomplete);
+    return resultFrom(retained, "append");
+  } catch (error) {
+    if (retained === state) retained = null;
+    if (error instanceof UsageLedgerRebuildRequiredError) return rebuild(signal);
+    throw error;
+  }
+}
+
+async function refresh(signal: AbortSignal | undefined): Promise<FailureProjectionResult> {
+  const state = retained;
+  if (!state) return rebuild(signal);
+  const observed = currentUsageLogRevision();
+  if (requiresRebuild(state, observed)) return rebuild(signal);
+  if (observed && state.revision && observed.size === state.revision.size) {
+    return resultFrom(state, "unchanged");
+  }
+  return append(state, signal);
+}
+
+/**
+ * The current grouping, refreshed from the ledger.
+ *
+ * Single-flighted: two concurrent readers would otherwise run two scans of the same file and
+ * one of them would publish over the other's checkpoint.
+ */
+export async function getFailureProjection(
+  options: { signal?: AbortSignal } = {},
+): Promise<FailureProjectionResult> {
+  if (inFlight) return inFlight;
+  const flight = refresh(options.signal).finally(() => {
+    if (inFlight === flight) inFlight = null;
+  });
+  inFlight = flight;
+  return flight;
+}
+
+/**
+ * Drop the retained projection.
+ *
+ * Safe at any time and for any reason: it is rebuildable from the ledger by construction, which
+ * is the property that lets memory pressure discard the whole thing rather than prune individual
+ * groups. Pruning groups would make this projection a retention policy of its own.
+ */
+export function discardRetainedFailureProjection(): number {
+  const count = retained?.accumulator.groupCount ?? 0;
+  retained = null;
+  return count;
+}
+
+/** Test-only process-state reset for isolated harnesses. */
+export function resetFailureProjectionCacheForTests(): void {
+  retained = null;
+  inFlight = null;
+}
diff --git a/src/usage/failure-projection.ts b/src/usage/failure-projection.ts
new file mode 100644
index 00000000000..f235eac3628
--- /dev/null
+++ b/src/usage/failure-projection.ts
@@ -0,0 +1,174 @@
+/**
+ * Failures grouped by what they have in common, rebuilt from the canonical ledger.
+ *
+ * This is the derived form of #3748. The original built a second durable store; this holds only
+ * a count and two timestamps per group, and every one of them falls out of a scan of
+ * usage.jsonl. Delete a row from the ledger and it leaves this projection on the next rebuild,
+ * which is what it means for retention to have one owner rather than four.
+ *
+ * What it deliberately does NOT hold: the occurrence list the original retained (a second copy
+ * of history with its own retention policy), and the mutable monitoring/dispatched/fixed/ignored
+ * remediation status with its free-text notes. Those are operator state, not event history: they
+ * cannot be reconstructed from immutable request rows, so presenting them as a derived ledger
+ * would be presenting a claim this projection cannot make. They need their own owner if they are
+ * wanted, keyed by the fingerprint below.
+ */
+import { getProviderRegistryEntry } from "../providers/registry";
+import { baseProviderLabel } from "../providers/label";
+import {
+  computeFailureFingerprint,
+  failureStatusClass,
+  FAILURE_FINGERPRINT_VERSION,
+  type FailureFingerprint,
+  type FailureFingerprintFacts,
+} from "./failure-fingerprint";
+import {
+  classifyRequestOutcome,
+  isRequestCloseReason,
+  isRequestTerminalStatus,
+} from "./request-outcome";
+import {
+  isKnownInboundProtocol,
+  isKnownRequestFailureCause,
+  isKnownTerminalSource,
+  isKnownTransportPhase,
+  type PersistedUsageEntry,
+} from "./log";
+
+/**
+ * The configured provider name reduced to a registry member, or null.
+ *
+ * The durable `provider` is whatever the user named their provider entry, so it is open text and
+ * cannot enter a key that promises to carry no content. Resolving it against the registry makes
+ * the value closed by construction: either it is one of the ids this build ships, or it is
+ * nothing. A user who names a provider after themselves groups under `null`, which is the
+ * correct answer -- the projection does not know which provider it is.
+ */
+export function failureProviderClass(provider: string): string | null {
+  return getProviderRegistryEntry(baseProviderLabel(provider))?.id ?? null;
+}
+
+export interface FailureProjectionGroup extends FailureFingerprintFacts {
+  fingerprint: FailureFingerprint;
+  firstSeen: number;
+  lastSeen: number;
+  count: number;
+}
+
+export interface FailureProjectionSnapshot {
+  fingerprintVersion: typeof FAILURE_FINGERPRINT_VERSION;
+  groups: readonly FailureProjectionGroup[];
+  /**
+   * Failed rows written before the recorder stored a cause. Counted rather than bucketed under
+   * an invented "unknown" cause, because a group an operator cannot act on is worse than a
+   * number that says how much history predates the field.
+   */
+  unattributedFailures: number;
+  /** Failed rows whose timestamp is not a finite number, so they cannot date a group. */
+  invalidTimestampFailures: number;
+}
+
+export interface FailureProjectionAccumulator {
+  add(entry: PersistedUsageEntry): void;
+  clone(): FailureProjectionAccumulator;
+  snapshot(): FailureProjectionSnapshot;
+  readonly groupCount: number;
+}
+
+interface MutableGroup extends FailureFingerprintFacts {
+  fingerprint: FailureFingerprint;
+  firstSeen: number;
+  lastSeen: number;
+  count: number;
+}
+
+function factsFor(entry: PersistedUsageEntry): FailureFingerprintFacts | null {
+  if (!isKnownRequestFailureCause(entry.failureCause)) return null;
+  return {
+    cause: entry.failureCause,
+    statusClass: failureStatusClass(entry.status),
+    providerClass: failureProviderClass(entry.provider),
+    inboundProtocol: isKnownInboundProtocol(entry.inboundProtocol) ? entry.inboundProtocol : null,
+    // Validated rather than copied. This is the one tuple slot whose durable type is a plain
+    // string, and it is assembled from an upstream terminal frame, so an unvalidated value is
+    // the single way upstream-controlled text could reach a grouping key.
+    terminalStatus: isRequestTerminalStatus(entry.terminalStatus) ? entry.terminalStatus : null,
+    closeReason: isRequestCloseReason(entry.closeReason) ? entry.closeReason : null,
+    transportPhase: isKnownTransportPhase(entry.transportPhase) ? entry.transportPhase : null,
+    terminalSource: isKnownTerminalSource(entry.terminalSource) ? entry.terminalSource : null,
+  };
+}
+
+function createFrom(groups: Map<string, MutableGroup>, counters: {
+  unattributed: number;
+  invalidTimestamp: number;
+}): FailureProjectionAccumulator {
+  let unattributedFailures = counters.unattributed;
+  let invalidTimestampFailures = counters.invalidTimestamp;
+
+  return {
+    add(entry: PersistedUsageEntry): void {
+      // The shared classifier decides what a failure is, so this projection and the exporter
+      // agree on which rows are in scope. An incomplete turn is not here: it has no cause.
+      if (classifyRequestOutcome(entry) !== "failed") return;
+      const facts = factsFor(entry);
+      if (facts === null) {
+        unattributedFailures += 1;
+        return;
+      }
+      if (typeof entry.timestamp !== "number" || !Number.isFinite(entry.timestamp)) {
+        invalidTimestampFailures += 1;
+        return;
+      }
+      const fingerprint = computeFailureFingerprint(facts);
+      const existing = groups.get(fingerprint);
+      if (existing === undefined) {
+        groups.set(fingerprint, {
+          ...facts,
+          fingerprint,
+          firstSeen: entry.timestamp,
+          lastSeen: entry.timestamp,
+          count: 1,
+        });
+        return;
+      }
+      // Min and max rather than first-and-last-written: a ledger is append-ordered in practice
+      // but nothing in the format promises it, and a projection that assumed order would report
+      // a first-seen later than its last-seen for a hand-merged file.
+      existing.firstSeen = Math.min(existing.firstSeen, entry.timestamp);
+      existing.lastSeen = Math.max(existing.lastSeen, entry.timestamp);
+      existing.count += 1;
+    },
+
+    clone(): FailureProjectionAccumulator {
+      const copy = new Map<string, MutableGroup>();
+      for (const [key, group] of groups) copy.set(key, { ...group });
+      return createFrom(copy, {
+        unattributed: unattributedFailures,
+        invalidTimestamp: invalidTimestampFailures,
+      });
+    },
+
+    snapshot(): FailureProjectionSnapshot {
+      // Most recent first, then by fingerprint, so two runs over the same ledger produce the
+      // same order. A tie broken by insertion order would depend on scan chunking.
+      const ordered = [...groups.values()]
+        .map(group => ({ ...group }))
+        .sort((a, b) => b.lastSeen - a.lastSeen || (a.fingerprint < b.fingerprint ? -1 : a.fingerprint > b.fingerprint ? 1 : 0));
+      return {
+        fingerprintVersion: FAILURE_FINGERPRINT_VERSION,
+        groups: ordered,
+        unattributedFailures,
+        invalidTimestampFailures,
+      };
+    },
+
+    get groupCount(): number {
+      return groups.size;
+    },
+  };
+}
+
+export function createFailureProjectionAccumulator(): FailureProjectionAccumulator {
+  return createFrom(new Map(), { unattributed: 0, invalidTimestamp: 0 });
+}
diff --git a/src/usage/ledger-retention.ts b/src/usage/ledger-retention.ts
new file mode 100644
index 00000000000..aaaf17bcc5b
--- /dev/null
+++ b/src/usage/ledger-retention.ts
@@ -0,0 +1,160 @@
+/**
+ * Opt-in size limit for the canonical usage ledger (#5063).
+ *
+ * Retention on usage.jsonl is the right architecture -- the alternative is a projection that
+ * deletes rows the ledger still has, which is a second retention policy. What #5063's version
+ * could not promise is that a row appended by another writer between its size snapshot and its
+ * rename survived: it captured a size, copied a suffix, and renamed over whatever was there.
+ *
+ * Two things close that here. The append is synchronous and this runs inside the same call
+ * stack, with no await between the append and the publication, so no in-process append can
+ * interleave. And `validateBeforeRename` re-opens the target immediately before the rename and
+ * refuses unless its identity, size and revision metadata are byte-for-byte what was copied --
+ * so an append from anywhere else aborts the replacement instead of losing the row. The original
+ * file and that append both survive; the next append retries from a fresh revision.
+ *
+ * What remains outside the contract: a program that ignores the OpenCodex ledger owner entirely
+ * can still write between the final comparison and the rename. No portable conditional rename
+ * exists to prevent that, and the honest claim is that the race is closed for every cooperating
+ * writer and detected up to the last possible moment for anything else.
+ */
+import { closeSync, fstatSync, openSync, readSync, writeSync } from "node:fs";
+import { atomicWriteFileStreamed } from "../config/atomic-write";
+import {
+  currentUsageLogRevision,
+  usageLogIdentityKey,
+  usageLogPath,
+  usageLogRevisionKey,
+  type UsageLogRevision,
+} from "./log";
+import {
+  MIN_USAGE_LEDGER_MAX_BYTES,
+  USAGE_LEDGER_RETENTION_TARGET_RATIO,
+} from "./retention-contract";
+
+/** Bounded copy buffer. Matches the ledger scanner's chunk so one storage policy governs both. */
+const COPY_CHUNK_BYTES = 1024 * 1024;
+
+export class UsageLedgerRevisionChangedError extends Error {
+  readonly code = "usage_ledger_revision_changed";
+
+  constructor() {
+    super("usage ledger changed while its retained span was being published");
+    this.name = "UsageLedgerRevisionChangedError";
+  }
+}
+
+export type UsageLedgerRetentionResult =
+  | { kind: "disabled" }
+  | { kind: "unchanged"; currentBytes: number }
+  | { kind: "replaced"; currentBytes: number; removedBytes: number }
+  | { kind: "deferred"; currentBytes: number; reason: "revision-changed" | "no-boundary" };
+
+/**
+ * The first LF at or after `from`, so the retained span starts on a row boundary.
+ *
+ * Any nonempty suffix that is not LF-terminated is uncommitted by the scanner's definition, even
+ * if it happens to parse. Starting anywhere but after an LF would publish half a row as a whole
+ * one, which is the shape that makes a ledger unreadable rather than merely shorter.
+ */
+function firstRowBoundary(fd: number, from: number, end: number): number | null {
+  const buffer = Buffer.allocUnsafe(COPY_CHUNK_BYTES);
+  for (let position = from; position < end;) {
+    const read = readSync(fd, buffer, 0, Math.min(buffer.byteLength, end - position), position);
+    if (read <= 0) return null;
+    const index = buffer.subarray(0, read).indexOf(0x0a);
+    if (index >= 0) return position + index + 1;
+    position += read;
+  }
+  return null;
+}
+
+function copyRange(sourceFd: number, targetFd: number, from: number, to: number): void {
+  const buffer = Buffer.allocUnsafe(COPY_CHUNK_BYTES);
+  for (let position = from; position < to;) {
+    const read = readSync(sourceFd, buffer, 0, Math.min(buffer.byteLength, to - position), position);
+    if (read <= 0) throw new Error("usage ledger shrank while its retained span was copied");
+    let written = 0;
+    while (written < read) written += writeSync(targetFd, buffer, written, read - written);
+    position += read;
+  }
+}
+
+function sameRevision(a: UsageLogRevision | null, b: UsageLogRevision | null): boolean {
+  return a !== null && b !== null
+    && usageLogIdentityKey(a) === usageLogIdentityKey(b)
+    && usageLogRevisionKey(a) === usageLogRevisionKey(b)
+    && a.size === b.size;
+}
+
+/**
+ * Trim the ledger to the newest whole rows when it exceeds `maxBytes`.
+ *
+ * Rows are copied BYTE FOR BYTE and never parsed or re-serialized. That is what keeps the
+ * failure stage and cause, the attempts, the spend record and any field a later build adds
+ * intact through a compaction: a retention pass that understood the row shape would silently
+ * drop every field it was written before.
+ */
+export function enforceUsageLedgerSizeLimit(
+  maxBytes: number | undefined,
+  /**
+   * Runs after the retained span is copied and before the pre-rename check.
+   *
+   * A parameter rather than an exported flag, so the only way to reach this window is to be the
+   * caller. The revision guard below is the one piece of this module that cannot be observed
+   * from its inputs and outputs, and a contract nothing can drive is a contract nobody has
+   * checked.
+   */
+  options: { onSpanCopied?: () => void } = {},
+): UsageLedgerRetentionResult {
+  if (maxBytes === undefined || !Number.isSafeInteger(maxBytes) || maxBytes < MIN_USAGE_LEDGER_MAX_BYTES) {
+    return { kind: "disabled" };
+  }
+  const captured = currentUsageLogRevision();
+  if (!captured || captured.size <= maxBytes) {
+    return captured ? { kind: "unchanged", currentBytes: captured.size } : { kind: "disabled" };
+  }
+  const path = usageLogPath();
+  // Trim below the ceiling rather than to it, so an append does not immediately re-cross the
+  // line and make every subsequent append pay for a full rewrite.
+  const target = Math.floor(maxBytes * USAGE_LEDGER_RETENTION_TARGET_RATIO);
+  let sourceFd: number;
+  try {
+    sourceFd = openSync(path, "r");
+  } catch {
+    return { kind: "deferred", currentBytes: captured.size, reason: "revision-changed" };
+  }
+  try {
+    const opened = fstatSync(sourceFd);
+    if (Number(opened.size) !== captured.size || Number(opened.ino) !== captured.ino) {
+      return { kind: "deferred", currentBytes: captured.size, reason: "revision-changed" };
+    }
+    const start = firstRowBoundary(sourceFd, Math.max(0, captured.size - target), captured.size);
+    // No LF in the retained window means one row is larger than the whole target. Deleting it
+    // would empty the ledger to satisfy a ceiling it cannot meet, so nothing is done.
+    if (start === null || start >= captured.size) {
+      return { kind: "deferred", currentBytes: captured.size, reason: "no-boundary" };
+    }
+    atomicWriteFileStreamed(path, descriptor => {
+      copyRange(sourceFd, descriptor, start, captured.size);
+      options.onSpanCopied?.();
+    }, {
+      // The last possible moment. Anything that appended, replaced or rewrote the ledger while
+      // the copy ran moves size, inode or revision metadata, and the throw leaves both the
+      // original file and that write exactly as they are.
+      validateBeforeRename: () => {
+        if (!sameRevision(currentUsageLogRevision(), captured)) {
+          throw new UsageLedgerRevisionChangedError();
+        }
+      },
+    });
+    return { kind: "replaced", currentBytes: captured.size - start, removedBytes: start };
+  } catch (error) {
+    if (error instanceof UsageLedgerRevisionChangedError) {
+      return { kind: "deferred", currentBytes: captured.size, reason: "revision-changed" };
+    }
+    throw error;
+  } finally {
+    closeSync(sourceFd);
+  }
+}
diff --git a/src/usage/log.ts b/src/usage/log.ts
index 4c1cc58204b..6955db2073a 100644
--- a/src/usage/log.ts
+++ b/src/usage/log.ts
@@ -7,11 +7,36 @@ import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { sanitizeLogMetadataString } from "../lib/redact";
 import { usageDisplayTotalTokens } from "./totals";
+import { normalizeAttemptDeliverySummary } from "./attempt-delivery";
+import {
+  isRequestCloseReason,
+  isRequestTerminalStatus,
+  type RequestCloseReason,
+  type RequestTerminalStatus,
+} from "./request-outcome";
 import type { AttemptTierOutcome, OcxUsage } from "../types";
 import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routing/trace";
 import { ACCOUNT_LOG_LABEL_RE, CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
 import { claudeCompatibilityReason, normalizeClaudeFeatureCodes, type ClaudeFeatureCode } from "../claude/compatibility";
 import type { CodexWsStageRecord } from "../server/responses/codex-ws-wire";
+import {
+  ATTEMPT_RECOVERY_KIND_ROSTER,
+  ATTEMPT_RECOVERY_WITHHELD_ROSTER,
+  REQUEST_FAILURE_CAUSES,
+  REQUEST_FAILURE_STAGES,
+  REQUEST_TRANSPORT_PHASES,
+  type AttemptRecoveryKind,
+  type AttemptRecoveryWithheld,
+  type AttemptDeliverySummary,
+  type RequestFailureCause,
+  type RequestFailureStage,
+  type RequestSpendTotals,
+} from "./telemetry-contract";
+
+// Re-exported so every existing importer keeps its path. The declarations moved to a leaf the
+// dashboard can import without pulling node:fs and the config barrel into the browser build.
+export { ATTEMPT_RECOVERY_KIND_ROSTER, ATTEMPT_RECOVERY_WITHHELD_ROSTER, REQUEST_FAILURE_CAUSES, REQUEST_FAILURE_STAGES };
+export type { AttemptRecoveryKind, AttemptRecoveryWithheld, RequestFailureCause, RequestFailureStage, RequestSpendTotals };
 
 export interface PersistedClaudeCompatibilityLog {
   decision: "shadow";
@@ -58,45 +83,6 @@ export function isCodexPoolAccountLogLabel(value: unknown): value is "main" | `p
   return value === "main" || (typeof value === "string" && CODEX_ACCOUNT_LOG_LABEL_RE.test(value));
 }
 
-/**
- * Recovery kinds recorded per attempt in the usage log; the GUI renders localized labels
- * for these wire values.
- */
-export type AttemptRecoveryKind =
-  | "transient-5xx"
-  | "connection-reset"
-  | "oauth-401"
-  | "key-401"
-  | "key-429"
-  | "rate-limit-429"
-  | "anthropic-oauth-429"
-  | "oauth-account-429"
-  | "image-413"
-  | "console-go-upload-retry"
-  | "opaque-blob-rejection"
-  | "empty-completion"
-  | "reasoning-effort-downgrade";
-
-/**
- * Why a recovery this request was otherwise willing to make did not happen.
- *
- * Recorded separately from `recoveryKinds` and from `sendCount`, because the question it
- * answers is different from either. A log showing one physical send and no recovery kind used
- * to be ambiguous: it could mean nothing was eligible, or that something was eligible and the
- * send budget withheld it. Those need opposite follow-ups, and the second one was invisible
- * (#5044).
- *
- * `sendCount` deliberately does not move for these. A refused attempt is not a physical send,
- * and inflating the count to signal the refusal would corrupt the one number that means
- * "requests this proxy actually made".
- *
- * Bounded vocabulary on purpose: it is a wire value a maintainer reads, never a credential, an
- * account id, an upstream body, prompt content, or exception text.
- */
-export type AttemptRecoveryWithheld =
-  | "retry-send-budget"
-  | "rotation-send-budget";
-
 /** Request-time upstream credential class, never a credential or account identifier. */
 export type UsageCredentialSource = "grok-oauth" | "xai-api-key";
 
@@ -200,6 +186,21 @@ export interface PersistedUsageAttempt {
    * account identifiers.
    */
   codexWsStage?: CodexWsStageRecord;
+  /**
+   * What this attempt delivered, as five bounded counts (#3983). Absent on attempts whose
+   * transport does not pass through the Responses bridge and on pre-instrumentation rows.
+   */
+  deliverySummary?: AttemptDeliverySummary;
+  /**
+   * How far this attempt's exchange got and why it failed, in the shared vocabulary (#2366).
+   *
+   * Both values are closed roster members, so the pair can be a metric label and a grouping key
+   * without a masking pass. Absent on a completed attempt and on every row written before the
+   * attribution existed. The resend verdict these two imply is NOT stored: it is derived at read
+   * time, so a stored row can never carry a verdict the current table would no longer reach.
+   */
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
 }
 
 /**
@@ -210,19 +211,7 @@ export interface PersistedUsageAttempt {
  * operator needs is the total that reached upstream carrying the full prompt. These fields are
  * that total, decomposed by how much of it is explained.
  */
-export interface PersistedRequestSpend {
-  /** Physical upstream sends summed across every attempt of this logical request, combo children included. */
-  sends: number;
-  /** Sends whose attempt reached a terminal status, so the spend has a known outcome. */
-  settled: number;
-  /**
-   * Sends charged with no terminal outcome behind them: an attempt abandoned mid-flight, or a
-   * budget charge no attempt row ever accounted for. Never folded into `settled` — an unexplained
-   * send is the exact quantity this record exists to make visible.
-   */
-  unresolved: number;
-  /** Model sends the request execution budget charged. Absent when no budget was attached. */
-  reserved?: number;
+export interface PersistedRequestSpend extends RequestSpendTotals {
   /** Budget profile that produced `reserved`, so a count can be read against the policy it obeyed. */
   policyVersion?: string;
   /**
@@ -329,8 +318,13 @@ export interface PersistedUsageEntry {
   // Failure diagnostics (devlog/_plan/260716_claudecode_hardening/030): persisted for
   // status>=400 or non-completed terminals so incidents survive the in-memory ring buffer.
   errorCode?: string;
-  terminalStatus?: string;
-  closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow";
+  /**
+   * Closed, like `closeReason` beside it has always been. It was `string` while it was only
+   * rendered; it is a grouping-key slot now, and the value is assembled from an upstream
+   * terminal frame, so an open type here is the one way upstream text could reach that key.
+   */
+  terminalStatus?: RequestTerminalStatus;
+  closeReason?: RequestCloseReason;
   /** Already redacted + capped at capture (request-log.ts redactSecretString().slice(0,500)). */
   upstreamError?: string;
   /** Where the terminal/failure was observed; absent on historic rows. */
@@ -357,6 +351,53 @@ export interface PersistedUsageEntry {
   routeDecision?: RouteDecisionTraceV1;
   /** Closed Claude protocol codes only; absent on older rows. */
   claudeCompatibility?: PersistedClaudeCompatibilityLog;
+  /**
+   * How far this request got and why it failed (#2366). Projected from the attempt that ended
+   * the request so every surface reads the answer off the same row. Absent on a completed
+   * request and on rows written before the attribution existed.
+   */
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
+}
+
+/**
+ * Attribution for the logical request, projected from the attempt that ended it (#2366).
+ *
+ * Carried on the entry as well as the attempt because the three surfaces that have to agree read
+ * the entry: a projection that had to reach into `attempts` to answer "why did this fail" would
+ * be reading a different row from the exporter, which is the disagreement the landed terminal
+ * classifier already removed once.
+ */
+export interface PersistedRequestFailureAttribution {
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
+}
+
+const KNOWN_REQUEST_FAILURE_STAGES: ReadonlySet<string> = new Set(REQUEST_FAILURE_STAGES);
+const KNOWN_REQUEST_FAILURE_CAUSES: ReadonlySet<string> = new Set(REQUEST_FAILURE_CAUSES);
+
+/**
+ * Same closed-set discipline as `isKnownTransportPhase`, with the set DERIVED from the roster
+ * rather than restated. The recovery vocabulary was written twice once -- as a union and as the
+ * read-back whitelist -- and a member present in only one of them is written to disk and dropped
+ * on the next read, which loses exactly the field that says why the row failed.
+ */
+export function isKnownRequestFailureStage(value: unknown): value is RequestFailureStage {
+  return typeof value === "string" && KNOWN_REQUEST_FAILURE_STAGES.has(value);
+}
+
+export function isKnownRequestFailureCause(value: unknown): value is RequestFailureCause {
+  return typeof value === "string" && KNOWN_REQUEST_FAILURE_CAUSES.has(value);
+}
+
+/** The stage/cause pair a normalizer keeps, dropping either half that is not a roster member. */
+export function normalizeRequestFailureAttribution(
+  raw: { failureStage?: unknown; failureCause?: unknown },
+): PersistedRequestFailureAttribution {
+  return {
+    ...(isKnownRequestFailureStage(raw.failureStage) ? { failureStage: raw.failureStage } : {}),
+    ...(isKnownRequestFailureCause(raw.failureCause) ? { failureCause: raw.failureCause } : {}),
+  };
 }
 
 const KNOWN_USAGE_SURFACES = new Set<NonNullable<PersistedUsageEntry["surface"]>>([
@@ -394,12 +435,10 @@ export function isKnownInboundProtocol(value: unknown): value is NonNullable<Per
   return typeof value === "string" && KNOWN_INBOUND_PROTOCOLS.has(value as NonNullable<PersistedUsageEntry["inboundProtocol"]>);
 }
 
-const KNOWN_TRANSPORT_PHASES = new Set<NonNullable<PersistedUsageEntry["transportPhase"]>>([
-  "pre_headers", "mid_stream", "terminal_sse",
-]);
+const KNOWN_TRANSPORT_PHASES: ReadonlySet<string> = new Set(REQUEST_TRANSPORT_PHASES);
 
 export function isKnownTransportPhase(value: unknown): value is NonNullable<PersistedUsageEntry["transportPhase"]> {
-  return typeof value === "string" && KNOWN_TRANSPORT_PHASES.has(value as NonNullable<PersistedUsageEntry["transportPhase"]>);
+  return typeof value === "string" && KNOWN_TRANSPORT_PHASES.has(value);
 }
 
 const KNOWN_TERMINAL_SOURCES = new Set<NonNullable<PersistedUsageEntry["terminalSource"]>>([
@@ -497,25 +536,8 @@ function normalizeUsageValue(usage: OcxUsage | undefined): OcxUsage | undefined
   };
 }
 
-const ATTEMPT_RECOVERY_KINDS = new Set<AttemptRecoveryKind>([
-  "transient-5xx",
-  "connection-reset",
-  "oauth-401",
-  "key-401",
-  "key-429",
-  "rate-limit-429",
-  "anthropic-oauth-429",
-  "oauth-account-429",
-  "image-413",
-  "console-go-upload-retry",
-  "opaque-blob-rejection",
-  "empty-completion",
-  "reasoning-effort-downgrade",
-]);
-const ATTEMPT_RECOVERY_WITHHELD = new Set<AttemptRecoveryWithheld>([
-  "retry-send-budget",
-  "rotation-send-budget",
-]);
+const ATTEMPT_RECOVERY_KINDS: ReadonlySet<AttemptRecoveryKind> = new Set(ATTEMPT_RECOVERY_KIND_ROSTER);
+const ATTEMPT_RECOVERY_WITHHELD: ReadonlySet<AttemptRecoveryWithheld> = new Set(ATTEMPT_RECOVERY_WITHHELD_ROSTER);
 const USAGE_STATUSES = new Set<UsageStatus>([
   "reported",
   "unreported",
@@ -643,6 +665,9 @@ function normalizeUsageAttempt(raw: unknown): PersistedUsageAttempt | null {
   const codexWsStage = "codexWsStage" in attempt
     ? normalizeCodexWsStageRecord(attempt.codexWsStage)
     : undefined;
+  const deliverySummary = "deliverySummary" in attempt
+    ? normalizeAttemptDeliverySummary(attempt.deliverySummary)
+    : undefined;
   const recoveryKinds = Array.isArray(attempt.recoveryKinds)
     ? [...new Set(attempt.recoveryKinds.filter(
       (value): value is AttemptRecoveryKind => typeof value === "string"
@@ -711,6 +736,8 @@ function normalizeUsageAttempt(raw: unknown): PersistedUsageAttempt | null {
       : {}),
     ...(tierOutcome ? { tierOutcome } : {}),
     ...(codexWsStage ? { codexWsStage } : {}),
+    ...(deliverySummary ? { deliverySummary } : {}),
+    ...normalizeRequestFailureAttribution(attempt),
   };
 }
 
@@ -882,11 +909,15 @@ function normalizeUsageEntry(entry: PersistedUsageEntry): PersistedUsageEntry {
     ...(affinityReason ? { affinityReason } : {}),
     ...(conversationStateScrub ? { conversationStateScrub } : {}),
     ...(entry.errorCode ? { errorCode: entry.errorCode } : {}),
-    ...(entry.terminalStatus ? { terminalStatus: entry.terminalStatus } : {}),
-    ...(entry.closeReason ? { closeReason: entry.closeReason } : {}),
+    // Validated rather than copied on truthiness, like the inbound protocol and transport phase
+    // above. Harmless while these were only rendered; not harmless once the terminal status is
+    // a grouping-key slot, because the string is assembled from an upstream frame.
+    ...(isRequestTerminalStatus(entry.terminalStatus) ? { terminalStatus: entry.terminalStatus } : {}),
+    ...(isRequestCloseReason(entry.closeReason) ? { closeReason: entry.closeReason } : {}),
     ...(entry.upstreamError ? { upstreamError: entry.upstreamError } : {}),
     ...(routeDecision ? { routeDecision } : {}),
     ...(claudeCompatibility ? { claudeCompatibility } : {}),
+    ...normalizeRequestFailureAttribution(entry),
   };
 }
 
@@ -921,6 +952,20 @@ function ensureUsageLogDir(now: number): void {
   ensuredUsageLogDir = { path: dir, checkedAt: now };
 }
 
+/**
+ * One owner hook, run after an append lands.
+ *
+ * A slot rather than a direct call, because the only consumer -- ledger retention -- reads this
+ * module's revision helpers, and importing it back here would be a static cycle. The hook runs
+ * INSIDE the synchronous append call stack on purpose: that is what makes "no in-process append
+ * can interleave with a compaction" true rather than merely likely.
+ */
+let afterUsageLedgerAppend: (() => void) | null = null;
+
+export function setUsageLedgerAppendHook(hook: (() => void) | null): void {
+  afterUsageLedgerAppend = hook;
+}
+
 export function appendUsageEntry(entry: PersistedUsageEntry): void {
   const line = `${JSON.stringify(normalizeUsageEntry(entry))}\n`;
   const path = usageLogPath();
@@ -941,10 +986,12 @@ export function appendUsageEntry(entry: PersistedUsageEntry): void {
       ensuredUsageLogDir = null;
       ensuredUsageLogFile = null;
       doAppend();
+      afterUsageLedgerAppend?.();
       return;
     }
     throw error;
   }
+  afterUsageLedgerAppend?.();
 }
 
 export type UsageLogRevision = {
diff --git a/src/usage/request-outcome.ts b/src/usage/request-outcome.ts
new file mode 100644
index 00000000000..a72f4cb8662
--- /dev/null
+++ b/src/usage/request-outcome.ts
@@ -0,0 +1,150 @@
+/**
+ * One terminal classification for a finished logical request, and the counts that go with it.
+ *
+ * Three surfaces answer "how did this request end" and they used to answer it three different
+ * ways. The durable row carries `terminalStatus` and `closeReason`; the Prometheus exporter had
+ * its own private `classifyResult`; the dashboard read the numeric HTTP status and nothing else.
+ * That is not a cosmetic difference. A turn cut short by `max_output_tokens` is durably
+ * `status: 200, terminalStatus: "incomplete"`, which the exporter reports as `incomplete` and the
+ * dashboard rendered as a green 200 — the operator and the metric disagreed about whether the
+ * user got an answer.
+ *
+ * The fix is not a third classifier. It is this one, which the exporter imports, the management
+ * payload carries, and the dashboard renders, so agreement is structural rather than a rule
+ * someone has to keep.
+ *
+ * Leaf module: its only import is a type, erased at runtime.
+ */
+import type { RequestSpendTotals } from "./telemetry-contract";
+
+/**
+ * Ordered by how much of an answer the caller received. The order is not a ranking of severity;
+ * `aborted` is last because the caller chose it, not because it is the worst outcome.
+ */
+export const REQUEST_OUTCOME_CLASSES = Object.freeze([
+  /** A terminal event settled the turn and the caller received the answer. */
+  "completed",
+  /** The turn ended without an answer. */
+  "failed",
+  /** The turn produced part of an answer and stopped. */
+  "incomplete",
+  /** The caller went away before the turn finished. */
+  "aborted",
+] as const);
+
+export type RequestOutcomeClass = typeof REQUEST_OUTCOME_CLASSES[number];
+
+/**
+ * The terminal statuses a Responses turn can settle on.
+ *
+ * Derived from the outcome classes rather than restated: a turn reports whether it completed,
+ * failed or stopped short, and `aborted` is not one of them because the caller leaving is not a
+ * terminal the origin emits. Deriving it means a fifth outcome class cannot leave this list
+ * stale, and restating the three would be the same copy that let the recovery roster drift.
+ */
+export type RequestTerminalStatus = Exclude<RequestOutcomeClass, "aborted">;
+
+/**
+ * The same three members as a runtime list, filtered out of the outcome roster rather than
+ * typed out again, so the guard below cannot disagree with the type above it.
+ */
+export const REQUEST_TERMINAL_STATUSES: readonly RequestTerminalStatus[] = Object.freeze(
+  REQUEST_OUTCOME_CLASSES.filter((value): value is RequestTerminalStatus => value !== "aborted"),
+);
+
+/** Why the response body stopped being read. Closed, and persisted as such. */
+export const REQUEST_CLOSE_REASONS = Object.freeze([
+  "terminal",
+  "client_cancel",
+  "non_stream",
+  "body_stall",
+  "body_overflow",
+] as const);
+
+export type RequestCloseReason = typeof REQUEST_CLOSE_REASONS[number];
+
+/**
+ * Read-back guards for the two facts that reach a durable row as strings.
+ *
+ * `terminalStatus` was typed `string` on the persisted entry and copied through the normalizer
+ * on truthiness alone, unlike the inbound protocol, transport phase and terminal source beside
+ * it. That was harmless while the value was only rendered; it stops being harmless the moment
+ * the value becomes part of a grouping key, because the string is assembled from an upstream
+ * frame and an unvalidated one would put upstream-controlled text into the key.
+ */
+export function isRequestTerminalStatus(value: unknown): value is RequestTerminalStatus {
+  return typeof value === "string"
+    && (REQUEST_TERMINAL_STATUSES as readonly string[]).includes(value);
+}
+
+export function isRequestCloseReason(value: unknown): value is RequestCloseReason {
+  return typeof value === "string"
+    && (REQUEST_CLOSE_REASONS as readonly string[]).includes(value);
+}
+
+/**
+ * The facts a terminal classification is allowed to read.
+ *
+ * Deliberately narrow, and deliberately NOT the whole durable row: an outcome that could consult
+ * a provider name or an error message would be a different answer per provider, which is how the
+ * three surfaces drifted apart in the first place.
+ */
+export interface RequestOutcomeFacts {
+  readonly status: number;
+  readonly terminalStatus?: string | undefined;
+  readonly closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow" | undefined;
+}
+
+/**
+ * Classify one finished logical request.
+ *
+ * Semantic terminal facts are read BEFORE the numeric status, which is the whole point. An HTTP
+ * 200 that carried an incomplete terminal is incomplete; a 502 that carried an incomplete
+ * terminal is also incomplete, and reading the status first would have called them success and
+ * failure. The numeric status is consulted only when no terminal event was recorded at all.
+ */
+export function classifyRequestOutcome(facts: RequestOutcomeFacts): RequestOutcomeClass {
+  if (facts.closeReason === "client_cancel" || facts.status === 499) return "aborted";
+  if (facts.terminalStatus === "failed") return "failed";
+  if (facts.terminalStatus === "incomplete"
+    || facts.closeReason === "body_stall"
+    || facts.closeReason === "body_overflow") return "incomplete";
+  if (facts.terminalStatus === "completed") return "completed";
+  if (facts.terminalStatus === undefined
+    && (facts.status === 101 || (facts.status >= 200 && facts.status < 400))) return "completed";
+  return "failed";
+}
+
+/** A count is reportable only when the writer recorded a non-negative integer. */
+function reportableCount(value: number | undefined): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : 0;
+}
+
+/**
+ * Physical sends a finished request made, as the one number every surface shows.
+ *
+ * This READS the recorded total rather than recomputing one. An earlier draft returned
+ * `max(sends, reserved)` on the reasoning that a budget charge with no attempt row behind it is
+ * still a send that left — true, but it made the dashboard report four where the exporter, which
+ * sums the same attempts the recorder summed, reported three. Two defensible formulas are still
+ * two answers. The recorder already decided this, and `unresolved` below is where a charge with
+ * no attempt behind it becomes visible.
+ */
+export function requestPhysicalSends(spend: RequestSpendTotals | undefined): number {
+  return reportableCount(spend?.sends);
+}
+
+/**
+ * Sends whose attempt reached a terminal status, and sends that did not.
+ *
+ * Kept beside {@link requestPhysicalSends} because an operator reading a send total needs to know
+ * how much of it is explained. An unresolved send is the quantity a duplicate-send incident shows
+ * up in, and folding it into the total is what made #4546 invisible for so long.
+ */
+export function requestSettledSends(spend: RequestSpendTotals | undefined): number {
+  return reportableCount(spend?.settled);
+}
+
+export function requestUnresolvedSends(spend: RequestSpendTotals | undefined): number {
+  return reportableCount(spend?.unresolved);
+}
diff --git a/src/usage/retention-contract.ts b/src/usage/retention-contract.ts
new file mode 100644
index 00000000000..bc8d10feece
--- /dev/null
+++ b/src/usage/retention-contract.ts
@@ -0,0 +1,28 @@
+/**
+ * The usage-ledger retention limits, stated once for the schema, the server and the dashboard.
+ *
+ * Import-free, for the reason `telemetry-contract.ts` gives: the dashboard is a separate
+ * TypeScript project, and a type-only import still drags the imported file's whole graph into
+ * the browser build. Anything added here must keep that property.
+ */
+
+/**
+ * Below this a ceiling cannot hold even one large row plus its successor, so a value under it is
+ * treated as unset rather than enforced into an empty ledger.
+ */
+export const MIN_USAGE_LEDGER_MAX_BYTES = 1024 * 1024;
+
+/** What the dashboard offers when a user turns the limit on. Not a default for the proxy. */
+export const SUGGESTED_USAGE_LEDGER_MAX_BYTES = 1024 * 1024 * 1024;
+
+/**
+ * Trim to this fraction of the ceiling rather than to the ceiling itself, so the next append does
+ * not immediately re-cross it and charge every subsequent append a full rewrite.
+ */
+export const USAGE_LEDGER_RETENTION_TARGET_RATIO = 0.9;
+
+export interface UsageLedgerRetentionStatus {
+  /** Absent when no limit is configured. */
+  maxBytes?: number;
+  currentBytes: number;
+}
diff --git a/src/usage/summary.ts b/src/usage/summary.ts
index b1468fd1258..091dac17632 100644
--- a/src/usage/summary.ts
+++ b/src/usage/summary.ts
@@ -410,7 +410,7 @@ function isMeasuredStatus(status: UsageStatus): boolean {
   return status === "reported" || status === "estimated";
 }
 
-interface UsageAttribution {
+export interface UsageAttribution {
   requestId: string;
   provider: string;
   model: string;
@@ -454,7 +454,7 @@ function usageModelKey(providerKey: string, model: string): string {
   return `${providerKey}\0${model}`;
 }
 
-function usageAttributions(entry: PersistedUsageEntry): UsageAttribution[] {
+export function usageAttributions(entry: PersistedUsageEntry): UsageAttribution[] {
   if (!entry.attempts?.length) {
     return [{
       requestId: entry.requestId,
diff --git a/src/usage/telemetry-contract.ts b/src/usage/telemetry-contract.ts
new file mode 100644
index 00000000000..ff8a0e08901
--- /dev/null
+++ b/src/usage/telemetry-contract.ts
@@ -0,0 +1,237 @@
+/**
+ * The telemetry vocabulary both the proxy and the dashboard read.
+ *
+ * This module has NO imports, and that is its entire job. The dashboard is a separate TypeScript
+ * project with `erasableSyntaxOnly`, and a type-only import still pulls the imported file's whole
+ * import graph into that project. Importing these names from `./log` therefore dragged
+ * `node:fs`, `node:crypto` and the config barrel into the browser build, where a parameter
+ * property in `src/config/atomic-write.ts` fails to compile. The names below are the ones a
+ * browser legitimately needs, so they live where a browser can reach them.
+ *
+ * Anything added here must stay free of imports. A contract that acquires a dependency stops
+ * being a contract.
+ */
+
+/**
+ * Recovery kinds recorded per attempt in the usage log; the dashboard renders localized labels
+ * for these wire values.
+ *
+ * The roster is the single statement of this vocabulary and the type is derived from it. It was
+ * written twice once -- as a union and as the read-back whitelist -- and the two are not
+ * interchangeable: a member added only to the union compiles, is written to disk, and is dropped
+ * on the next read, so the row loses the field that says why it recovered. One declaration cannot
+ * drift from itself, and the dashboard now reads this one rather than keeping a third copy.
+ */
+export const ATTEMPT_RECOVERY_KIND_ROSTER = Object.freeze([
+  "transient-5xx",
+  "connection-reset",
+  "oauth-401",
+  "key-401",
+  "key-429",
+  "rate-limit-429",
+  "anthropic-oauth-429",
+  "oauth-account-429",
+  "image-413",
+  "console-go-upload-retry",
+  "opaque-blob-rejection",
+  "empty-completion",
+  "reasoning-effort-downgrade",
+] as const);
+
+export type AttemptRecoveryKind = typeof ATTEMPT_RECOVERY_KIND_ROSTER[number];
+
+/**
+ * Why a recovery this request was otherwise willing to make did not happen.
+ *
+ * Recorded separately from `recoveryKinds` and from `sendCount` because the question it answers
+ * is different from either. A log showing one physical send and no recovery kind used to be
+ * ambiguous: nothing was eligible, or something was and the send budget withheld it. Those need
+ * opposite follow-ups and the second was invisible (#5044).
+ *
+ * `sendCount` deliberately does not move for these. A refused attempt is not a physical send, and
+ * inflating the count to signal the refusal would corrupt the one number that means "requests this
+ * proxy actually made".
+ */
+export const ATTEMPT_RECOVERY_WITHHELD_ROSTER = Object.freeze([
+  "retry-send-budget",
+  "rotation-send-budget",
+] as const);
+
+export type AttemptRecoveryWithheld = typeof ATTEMPT_RECOVERY_WITHHELD_ROSTER[number];
+
+/**
+ * How far a failed exchange got, ordered by how much the DOWNSTREAM CLIENT observed.
+ *
+ * The order is by client observation rather than by upstream progress, because the question it
+ * answers is whether resending can duplicate something the caller already saw. An upstream that
+ * completed a turn we never relayed has committed nothing downstream; an upstream that emitted
+ * one token has.
+ *
+ * The roster lives here rather than beside the resend tables for the reason stated at the top of
+ * this file: the dashboard renders a label per member, and reaching the table module for the
+ * names would drag its import graph into the browser project. `src/lib/request-failure-model.ts`
+ * re-exports it, so every existing importer keeps its path and there is still exactly one
+ * declaration.
+ */
+export const REQUEST_FAILURE_STAGES = Object.freeze([
+  /** No response head exists. Whether the origin began the turn is not known from the stage alone. */
+  "pre-header",
+  /** A status line and headers exist, and no protocol body event has been parsed yet. */
+  "headers-only",
+  /** The protocol body began with control events only -- `response.created`, quota frames. */
+  "protocol-prelude",
+  /** At least one output-bearing event reached the caller. */
+  "semantic-output",
+  /** A tool call or other externally visible effect was emitted. */
+  "side-effect",
+  /** A terminal event settled the turn after its answer reached the caller. */
+  "terminal",
+] as const);
+
+export type RequestFailureStage = typeof REQUEST_FAILURE_STAGES[number];
+
+/**
+ * Why the request failed, as one closed dictionary for every layer.
+ *
+ * Bounded on purpose: these are wire values a maintainer reads and a metric labels by, never a
+ * credential, an account identifier, an upstream body or prompt content. That bound is what lets
+ * the value be a Prometheus label and a grouping key without a masking pass -- a closed roster
+ * has nothing to mask.
+ */
+export const REQUEST_FAILURE_CAUSES = Object.freeze([
+  /** The bytes provably never reached the origin: connect refused, DNS failure, TLS handshake. */
+  "transport-unsent",
+  /** The bytes left and the connection died before a head. The origin may be running the turn. */
+  "transport-ambiguous",
+  /** The origin answered that it would not start the turn now: 503, overloaded, backpressure. */
+  "upstream-declined",
+  /** A 429 rate limit. Capacity is momentarily gone; waiting is the remedy. */
+  "rate-limit",
+  /** Plan or credit quota is gone. Waiting out a retry window does not help; the account must change. */
+  "quota-exhausted",
+  /** Credentials were rejected: 401, 403 on identity. */
+  "credential-rejected",
+  /** The origin evaluated the content and refused it. Identical bytes get the identical refusal. */
+  "policy-refusal",
+  /**
+   * The origin rejected a request PARAMETER rather than the content: an unsupported reasoning
+   * effort, an unknown field. Distinct from `policy-refusal` because the remedy is opposite --
+   * the same content succeeds once the parameter is adjusted.
+   */
+  "parameter-rejected",
+  /** Opaque replay state was rejected as unverifiable. Only a request without it can succeed. */
+  "ciphertext-refusal",
+  /**
+   * The payload exceeded a size the origin accepts. A smaller rebuild of the same turn can
+   * succeed, which is why this is not the same answer as `payload-rejected`.
+   */
+  "payload-too-large",
+  /** The payload was rejected on its merits: unsupported media, malformed part. No repair helps. */
+  "payload-rejected",
+  /**
+   * The origin returned a server-side fault. Whether it had already begun the turn is not
+   * knowable from the status, so this is the honest classification for the mixed 5xx set the
+   * transient layer retries: 503 really did decline, 500 may not have.
+   */
+  "upstream-fault",
+  /** The turn settled carrying no usable output. */
+  "empty-output",
+  /** The caller went away. */
+  "client-cancelled",
+  /** This proxy refused before dispatch: send budget, route policy, replay refusal. */
+  "local-refusal",
+] as const);
+
+export type RequestFailureCause = typeof REQUEST_FAILURE_CAUSES[number];
+
+/**
+ * Whether this proxy may send the request again. Derived at READ time from the stage and the
+ * cause and never persisted, so a stored row cannot carry a verdict that the current table
+ * would no longer reach.
+ *
+ * Every refusal names WHY it refused, because the three reasons need different operator
+ * responses and used to arrive as one undifferentiated "no retry".
+ */
+export const RESEND_PERMISSIONS = Object.freeze([
+  /** The same request may be sent again. */
+  "permitted",
+  /** Only a modified request may be sent: rotated credential, stripped ciphertext. */
+  "permitted-after-repair",
+  /** Upstream execution state is unknown. No AUTOMATIC resend. */
+  "refused-ambiguous",
+  /** The caller already observed output or an externally visible effect. */
+  "refused-committed",
+  /** Identical bytes would get the identical answer. */
+  "refused-futile",
+] as const);
+
+export type ResendPermission = typeof RESEND_PERMISSIONS[number];
+
+/**
+ * Where a terminal or failure was observed on the wire.
+ *
+ * Declared here because three modules read it as a closed set -- the durable row's validator,
+ * the failure attribution and the failure fingerprint -- and a fourth restatement in a test is
+ * how a member added later leaves an "exhaustive" cross product green without exercising it.
+ */
+export const REQUEST_TRANSPORT_PHASES = Object.freeze([
+  "pre_headers",
+  "mid_stream",
+  "terminal_sse",
+] as const);
+
+export type RequestTransportPhase = typeof REQUEST_TRANSPORT_PHASES[number];
+
+/**
+ * What an attempt actually delivered, as five bounded counts (#3983).
+ *
+ * #3983 wanted these signals and emitted one debug line per event to get them. That is a second
+ * durable record: `emitDebugLine` writes the in-process ring AND stderr, and stderr is redirected
+ * to the service log under both launchd and systemd, so an installed service ends up with a
+ * per-event history beside the ledger, carrying its own retention, sequencing and identity. It
+ * also fingerprinted each payload under a process-global random key, which makes every repeated
+ * prompt fragment, tool name and error message correlatable for the process lifetime.
+ *
+ * Counts answer the same questions -- a missing terminal, adapter-to-client loss, empty output,
+ * partial output size -- and cannot carry content at all. They ride the attempt, so they inherit
+ * the ledger's normalization, masking and retention rather than acquiring their own.
+ *
+ * Counted where the event is DELIVERED, not where it is read. An adapter event the client never
+ * received is exactly the discrepancy worth seeing, and counting both ends at the reader would
+ * make the two numbers equal by construction.
+ */
+export interface AttemptDeliverySummary {
+  /** Events this attempt's adapter produced. */
+  adapterEvents: number;
+  /** Frames that reached the client transport, after a successful enqueue. */
+  relayedEvents: number;
+  /** UTF-8 bytes of output-bearing delta actually relayed. Never the content itself. */
+  semanticBytes: number;
+  /** Externally visible effects relayed: a tool call or a search call starting. */
+  sideEffectEvents: number;
+  /** Terminal frames relayed. Zero on a delivered stream is the missing-terminal signal. */
+  terminalEvents: number;
+}
+
+/**
+ * What one logical request spent upstream, decomposed by how much of it is explained.
+ *
+ * The counting half of the durable spend record, without the routing detail that sits beside it.
+ * Every surface that reports a send total reads these three numbers and none of them recomputes a
+ * total of its own -- a recomputed total is how the exporter and the dashboard ended up reporting
+ * different send counts for the same request.
+ */
+export interface RequestSpendTotals {
+  /** Physical upstream sends summed across every attempt, combo children included. */
+  sends: number;
+  /** Sends whose attempt reached a terminal status, so the spend has a known outcome. */
+  settled: number;
+  /**
+   * Sends charged with no terminal outcome behind them: an attempt abandoned mid-flight, or a
+   * budget charge no attempt row ever accounted for. Never folded into `settled` -- an unexplained
+   * send is the exact quantity this record exists to make visible.
+   */
+  unresolved: number;
+  /** Model sends the request execution budget charged. Absent when no budget was attached. */
+  reserved?: number;
+}
diff --git a/src/usage/timeline.ts b/src/usage/timeline.ts
new file mode 100644
index 00000000000..af44587f512
--- /dev/null
+++ b/src/usage/timeline.ts
@@ -0,0 +1,219 @@
+import { cacheTokensFromUsage, usageAttributions } from "./summary";
+import type { PersistedUsageEntry } from "./log";
+import { usageDisplayTotalTokens } from "./totals";
+
+export type TimelineMetric = "total" | "input" | "output" | "cached";
+export type TimelineAggregation = "sum" | "average" | "max";
+export type TimelineGrouping = "model" | "modelAccount";
+export const TIMELINE_HOURS = [6, 24, 72, 168] as const;
+
+export interface TimelineQuery {
+  hours: typeof TIMELINE_HOURS[number];
+  bucketMinutes: number;
+  metric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  grouping: TimelineGrouping;
+  models: string[] | null;
+  now: number;
+}
+
+export interface TimelineSeries {
+  id: string;
+  provider: string;
+  model: string;
+  accountLogLabel?: string;
+  total: number;
+  points: number[];
+}
+
+export interface UsageTimeline {
+  start: number;
+  end: number;
+  bucketSeconds: number;
+  buckets: number;
+  metric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  grouping: TimelineGrouping;
+  series: TimelineSeries[];
+  availableModels: string[];
+  missingMeasurements: number;
+  truncated: boolean;
+}
+
+const METRICS: readonly TimelineMetric[] = ["total", "input", "output", "cached"];
+const AGGREGATIONS: readonly TimelineAggregation[] = ["sum", "average", "max"];
+const GROUPINGS: readonly TimelineGrouping[] = ["model", "modelAccount"];
+
+function enumValue<T extends string>(value: string | null, values: readonly T[], fallback: T): T | { error: string } {
+  if (value === null || value === "") return fallback;
+  return values.includes(value as T) ? value as T : { error: `invalid value for parameter: ${value}` };
+}
+
+function parseModels(raw: string | null): string[] | null | { error: string } {
+  if (raw === null || raw.trim() === "") return null;
+  const models = raw.split(",").map(model => model.trim());
+  if (models.length > 100) return { error: "models must contain at most 100 identifiers" };
+  if (models.some(model => !/^[^/\s]+\/[^/\s]+$/.test(model))) {
+    return { error: "models must contain provider/model identifiers" };
+  }
+  return [...new Set(models)];
+}
+
+export function parseTimelineQuery(params: URLSearchParams, now: number): TimelineQuery | { error: string } {
+  const rawHours = params.get("hours") ?? "24";
+  const hoursNumber = Number(rawHours);
+  if (!TIMELINE_HOURS.includes(hoursNumber as typeof TIMELINE_HOURS[number])) {
+    return { error: "hours must be one of 6, 24, 72, 168" };
+  }
+  const bucketMinutes = Number(params.get("bucketMinutes") ?? "60");
+  if (!Number.isInteger(bucketMinutes) || bucketMinutes < 1 || bucketMinutes > 1440) {
+    return { error: "bucketMinutes must be an integer from 1 through 1440" };
+  }
+  const buckets = Math.ceil(hoursNumber * 60 / bucketMinutes);
+  if (buckets > 2000) return { error: "timeline bucket count must not exceed 2000" };
+  const metric = enumValue(params.get("metric"), METRICS, "total");
+  if (typeof metric !== "string") return metric;
+  const aggregation = enumValue(params.get("aggregation"), AGGREGATIONS, "sum");
+  if (typeof aggregation !== "string") return aggregation;
+  const grouping = enumValue(params.get("grouping"), GROUPINGS, "model");
+  if (typeof grouping !== "string") return grouping;
+  const models = parseModels(params.get("models"));
+  if (typeof models === "object" && models !== null && "error" in models) return models;
+  if (!Number.isFinite(now)) return { error: "now must be finite" };
+  return {
+    hours: hoursNumber as TimelineQuery["hours"],
+    bucketMinutes,
+    metric,
+    aggregation,
+    grouping,
+    models: models as string[] | null,
+    now,
+  };
+}
+
+interface SeriesState {
+  provider: string;
+  model: string;
+  accountLogLabel?: string;
+  points: number[];
+  requests: Map<number, Map<string, number>>;
+}
+
+function metricValue(metric: TimelineMetric, attribution: ReturnType<typeof usageAttributions>[number]): number | undefined {
+  if (metric === "total") return usageDisplayTotalTokens(attribution.usage, attribution.totalTokens);
+  if (metric === "input") return attribution.usage?.inputTokens;
+  if (metric === "output") return attribution.usage?.outputTokens;
+  return cacheTokensFromUsage(attribution.usage).read;
+}
+
+export function createTimelineAccumulator(query: TimelineQuery): { add(entry: PersistedUsageEntry): void; finish(): UsageTimeline } {
+  const bucketSeconds = query.bucketMinutes * 60;
+  const start = Math.floor((query.now - query.hours * 3_600_000) / 1000 / bucketSeconds) * bucketSeconds;
+  const buckets = Math.ceil(query.hours * 60 / query.bucketMinutes);
+  const end = start + buckets * bucketSeconds;
+  const startMs = start * 1000;
+  const endMs = end * 1000;
+  const series = new Map<string, SeriesState>();
+  const availableModels = new Set<string>();
+  let missingMeasurements = 0;
+
+  function add(entry: PersistedUsageEntry): void {
+    if (entry.timestamp < startMs || entry.timestamp >= endMs) return;
+    const bucket = Math.floor((entry.timestamp - startMs) / (bucketSeconds * 1000));
+    if (bucket < 0 || bucket >= buckets) return;
+    for (const attribution of usageAttributions(entry)) {
+      const modelId = `${attribution.provider}/${attribution.model}`;
+      availableModels.add(modelId);
+      if (query.models && !query.models.includes(modelId)) continue;
+      const id = query.grouping === "model"
+        ? modelId
+        : `${modelId} · ${attribution.accountLogLabel ?? "unknown"}`;
+      let state = series.get(id);
+      if (!state) {
+        state = {
+          provider: attribution.provider,
+          model: attribution.model,
+          ...(query.grouping === "modelAccount" ? { accountLogLabel: attribution.accountLogLabel ?? "unknown" } : {}),
+          points: Array<number>(buckets).fill(0),
+          requests: new Map(),
+        };
+        series.set(id, state);
+      }
+      const value = metricValue(query.metric, attribution);
+      if (value === undefined) {
+        missingMeasurements += 1;
+        continue;
+      }
+      if (query.aggregation === "sum") {
+        state.points[bucket] = (state.points[bucket] ?? 0) + value;
+      } else {
+        let requests = state.requests.get(bucket);
+        if (!requests) {
+          requests = new Map();
+          state.requests.set(bucket, requests);
+        }
+        requests.set(attribution.requestId, (requests.get(attribution.requestId) ?? 0) + value);
+      }
+    }
+  }
+
+  function finish(): UsageTimeline {
+    const rows = [...series].map(([id, state]): { row: TimelineSeries; state: SeriesState } => {
+      if (query.aggregation !== "sum") {
+        for (const [bucket, requests] of state.requests) {
+          const values = [...requests.values()];
+          state.points[bucket] = query.aggregation === "max"
+            ? Math.max(...values)
+            : values.reduce((sum, value) => sum + value, 0) / values.length;
+        }
+      }
+      const total = state.points.reduce((sum, value) => sum + value, 0);
+      return {
+        row: {
+          id,
+          provider: state.provider,
+          model: state.model,
+          ...(state.accountLogLabel !== undefined ? { accountLogLabel: state.accountLogLabel } : {}),
+          total,
+          points: state.points,
+        },
+        state,
+      };
+    }).sort((left, right) => right.row.total - left.row.total || left.row.id.localeCompare(right.row.id));
+    const kept = (rows.length > 24 ? rows.slice(0, 23) : rows).map(({ row }) => row);
+    if (rows.length > 24) {
+      const otherPoints = Array<number>(buckets).fill(0);
+      const folded = rows.slice(23);
+      if (query.aggregation === "sum") {
+        for (const { row } of folded) {
+          for (let index = 0; index < buckets; index += 1) otherPoints[index] = (otherPoints[index] ?? 0) + (row.points[index] ?? 0);
+        }
+      } else {
+        for (let index = 0; index < buckets; index += 1) {
+          const values = folded.flatMap(({ state }) => [...(state.requests.get(index)?.values() ?? [])]);
+          if (values.length > 0) {
+            otherPoints[index] = query.aggregation === "max"
+              ? Math.max(...values)
+              : values.reduce((sum, value) => sum + value, 0) / values.length;
+          }
+        }
+      }
+      kept.push({ id: "other", provider: "", model: "other", total: otherPoints.reduce((sum, value) => sum + value, 0), points: otherPoints });
+    }
+    return {
+      start,
+      end,
+      bucketSeconds,
+      buckets,
+      metric: query.metric,
+      aggregation: query.aggregation,
+      grouping: query.grouping,
+      series: kept,
+      availableModels: [...availableModels].sort(),
+      missingMeasurements,
+      truncated: false,
+    };
+  }
+
+  return { add, finish };
+}
diff --git a/src/web-search/alpha-search.ts b/src/web-search/alpha-search.ts
index 3bdd64853ad..1b4489bfbe5 100644
--- a/src/web-search/alpha-search.ts
+++ b/src/web-search/alpha-search.ts
@@ -14,6 +14,8 @@
 import { formatErrorResponse } from "../bridge";
 import { redactSecretString } from "../lib/redact";
 import { sidecarEnter } from "../lib/sidecar-tracker";
+import { admissionScopeDenial } from "../server/admission-model-scope";
+import type { DataPlaneAdmission } from "../server/auth-cors";
 import type { OcxConfig, OcxProviderConfig, OcxWebSearchSidecarConfig } from "../types";
 import { runAnthropicWebSearch } from "./anthropic-executor";
 import { runExaWebSearch } from "./exa-executor";
@@ -252,6 +254,7 @@ export async function handleAlphaSearchSidecarFallback(
   config: OcxConfig,
   signal?: AbortSignal,
   logCtx?: { provider: string },
+  admission?: DataPlaneAdmission,
 ): Promise<Response> {
   const resolution = resolveAlphaSearchSidecar(config);
   if (resolution.status === "missing-credential") {
@@ -266,6 +269,24 @@ export async function handleAlphaSearchSidecarFallback(
   const resolved = resolution.sidecar;
   if (logCtx) logCtx.provider = resolved.backend;
 
+  // This backend is a paid destination like any other, and the operator's
+  // configuration -- not the caller -- decides which one and which model. A key
+  // scoped away from it must not spend it by asking the search endpoint instead
+  // of the inference one. Exa has no configured provider entry, so its own
+  // backend name is the destination.
+  const settings = sidecarSettingsForAlphaSearch(resolved.backend, config);
+  const requestedModel = (body as { model?: unknown } | null)?.model;
+  const denial = admissionScopeDenial(
+    config,
+    admission,
+    typeof requestedModel === "string" && requestedModel.trim() ? requestedModel : undefined,
+    {
+      providerName: resolved.backend === "exa" ? resolved.backend : resolved.providerName,
+      modelId: settings.model,
+    },
+  );
+  if (denial) return denial;
+
   const queries = extractAlphaSearchQueries(body);
   if (queries.length === 0) {
     return formatErrorResponse(
@@ -275,7 +296,6 @@ export async function handleAlphaSearchSidecarFallback(
     );
   }
 
-  const settings = sidecarSettingsForAlphaSearch(resolved.backend, config);
   const sidecarExit = sidecarEnter("search");
   try {
     const texts: string[] = [];
diff --git a/structure/INDEX.md b/structure/INDEX.md
index cd101960def..bfd932df79a 100644
--- a/structure/INDEX.md
+++ b/structure/INDEX.md
@@ -78,6 +78,7 @@ Background service, docs, release, and design discipline.
 
 | Doc | Scope |
 | --- | --- |
+| [`desktop-shell.md`](desktop-shell.md) | Tauri desktop shell, proxy attachment and sidecar lifecycle, tray controls, bootstrap navigation, and desktop companion presence. |
 | [`ops/service-and-sidecars.md`](ops/service-and-sidecars.md) | Service install/repair, platform launchers, tray, and sidecar processes. |
 | [`ops/docs-and-release.md`](ops/docs-and-release.md) | Docs site, workflow map, branch policy, release flow, and cross-platform CI. |
 | [`design-methodology.md`](design-methodology.md) | Stage ordering for new GUI, CLI, and user-facing surfaces. |
@@ -90,7 +91,9 @@ A source area can be described by more than one doc, because these docs are orga
 | Source path | Described by |
 | --- | --- |
 | `.github/` | [`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `app/` | [`overview.md`](overview.md) |
 | `bin/` | [`runtime.md`](runtime.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `desktop/` | [`desktop-shell.md`](desktop-shell.md) |
 | `docs-site/` | [`ops/docs-and-release.md`](ops/docs-and-release.md) |
 | `gui/` | [`overview.md`](overview.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md)<br>[`design-methodology.md`](design-methodology.md) |
 | `scripts/` | [`overview.md`](overview.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
@@ -103,6 +106,7 @@ A source area can be described by more than one doc, because these docs are orga
 | `src/clients/` | [`clients/integrations.md`](clients/integrations.md) |
 | `src/codex/` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md)<br>[`codex-home.md`](codex-home.md)<br>[`catalog.md`](catalog.md)<br>[`subagents.md`](subagents.md)<br>[`providers/openai-tiers.md`](providers/openai-tiers.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
 | `src/combos/` | [`runtime.md`](runtime.md)<br>[`providers-and-adapters.md`](providers-and-adapters.md) |
+| `src/companion/` | [`overview.md`](overview.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md) |
 | `src/compatibility/` | [`runtime.md`](runtime.md)<br>[`adapters/compatibility-contracts.md`](adapters/compatibility-contracts.md) |
 | `src/config.ts` | [`overview.md`](overview.md)<br>[`runtime.md`](runtime.md)<br>[`config.md`](config.md)<br>[`providers/openai-tiers.md`](providers/openai-tiers.md) |
 | `src/config/` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md) |
@@ -124,6 +128,7 @@ A source area can be described by more than one doc, because these docs are orga
 | `src/routing/` | [`catalog.md`](catalog.md) |
 | `src/server/` | [`runtime.md`](runtime.md)<br>[`catalog.md`](catalog.md)<br>[`subagents.md`](subagents.md)<br>[`transports/byte-accounting.md`](transports/byte-accounting.md)<br>[`transports/responses.md`](transports/responses.md)<br>[`transports/streaming-health.md`](transports/streaming-health.md)<br>[`transports/inventory.md`](transports/inventory.md)<br>[`data-planes/images.md`](data-planes/images.md)<br>[`data-planes/inbound-compat.md`](data-planes/inbound-compat.md)<br>[`providers-and-adapters.md`](providers-and-adapters.md)<br>[`providers/xai-grok.md`](providers/xai-grok.md)<br>[`adapters/registry.md`](adapters/registry.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md)<br>[`ops/service-and-sidecars.md`](ops/service-and-sidecars.md) |
 | `src/server/index.ts` | [`adapters/compatibility-lab.md`](adapters/compatibility-lab.md) |
+| `src/server/management/companion-routes.ts` | [`desktop-shell.md`](desktop-shell.md) |
 | `src/service.ts` | [`runtime.md`](runtime.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
 | `src/service/` | [`runtime.md`](runtime.md) |
 | `src/stall-timeout.ts` | [`runtime.md`](runtime.md) |
@@ -132,6 +137,7 @@ A source area can be described by more than one doc, because these docs are orga
 | `src/types.ts` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md) |
 | `src/update/` | [`runtime.md`](runtime.md) |
 | `src/usage/` | [`runtime.md`](runtime.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md) |
+| `src/usage/timeline.ts` | [`gui-and-management-api.md`](gui-and-management-api.md) |
 | `src/vision/` | [`runtime.md`](runtime.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md) |
 | `src/web-search/` | [`runtime.md`](runtime.md)<br>[`providers-and-adapters.md`](providers-and-adapters.md) |
 
diff --git a/structure/adapters/registry.md b/structure/adapters/registry.md
index 28a464e3e03..d1d67b5dc31 100644
--- a/structure/adapters/registry.md
+++ b/structure/adapters/registry.md
@@ -16,8 +16,9 @@ Shared parsing and streaming follow the [request-copy](../transports/byte-accoun
 
 Runtime adapter construction has one authority: `src/adapters/registry.ts`.
 
-The OpenCode Go [chronological instruction exception](../providers/chat-compat.md#opencode-go-chronological-instructions)
-uses the provider registry's destination identity inside the Chat adapter; it adds no adapter factory.
+[Chronological instruction ordering](../providers/chat-compat.md#chronological-in-conversation-instructions)
+is now uniform across destinations, so the Chat adapter no longer consults the provider registry's
+destination identity for it; it adds no adapter factory.
 
 `src/server/adapter-resolve.ts` may resolve a provider/model onto an adapter id, but it does not maintain a second adapter factory inventory. The selected persisted/configured adapter id remains an untrusted string until the registry lookup succeeds. Unknown ids fail with the existing `Unknown adapter: <id>` error instead of widening configuration types around a closed compile-time union.
 
@@ -173,7 +174,7 @@ Pool quota producers and account commands follow the [bounded raw-observation co
 
 Account quota surfaces use [safe probe diagnostics](../transports/inventory.md#account-quota-failure-diagnostics) separately from quota validity, credential health and routing authority.
 
-Combo child requests normalize effort and thinking controls against the selected target while retaining reasoning summaries; strict unknown targets preserve caller controls. The [Responses transport owner](../transports/responses.md) documents this boundary, and native Chat removes effort only for an explicit empty declaration or no-reasoning model.
+Combo child requests normalize effort and thinking controls against the selected target while retaining reasoning summaries; strict unknown targets preserve caller controls. The [Responses transport owner](../transports/responses.md) documents this boundary. Translated and native Chat builders share explicit gateway-object and tool-bearing effort-omission policy after provider resolution; native Chat otherwise preserves caller controls and removes effort for an explicit empty declaration or no-reasoning model.
 
 Live sideband admission and its bounded upstream handshake follow the [runtime contract](../runtime.md#live-sideband-handshake); the ordinary Responses WebSocket exchange remains separate.
 
@@ -196,8 +197,18 @@ variant; unrelated model families retain their existing suffix precedence.
 
 `src/responses/input-media.ts` inspects actual content blocks and typed tool-output arrays
 without parsing text or function arguments, copying attachment payloads, resolving file IDs,
-or fetching URLs. Audio, files/documents and file-ID-only images have no lossless normalized
-carrier. The scanner returns only an input-kind name, never client content.
+or fetching URLs. Audio and file-ID-only images have no lossless normalized carrier, and
+neither does a file or document reference that carries no bytes. The scanner returns only an
+input-kind name, never client content.
+
+A document that carries its own base64 bytes is the one exception, and only in user or
+developer message content: `src/responses/inline-document.ts` decodes it into the
+`OcxDocumentContent` part, which the Anthropic, OpenAI Chat and Gemini wires emit as a native
+document, file part and `inline_data` respectively. Every other position — tool output, system
+and assistant content — is still refused, because those converters reduce their content to text
+and exempting them would restore the silent drop the scanner exists to prevent. The scanner and
+the decoder share one predicate so a request cannot be exempted here and reduced to a marker
+there.
 
 `src/adapters/input-media-guard.ts` guards adapters created by the registry after effective
 wire selection. A translated `buildRequest` refuses these inputs through the existing 400
diff --git a/structure/catalog.md b/structure/catalog.md
index e74edcb8adb..7b035ee99fc 100644
--- a/structure/catalog.md
+++ b/structure/catalog.md
@@ -166,6 +166,10 @@ Provider live-model lists are cached with a configured TTL (`src/codex/model-cac
 deleting, or editing a provider's shape clears that per-provider cache; a disabled-only change
 deliberately does not, because a disabled provider is already excluded from the catalog gather
 instead. Codex's own `models_cache.json` is a different cache, invalidated by catalog refresh.
+Entitlement-specific rosters (Qoder, Devin, Cursor) additionally bind their cache entry to an
+irreversible credential fingerprint: a credential switch observes neither the fresh nor the stale
+roster recorded under the previous credential, and a failed discovery's cooldown neither supplies
+the previous credential's stale roster nor suppresses the next credential's first discovery.
 
 A Devin live row spreads its measured `inputModalities` before
 `catalogHintsFromProviderConfig`, so exact `modelCapabilities` declarations, the legacy
diff --git a/structure/clients/claude-desktop.md b/structure/clients/claude-desktop.md
index 3aec2c2d3cc..8e73c82187c 100644
--- a/structure/clients/claude-desktop.md
+++ b/structure/clients/claude-desktop.md
@@ -29,6 +29,49 @@ Native OpenAI pool routing also accepts
 [Orca-linked accounts](../codex-home.md#orca-source-owned-account-import), whose source resolution
 belongs to the shared account store. The import CLI adds pool rows independently of Desktop profiles.
 
+## Desktop modes: first-party and gateway
+
+`src/claude/desktop-first-party.ts` owns the Desktop mode contract. Two modes exist and are
+mutually exclusive on one machine:
+
+- **first-party** (default): Claude Desktop itself is left on claude.ai — login, Chat tab,
+  connectors and remote control are untouched and no config-library profile is written. The apply
+  writes only `HTTPS_PROXY=http://127.0.0.1:<port+100>` and `NODE_EXTRA_CA_CERTS=<config>/claude-intercept/ca.pem`
+  into the `env` block of Claude Code's `settings.json` (via `src/claude/intercept/settings.ts`),
+  creating the local authority first. Only the Claude Code process Desktop spawns for the Code tab
+  (and its subagents, and any standalone `claude` CLI) reads that env, so only their
+  `api.anthropic.com` traffic reaches the [Claude intercept pair](../runtime.md#claude-intercept-pair).
+- **gateway**: the existing third-party profile written by `src/claude/desktop-3p.ts`; the whole
+  app switches to the local gateway. It is selected explicitly (`--gateway`, dashboard, or the
+  legacy `--static|--hybrid|--discovery-only` shape flags, which imply it).
+
+`resolveClaudeDesktopMode` returns the explicit `claudeCode.desktopMode` when set; otherwise a
+persisted `desktopProfile.appliedFingerprint` (an existing gateway install) keeps `gateway`, and a
+fresh install resolves to `first-party`. Updates therefore never flip a working gateway install
+silently, while new installs land on first-party. `resolveClaudeDesktopApplyMode` narrows an
+*implied* first-party to gateway where the intercept pair cannot run (client role or
+`claudeCode.intercept.enabled: false`); an explicit `first-party` is refused with
+`intercept_disabled` instead of being rewritten.
+
+Switching is ownership-aware in both directions: a gateway apply first removes the first-party env
+(only values anchored on OpenCodex's own CA path); a first-party apply first pivots an owned
+gateway profile (`gateway_ours`/`gateway_drifted`) back to standard through
+`removeDesktop3pStandardPivot({ replaceWhileEnabled: true })` — the durable switch stays ON, so the
+OFF-flow desired-state guard is bypassed on purpose — and fails (`claude_desktop_gateway_removal_failed`)
+without writing the env if that pivot cannot complete. It refuses (`foreign_env`) when
+`settings.json` already carries a proxy/CA value OpenCodex does not own.
+Disabling the integration (native toggle, `ocx ensure` with the durable switch OFF) removes both the
+gateway profile and the first-party env. With the switch ON in first-party mode, `ocx ensure`
+re-applies a stale env (the proxy port follows the public port).
+
+Surfaces: `ocx claude desktop apply [--first-party|--gateway]` in `src/cli/claude-desktop.ts`;
+`POST /api/claude-desktop/apply` with `mode` ∈ `first-party|gateway|static|hybrid|discovery` and
+`GET /api/claude-desktop/status` (`mode`, `firstParty.{applied,stale,interceptEnabled,interceptRunning,proxyPort,caCertPath}`)
+in `src/server/management/agent-settings-routes.ts`; the native toggle in
+`src/server/management/native-integration-routes.ts` applies the resolved mode on enable. Managed
+Windows policy health only applies in gateway mode, because first-party never touches Desktop's own
+configuration. Ordinary Chat-tab traffic is out of scope for both modes.
+
 ## Connected Claude Desktop profiles
 
 The connection's local Codex readiness check follows the [selected-runtime probe contract](../runtime.md#remote-hub-hardening-ownership); general status hands its resolved command to this check instead of probing the version twice.
diff --git a/structure/clients/integrations.md b/structure/clients/integrations.md
index 402a60e07f0..b3e7650f0f7 100644
--- a/structure/clients/integrations.md
+++ b/structure/clients/integrations.md
@@ -6,6 +6,8 @@ The client-integration subsystem writes one generated OpenCodex provider contrib
 third-party client's existing config without taking ownership of the rest of that file. Its core
 promise is reversibility: apply snapshots first, writes atomically, records exactly what it owns,
 and refuses refresh, disable, or restore when the current file cannot be classified safely.
+Managed client targets are inspected without following a final symbolic link, and their atomic
+replacement addresses the named directory entry rather than resolving that link again at commit.
 
 Shared response support has a separate [bounded ingestion contract](../transports/inventory.md#bounded-response-ingestion-and-orcarouter-login):
 raw-byte callers own their byte and deadline budgets and inherit best-effort cancellation.
@@ -17,7 +19,8 @@ parsing and ownership rules below.
 | Module | Responsibility |
 | --- | --- |
 | `src/clients/config-export.ts` | Pure per-client config builders and the exact managed fragments each client receives. It never writes files. |
-| `src/integrations/registry.ts` | Canonical config/detection paths, source-preserving YAML declarations, writer-lock behavior, and client IDs. |
+| `src/integrations/registry.ts` | Canonical config/detection paths, current-provider-store declarations, source-preserving YAML declarations, writer-lock behavior, and client IDs. |
+| `src/integrations/target.ts` | Which file one operation reads, writes and records, and whether a write there reaches the client. |
 | `src/integrations/config-io.ts` | Bounded file loading and parsing. Values that cannot round-trip through the target serializer are rejected before mutation. |
 | `src/integrations/state.ts` | The single `absent` / `current` / `stale` / `conflict` / `unsafe` classifier used by status and every writer operation. |
 | `src/integrations/ownership.ts` | Durable ownership records: file, generated contribution, protected contribution, exact fragment paths, and operation identity. |
@@ -207,6 +210,68 @@ fail closed. A successful refresh writes the new operation-scoped policy.
 
 > Decision record: [ADR-0092](../decisions/ADR-0092-zcode-runtime-metadata.md)
 
+## A store the client no longer reads
+
+A client may move its provider list to a different file between releases and keep the old one
+reachable only through a one-shot import. That import runs on an install that has never created the
+new file and never again, so every later write to the old path is read by nobody. ZCode 3.14 is the
+instance this rule was written for: the apply was correct, the ownership record was correct, the
+journal row was correct, and no model appeared in the client.
+
+A client in that position declares `currentStore` in the registry. The declaration is not only a
+location: it carries the text format of that file, the contribution shape its reader understands,
+and the predicate that decides whether a document on disk is a version whose shape has been
+observed. Naming the store without the last three would be naming a file we cannot write.
+
+`src/integrations/target.ts` turns that declaration into the one answer every surface uses: which
+file this operation reads, writes, journals and records, and whether a write there reaches the
+client. It decides from three facts, in order:
+
+1. No declared store, or no store on disk — the config file, unchanged. A client that has never run
+   still imports what we write there, which is why the rule keys on the store's presence rather
+   than on a client version.
+2. This project's own block already in one of the two files — that file. Disable removes what we
+   wrote from where we wrote it, and no apply leaves a block in one file while writing another.
+3. Otherwise the store, and only when its schema establishes.
+
+Four properties are load-bearing:
+
+- The store is observed through the same `IntegrationIO` seam as the config file, so status and
+  mutation cannot disagree about which file an operation is about. Only a regular file counts; a
+  failed stat is not evidence of a migration.
+- The ownership record, the journal row and the undo guard all follow the target rather than the
+  client. A row naming the store is restorable because the guard asks whether this client still
+  names that location, not whether it is the config file.
+- The refusal is bound into the plan fingerprint together with its reason, so a confirmation taken
+  before the client created its store cannot be committed afterwards — and neither can one taken
+  before the store's schema version moved under an unchanged path.
+- Disable is never gated on it. Removing bytes this project wrote from the file it wrote them to is
+  unaffected by where the client reads, and refusing it would leave the block unremovable through
+  the tool.
+
+Writing the store does not relax ownership anywhere. The store keys a model rule by the pair
+`(providerId, modelId)`, so the managed path names both: a selector naming only the model would
+match another provider's rule for the same model and replace it. A rule carrying this project's
+provider id that no record accounts for — including one the client's own migration created — is a
+conflict, and the explicit overwrite remains the only way past it.
+
+Persisted selector segments have two disjoint grammars owned by `src/integrations/merge.ts`.
+An unversioned `[field=value]` segment is permanently a one-criterion selector; commas and later
+equals signs remain part of its value, so an older ownership record keeps naming the same element.
+New multi-field selectors use the explicit `[v2:field=value,field=value]` grammar and are emitted by
+the shared formatter. A segment beginning with that reserved marker but failing the complete v2
+grammar is unreadable rather than a plain key or a v1 selector, so malformed persisted bytes cannot
+silently select a different element.
+
+A store whose schema cannot be established is reported, never merged into. That file holds the
+user's other providers and the client rewrites it on its own, so asserting a nesting we have not
+observed would trade a silent no-op for a silent loss. Status reports the store beside the file
+state rather than folding it into the state: `current` remains the truth about the file, and the
+notice appears only when the client reads some other file than the one the state is about.
+
+Deleting the client's store to re-trigger its own import is not implemented and must not be. It
+discards every provider the client keeps there.
+
 ## Verification
 
 Behavior changes require real writer tests against a temporary home and state store. At minimum,
@@ -280,3 +345,6 @@ existing explicit confirmation. The journal endpoint evaluates Undo against the
 Recovery reads commit history and ownership through strict store methods. Unreadable or malformed
 metadata is uncertainty, never evidence that a transaction did not commit. Pending records validate
 complete ownership, exact Cline paths and result fingerprints before either native file is replaced.
+Native pair writes replace the named directory entries without following final symlinks. A symlink
+present at validation is refused, and one exchanged into place during a mutation is refused rather
+than redirecting OpenCodex's write outside Cline's settings directory.
diff --git a/structure/codex-home.md b/structure/codex-home.md
index c7a6ef5248f..47177b946ae 100644
--- a/structure/codex-home.md
+++ b/structure/codex-home.md
@@ -321,6 +321,8 @@ What a detected migration does depends on which refusal it is, and on direction.
 
 On apply, that reason retires the relabel unit and the config/profile/journal write stands when the admitted candidate preserves any existing provider table. Retention is decided before witness construction and does not depend on history preflight passing: apply keeps any existing provider definition while selecting the requested root provider. This also protects references when native migration begins after artifact commit or during worker startup, without compensating over newer native writes. Background worker failures remain reported, and candidate bytes never change after admission. Any other reason there — an unreadable state database, a changed rollout identity, a preflight that could not run — may succeed on a later attempt, so it still restores all three preimages before returning a structured refusal, including on legacy-uncoordinated homes.
 
+`history_paginated_openai_requires_native_writer` is the one apply-side reason that is neither of those. It means a provider-table transition found an `openai`-tagged row already paginated, and the transition as planned would take the root `openai_base_url` out from under it. `applyPaginatedOpenaiCompat` in `src/codex/inject/paginated-openai-compat.ts` resolves it in the same window as the provider-table retention above, before the witness: it keeps the marker-owned root override beside the table and downgrades the reason to the stand-down constant, so the relabel unit never starts and the paginated row is neither read nor written. The retained line is journaled as OpenCodex's own, which is what lets restore remove it later; a line the user owns is left in place and journaled as theirs. Only an admission-token form still refuses, because Codex's built-in `openai` entry cannot carry `x-opencodex-api-key`, and that refusal names the configuration that resolves it rather than telling the operator not to retry (#5321).
+
 On restore and removal, that same reason no longer refuses the config half. It selects a degraded restore: every OpenCodex root routing key comes out, `[model_providers.opencodex]` is retained verbatim including its ownership marker, and the history relabel is skipped rather than attempted. The retained table is captured from the pre-transform bytes and re-appended into the same buffer, so the write is one atomic transformation — a config carrying root `model_provider = "opencodex"` without a matching table fails the whole Codex config load, not one thread, which makes that intermediate state strictly worse than the routing it replaces. `resolveRestoreHistoryDisposition` in `src/codex/inject/restore.ts` is the single place that reads the preflight reason and answers the separate question of whether routing may come out. Every other reason keeps the hard refusal and compensates on every artifact, because retiring a provider definition its thread rows still name would orphan them. A failed config restore stops catalog/history work; coordinated restore rolls back its published remove transition. Legacy first-line provider patches are bound to the validated file identity before and after writing. These compensating checks do not provide a native-writer lock or authorize external ordinal allocation.
 
 The legacy external writer is now refused for affected rows in any store whose schema includes history_mode, even while their row mode is still legacy. This deliberately sacrifices automatic relabeling on migration-capable stores rather than racing native conversion. It no longer costs the home its ability to be uninstalled: synchronous and asynchronous restore, inline journal restore, and direct config removal all take routing down on that reason while keeping the provider table, so an already-paginated home can be stopped and uninstalled and plain `codex` returns to the built-in provider. Rows naming `opencodex` still resolve through the retained table; their requests reach a proxy that is gone and fail with an ordinary connection error, which is a per-conversation failure rather than a broken config. `ocx restore --remove-codex-provider-table` removes the table for a user who accepts that those conversations stop opening; nothing selects it implicitly.
diff --git a/structure/config.md b/structure/config.md
index 5d68a5ad766..12cf9acbd10 100644
--- a/structure/config.md
+++ b/structure/config.md
@@ -64,7 +64,8 @@ owner-only state and is validated before a record is returned. `src/config.ts` r
 symbols for compatibility, but new lifecycle-only callers import the process-state leaf directly.
 
 Replacing config and process-state writes use `src/config/atomic-write.ts`. The leaf preserves the shared
-process-wide temp sequence, symlink target resolution, real-home test guard, owner manifest,
+process-wide temp sequence, symlink target resolution, no-follow directory-entry replacement for
+externally writable integration directories, real-home test guard, owner manifest,
 Windows ACL hardening, scrub-before-unlink failure path, and explicit residual-temp errors. A caller
 must not replace it with a local temp-and-rename shortcut.
 
@@ -89,6 +90,7 @@ matters for maintainers is which groups exist and who resolves them:
 | Retained state | `appOwnedMemoryBudgetMb` | Process-wide eviction target for app-owned logs, caches, blobs, and continuation payloads. Default 256 MiB, valid 64..4096; pinned state may temporarily exceed the target, but every pin-capable store has a finite local cap and their documented aggregate stays below `APP_OWNED_WORST_CASE_PINNED_BYTES` (512 MiB). Neither value caps RSS or native runtime memory. |
 | Spend | `spend.root`, `spend.identity`, `spend.pool`, `spend.retentionDays` | Durable token ceilings for the spend-reservation ledger. Absent is the default and means observe-only accounting: spend is still journaled and nothing is refused, so observe-only and enforced servers take the same state-directory writer lease. One live process may write one directory; explicit sibling instances need separate `OPENCODEX_HOME` directories. There is no default figure for any scope — the ledger is on by default, so a shipped ceiling would refuse real traffic on upgrade against a number nobody chose. Strictly validated and positive-integer only, because 0 would read as a budget and refuse everything; a malformed section degrades to no ceiling, which is why the write path rejects it and load diagnostics report it. Resolution and application live in `src/lib/spend-reservation-ledger.ts`; see [`transports/responses.md`](transports/responses.md). |
 | Transport | stream mode, timeouts, proxy settings, `websockets`, `emptyCompletionRetry` | `streamMode` persists in config.json; Windows services need a persisted input, and macOS uses it for explicit eager-relay opt-in. Empty-completion replay is an explicit top-level opt-in because its second upstream request may be billable. |
+| Provider egress | `providers.<name>.proxy`, `providers.<name>.noProxy` | An absent `proxy` inherits global egress; `"direct"` or `null` forces direct egress; HTTP(S) and SOCKS5(H) URLs select a provider-owned proxy. `noProxy` uses NO_PROXY syntax and sends a matching destination direct across either a provider-owned or inherited global proxy. `src/lib/provider-egress.ts` owns parsing and request-local resolution. |
 | Credentials | `apiKeys` | Data-plane only; never admitted to `/api/*`. |
 | Lifecycle | `codexAutoStart`, shim/start behavior, resume-history sync, storage cleanup | Startup safety reads these; see [`gui-and-management-api.md`](gui-and-management-api.md). |
 
@@ -229,9 +231,24 @@ converged and suppress the relabel permanently.
 
 That stand-down applies only when the provider tags left in place still resolve through the
 resulting configuration. A provider-table transition that finds a paginated `openai` row returns
-`history_paginated_openai_requires_native_writer` and refuses the artifact transaction: removing
-the root `openai_base_url` without relabeling that row would route a resumed conversation through
-Codex's built-in OpenAI provider instead of this proxy.
+`history_paginated_openai_requires_native_writer`, because removing the root `openai_base_url`
+without relabeling that row would route a resumed conversation through Codex's built-in OpenAI
+provider instead of this proxy. That reason selects a third state rather than a refusal:
+`src/codex/inject/paginated-openai-compat.ts` keeps the marker-owned root override beside the
+provider table, exactly as the client-compaction form already does, and the transition completes
+with the relabel standing down. Codex merges the override onto its built-in `openai` entry when
+it builds the provider map, so the row keeps reaching this proxy while never being rewritten, and
+the retained value is journaled as OpenCodex's own so restore can still take it out.
+
+Two cases cannot reach that state. An admission-token form cannot use the root key at all —
+Codex's built-in entry carries no `x-opencodex-api-key` header — so it keeps the refusal, and the
+message names the two configuration keys that resolve it (`unauthenticatedLoopbackListener`,
+`syncResumeHistory`) instead of saying only "do not retry". A root line the user owns is left
+alone and the conversation follows the destination they chose, which is the same guarantee the
+injector makes everywhere else about a line it does not own. Refusing the whole transition with
+no named way forward was the 2.60.0 regression in #5321: nothing was written, the integration
+stayed disabled, and the only exits a reporter could find were deleting the affected
+conversations or downgrading.
 
 Rows this home tagged `opencodex` resolve through a `[model_providers.opencodex]` table.
 Apply retains that existing definition before building the candidate witness, even when
diff --git a/structure/data-planes/images.md b/structure/data-planes/images.md
index 691b629bdc3..13ee416cac4 100644
--- a/structure/data-planes/images.md
+++ b/structure/data-planes/images.md
@@ -47,6 +47,14 @@ The keyed path never enters `handleResponses`, so `src/server/images.ts` repeats
 `selectProactiveApiKeyTransport` inside the keyed branch and rebuilds Authorization from the
 returned clone rather than the earlier snapshot.
 
+A configured key's model and provider scope applies to whichever destination the request settles
+on: the ChatGPT forward account, the keyed provider, the xAI Imagine bridge, or the Antigravity
+fallback. It is evaluated against that destination rather than the selector in the body, because
+the bridge and the fallback choose their own model, and a body that names no model cannot satisfy
+a model list. A refusal is the same 403 the scope returns on the routed path, and a key with no
+scope reaches every destination as before. Coverage lives in
+`tests/server/api-key-scope-images.test.ts`.
+
 The API-key `openai-responses` path also adapts Codex's private standalone image tool to the public
 Responses tool surface. A complete `image_gen` namespace is lowered to safe
 `image_gen__<inner-name>` function aliases even when no hosted image tool is present, because public
diff --git a/structure/data-planes/inbound-compat.md b/structure/data-planes/inbound-compat.md
index e6171845efa..d063adc30a5 100644
--- a/structure/data-planes/inbound-compat.md
+++ b/structure/data-planes/inbound-compat.md
@@ -28,6 +28,20 @@ keep credentials and audio content out of redirects, request logs and durable st
 `tests/server/audio-transcriptions.test.ts` exercises the real ingress and synthetic upstream;
 `tests/server/api-key-attribution.test.ts` uses multipart fixtures for the HTTP auth matrix.
 
+`src/server/audio-upstream.ts` is also where a configured key's model and provider scope is
+applied, once for every audio surface that resolves through it: the model it is handed is the one
+the upstream will run — the transcription model, the live session model, the model a standalone
+socket names in its own query, or the model a bound call settled on when the same key created it —
+and a refused forward request releases its probe lease. `LiveCallBinding` records that model for
+exactly this reason, so a reconnect is judged on the call it rejoins rather than on a default.
+
+The native voice path in `src/server/live.ts` applies the same predicate but can name less. It
+records nothing about the calls it relays, so a join, and a call-create that sends no session
+model, name no destination at all; a key carrying a model list is refused there rather than
+admitted against an assumed default, while a provider-only scope and an unscoped key are
+unchanged. Coverage lives in `tests/server/api-key-scope-audio.test.ts` and
+`tests/server/api-key-scope-live.test.ts`.
+
 ## Streaming audio
 
 `src/server/audio-client.ts` recognizes explicit audio keys before local legacy admission.
@@ -51,9 +65,9 @@ separate. Coverage lives in `tests/server/audio-client.test.ts`,
 `tests/server/audio-dictation.test.ts` and `tests/server/live-call-bindings.test.ts`.
 
 Translated Claude timeline reminders use the Chat adapter's
-[OpenCode Go instruction ordering](../providers/chat-compat.md#opencode-go-chronological-instructions)
-on its exact supported route. This is separate from trailing-notice stabilization
-and from native Chat message passthrough.
+[chronological instruction ordering](../providers/chat-compat.md#chronological-in-conversation-instructions)
+on every destination. This is separate from trailing-notice stabilization and from
+native Chat message passthrough.
 
 Shared parsing and streaming follow the [request-copy](../transports/byte-accounting.md#request-copy-accounting) and [stream-buffer accounting](../transports/byte-accounting.md#stream-buffer-accounting) contracts. Response-attached WebSocket telemetry follows the [stage record identity contract](../transports/responses.md#passthrough-sse-stream-shapes-314).
 
@@ -80,7 +94,10 @@ take the Chat -> Responses -> Chat bridge below. `parallel_tool_calls` is emitte
 parallel tools (or pinned false by the existing provider opt-out contract).
 The native passthrough still applies the existing model capability authority to reasoning: an
 explicit empty ladder removes caller `reasoning_effort`, while an unknown ladder remains
-unclassified. This guard does not alter the separate raw service-tier contract.
+unclassified. The two Chat builders share the explicit wire policy after provider resolution:
+`reasoningWireFormat: "gateway-object"` projects the configured object shape, and a listed
+tool-bearing model omits reasoning effort on both paths. With neither declaration, native raw
+reasoning forwarding stays unchanged. This guard does not alter the separate raw service-tier contract.
 
 On the response side, the upstream `service_tier` echo (xAI Priority Processing, OpenAI fast
 tier) relays to the Chat Completions caller on every delivery shape: the non-streaming body
@@ -96,6 +113,21 @@ or storage semantics retain the existing Chat -> Responses -> Chat bridge.
 Chat-to-Responses traffic that lands on `api.meta.ai` inherits the same 64-character tool-name
 aliasing as native Responses; see [`responses.md`](../transports/responses.md).
 
+On that bridge, `src/chat/inbound.ts` decides where a `system` or `developer` message lands by
+where the caller wrote it. A leading block, before any conversational item exists, becomes
+`instructions`. One that arrives after the conversation has started becomes a chronological
+`role:"developer"` input item instead, the same representation `src/claude/inbound.ts` mints for a
+mid-conversation instruction, so the slot the caller chose survives to the adapter that preserves
+it. The role is `developer` rather than `system` because the native ChatGPT backend refuses a
+`system` item inside `input` and canonical forwarding folds a message-shaped `system` item back
+onto `instructions`. An instruction that arrives between a tool call and its result is held until
+the batch drains, or until the next user or assistant turn, so the pair the Kiro, Anthropic and
+Google mappers require to stay adjacent is never split. Placement on the wire is then owned by
+[chronological in-conversation instructions](../providers/chat-compat.md#chronological-in-conversation-instructions),
+which also decides which role that slot carries. Regression coverage is in
+`tests/responses/chat-inbound-developer-position.test.ts`, which compares the final upstream body
+on the native Chat route, a combo route and the Responses endpoint.
+
 The direct SSE relay accepts CRLF and arbitrary transport chunk boundaries while retaining at most
 one bounded event. EOF with an unterminated event and an event above the translator limit are typed
 upstream failures, never successful partial completions. Provider-controlled structured error
@@ -334,7 +366,11 @@ default and require an explicit `thinking:{type:"disabled"}` to stop.
 
 The native Chat path retains provider-native file/audio blocks. When a request instead needs
 Chat-to-Responses projection, `src/chat/inbound.ts` rejects recognized audio/file content
-before it can become empty text, regardless of message role. Legacy `function`-role images
+before it can become empty text. The one exception is a `file` part carrying inline base64
+bytes in a `user` message: that projection builds an `input_file` block and the bytes survive
+to any wire with a counterpart. The same part in a `system`, `developer`, `assistant` or
+`tool` message is still refused, because those branches flatten their content to a string.
+Legacy `function`-role images
 also return an explicit error; their call/result pairing is not implemented by this projection.
 Modern `tool` images continue through the existing following-user carrier. These errors state
 an OpenCodex conversion limit, not a provider capability claim. Final Responses-to-adapter
diff --git a/structure/data-planes/search.md b/structure/data-planes/search.md
index a8ddf286def..81953f4ef83 100644
--- a/structure/data-planes/search.md
+++ b/structure/data-planes/search.md
@@ -16,6 +16,12 @@ find instead of asking for ChatGPT auth, and the request reaches no other backen
 fails answers with its own diagnostic. The fallback never runs while a forward candidate exists,
 so the verbatim relay stays the path for a ChatGPT deployment.
 
+A configured key's scope covers both branches, each against what it actually reaches. An
+account-qualified selector is judged against its resolved route; an unqualified one against the
+account the upstream resolved and the model the body names; the fallback against the configured
+backend and the model that backend runs, with Exa named by its backend because it has no provider
+entry. `tests/server/api-key-scope-alpha-search.test.ts` covers the two unrouted branches.
+
 ## Standalone Search and exact account selectors
 
 `POST /v1/alpha/search` retains the selected model in its request body. When that value is an
diff --git a/structure/decisions/ADR-0097-post-write-app-server-freshness.md b/structure/decisions/ADR-0097-post-write-app-server-freshness.md
new file mode 100644
index 00000000000..070709ea12e
--- /dev/null
+++ b/structure/decisions/ADR-0097-post-write-app-server-freshness.md
@@ -0,0 +1,12 @@
+# ADR-0097 — decision recorded under "CLI Codex restart scope"
+
+- Contract owner: [runtime.md](../runtime.md#cli-codex-restart-scope)
+
+## Decision record
+
+- 목적과 의도: Avoid telling an operator to interrupt a fresh Codex session after a successful sync.
+- 기존 구현 및 제약 조건: Startup already classified catalog freshness, but the ordinary post-write CLI warning treated every running app-server as stale; explicit restart flags must keep their existing consent semantics.
+- 검토한 주요 대안: Warn on every running process; suppress every warning; classify only the advisory non-restart path from one process observation.
+- 선택한 방식: Retain command lines from the classifier's enumeration and warn only for the proven-stale subset.
+- 다른 대안 대신 이 방식을 선택한 이유: Presence alone cannot prove stale state, while suppressing every warning would hide a real in-memory catalog mismatch.
+- 장점, 단점 및 영향: Mixed fresh/stale sets name only stale PIDs and unknown observations stay quiet; explicit restart requests remain unchanged.
diff --git a/structure/decisions/ADR-0098-schema-bound-exec-command-input-repair.md b/structure/decisions/ADR-0098-schema-bound-exec-command-input-repair.md
new file mode 100644
index 00000000000..8640b675e42
--- /dev/null
+++ b/structure/decisions/ADR-0098-schema-bound-exec-command-input-repair.md
@@ -0,0 +1,12 @@
+# ADR-0098 — decision recorded under "Schema-bound flat shell repair"
+
+- Contract owner: [transports/responses.md](../transports/responses.md#schema-bound-flat-shell-repair)
+
+## Decision record
+
+- 목적과 의도: Let an unambiguous routed `exec_command` wrapper reach the Codex shell bridge without weakening tool identity or argument validation.
+- 기존 구현 및 제약 조건: Freeform code-mode tools already unwrap `input`, but a genuinely declared flat function must keep its name and Codex validates it against required `cmd`.
+- 검토한 주요 대안: Rename the call to code-mode `exec`; rewrite every function's `input`; add a schema-bound repair at authoritative function-call completion.
+- 선택한 방식: Repair only the exact bare declaration and exact one-member string payload when the current-turn schema requires string `cmd`.
+- 다른 대안 대신 이 방식을 선택한 이유: Tool names and arbitrary `input` fields are caller-owned; the original schema is the only authority that makes the representation change deterministic.
+- 장점, 단점 및 영향: Buffered, streamed-completion, and replay paths converge on valid `cmd` arguments; previews and ambiguous or namespaced shapes stay untouched.
diff --git a/structure/desktop-shell.md b/structure/desktop-shell.md
new file mode 100644
index 00000000000..bc93235d22d
--- /dev/null
+++ b/structure/desktop-shell.md
@@ -0,0 +1,204 @@
+# Desktop shell
+
+The `desktop/` tree owns the Tauri v2 OpenCodex desktop shell. Its Rust crate
+discovers the loopback proxy, lazily retries management authentication, starts
+the bundled `ocx` sidecar only when the configured endpoint is unreachable,
+and owns the tray, autostart, single-instance, and window lifecycle behavior.
+
+`desktop/ui/` is the startup surface. Once the runtime reports healthy the shell navigates the
+webview to the proxy's loopback dashboard (`/#/usage`) rather than bundling or serving `gui/dist`
+itself. The page renders what the shell tells it and probes nothing on its own; it asks
+`startup_phases` for the state list rather than restating it, takes the current state from
+`startup_snapshot` on load because the first states finish in milliseconds, and then follows the
+`startup-phase` event. It uses no `alert`, `confirm` or `prompt`: the embedded webview implements
+none of the matching WKUIDelegate panel methods on macOS, so a platform dialog is declined without
+drawing anything.
+`withGlobalTauri` is on so that page can invoke without a bundler. Only the local app origin
+carries a capability, so the loopback dashboard reaches no command: `capabilities/default.json`
+declares no `remote` entry, and Tauri checks the ACL for any invoke from a non-local origin.
+
+## Startup, quit and the tray
+
+The window is created and shown before anything is registered, resolved, probed or started, and
+`desktop/src-tauri/src/startup.rs` runs the whole sequence inside it as named states —
+registering, resolving, probing, attaching or starting, waiting, then ready or failed — under one
+30-second deadline. Every call beneath that deadline is bounded by the time left rather than by its
+own timeout, so the ceiling is the ceiling. The failure state carries a retry, the
+child's exit code and a copyable diagnostic naming the state, the endpoint, the configuration home
+and the runtime's last output; `desktop/src-tauri/src/sidecar.rs` consumes the spawn event stream
+into that record instead of discarding it, which is what makes an immediate sidecar exit
+distinguishable from a slow start. The page asks for the state list and the run's progress rather
+than reconstructing either, because the early states finish faster than a listener can attach.
+
+The shell resolves nothing itself. Resolving runs the bundled `ocx resolve --json` and reads one
+`ocx-resolve/1` document: the configuration home, the effective port, and a liveness verdict with
+three answers rather than two. `live` means attach as a guest; `absent-proven` means every
+recorded and configured endpoint was definitively dead, and **only that authorises starting a
+runtime**. Everything else is unknown — a non-zero exit, a timeout, output that will not parse, a
+schema this shell does not know, a missing binary — and unknown fails the state with a diagnostic
+and a retry. It is never read as absence, because that reading is what put a second proxy next to
+the one already running. This replaces a file that read `runtime-port.json`, fell back to 10100 and
+started there, so a user with a configured `config.port` was started on a port they had not
+chosen; the probe budgets that decision needs live in the CLI, where they were tuned.
+
+Registering runs first, before the runtime is touched. A login launch starts hidden, so a tray
+installed only after a successful start would leave a failed start with no window and no icon. The
+login item is registered in that state too, before the tray, so its Start at Login checkbox reads
+the state first run leaves behind. A launch carrying the `--autostart` argument that the login
+item passes back is the only one that starts hidden, and only where there is a tray to hide in: a
+manual launch shows its window before the sequence begins, a login launch after the tray verdict.
+Registering happens once per process, so a retry re-runs only the runtime half and cannot build a
+second tray icon with its own refresh loop.
+
+`desktop/src-tauri/src/exit.rs` owns what ends the process. Where there is a usable tray, closing
+the window and the platform's quit gesture both hide; only the tray's Quit asks to end, and an
+installed update asks for a coordinated restart. Where there is no usable tray, closing the window
+is the quit. macOS needs one thing beyond the event loop: Tauri's default menu carries a predefined
+Quit wired to Cocoa's `terminate:` and the pinned tao raises no cancellable event for it, so
+`desktop/src-tauri/src/menu.rs` rebuilds that menu with an ordinary item on the same accelerator.
+
+Every ending drains first, and so does the tray's Stop, which is not an ending: all of them take the
+same phase, so Stop pressed twice, Stop then Quit, and Stop during an update are one execution over
+one child rather than several racing. Ownership is re-established at the start of each drain rather
+than read off a flag — the pid the endpoint reports has to be the child this app started — because
+between the spawn and now the child can have exited and a service can have taken the port back, and
+an owner's stop sent to that listener is a stop sent to somebody else's runtime. A listener that
+cannot be identified is left alone.
+
+A runtime counts as gone only when the child reports its own exit or the endpoint refuses a
+connection; a timeout or an unauthorized reply is not proof. The stop itself is the bundled
+`ocx stop --json`, not a management call from inside this process: the CLI's stop owns the
+receipt-backed teardown, the drain, the Windows respawn verification and the client-configuration
+restore, and an in-process endpoint cannot own its own teardown because launchd and systemd can
+terminate the request handler during self-unload. The shell reads that run's `ocx-stop/1` summary
+rather than inferring it, and treats a stop as done only when the CLI reported exit 0 **and** that
+no proxy of this home is left running. A service that failed while the proxy happened to stop
+satisfies the second and not the first, and it is exactly the case that may respawn the runtime a
+moment later. Nothing kills the child.
+
+A drain that does not complete within `DRAIN_DEADLINE` is **not** recorded as a drain. It becomes
+`DrainFailed`, and an unidentifiable runtime becomes `OwnershipUnknown`. A user's quit still
+proceeds from either — refusing to close when the user asked is the worse answer, and a standing
+runtime is recoverable with `ocx stop`. A coordinated restart does not: coming back onto a runtime
+that was never stopped puts the user on the old version while they believe they upgraded. A runtime
+this app did not start is never stopped. A quit that arrives while the sequence is starting one is
+held: the coordinator reserves the spawn rather than holding its lock across process creation, and
+the quit is deferred until the child is owned and then drains it.
+
+An in-app update downloads and signature-checks the package, confirms who owns the running runtime,
+drains it and confirms the child is gone, and only then installs. The order is not cosmetic: the
+pinned updater's Windows installer hands off to the installer process and ends this one, so a
+restart asked for after `install` is never reached, and the package would be replaced under a
+runtime still serving out of those files. A drain that did not complete refuses the install and
+leaves the update pending.
+
+The window may navigate to the `tauri://` scheme, to the loopback endpoint the sequence resolved,
+and on Windows to `tauri.localhost`, which is where the pinned Tauri serves the app itself because
+wry needs an http origin there. That is the one host and no port — not localhost generally, and not
+a widening of what the loopback dashboard may reach.
+
+`desktop/src-tauri/src/proxy.rs` is the local management client and has its own network policy,
+separate from the updater's download client. It refuses redirects and system proxies, and it will
+not send the management token until it has confirmed, from the unauthenticated health body, that the
+instance answering is the one the shell bound to: the marker, the pid, and the port it addressed.
+The binding carries a generation, so a request authorised under an earlier binding is not authorised
+after the shell rebinds.
+
+`desktop/src-tauri/src/tray_availability.rs` asks the session bus whether
+`org.kde.StatusNotifierWatcher` reports a host registered; macOS and Windows answer yes without a
+probe. Neither construction success nor the watcher's mere existence is the question — the pinned
+Linux backend creates an AppIndicator and reports success with no host attached, and a watcher with
+no host accepts registrations and draws nothing. Until the probe answers, Linux assumes no tray, so
+a window closed in the first moments quits rather than vanishing, and the verdict is published only
+once an icon actually exists — a tray that fails to build is a session with no tray, not a claimed
+one. Where the answer is no, no tray icon is claimed, the window is shown on launch whatever the
+launch origin, and closing it quits through the same drain. The update controls live in the tray
+menu, so a session without one checks for updates in the background and has no place to install
+them from.
+
+Every tray menu setter dispatches to the main thread and waits for it, and the tray is built on the
+main thread while holding the menu mutex, so the handles are copied out from under that mutex before
+any setter is called. Holding it across a setter is a cycle, and the symptom would be an app that
+stops answering Quit.
+
+## Runtime ownership, from the app's side
+
+`desktop/src-tauri/src/identity.rs` holds this installation's own install id: an opaque value minted
+once into the app's config directory and never rewritten, exclusively so two launches racing each
+other answer to the same one. It exists because the recorded claim names the owning *installation*,
+so the app needs a value of its own to compare against; an id kept only in the shared record would
+be whoever wrote it last, and a reinstalled app could not tell its own prior consent from another
+installation's. The cost is that a reinstall which keeps the directory keeps its consent and one
+that loses it asks again.
+
+`desktop/src-tauri/src/ownership.rs` mirrors the claim, the three answers a read can give and the
+comparison, all of which are defined by
+[background-service runtime ownership](runtime.md#background-service-runtime-ownership) and not
+here. The shell does not read the record: resolving a claim means reading every state path and
+failing closed on an unreadable one, on a corrupt anchor and on paths that disagree, and a second
+weaker implementation of a question core already answers is the mistake this tree has made before.
+The bundled CLI answers it. Until that contract lands, `resolve` returns *unavailable*, which is
+not the same as "nobody owns it" — the question has not been put — so the shell attempts no takeover
+and records nothing, and the startup state and the diagnostic say which of the two it is.
+
+`desktop/src-tauri/src/first_run.rs` turns Start at Login on once per installation,
+before the tray is built so its checkbox reads the resulting state. A menu bar app
+that is not running has no menu bar item, so leaving autostart off by default left an
+installed app absent after a reboot. The marker in the app config directory is written
+before the login item is touched and is never removed, so a user who turns the setting
+off keeps it off; writing it afterwards would let a failed enable retry on every launch.
+The behaviour is not macOS-only — the autostart plugin implements the Linux autostart
+entry and the current-user Windows Run registration too.
+
+The WidgetKit extension in `app/` needs three things that Xcode's app-extension target
+would supply on its own, and SwiftPM has no such target: `@main` on
+`OpenCodexWidgetBundle`, the `-e _NSExtensionMain` linker entry, and
+`-application-extension` — the compiler spelling of `APPLICATION_EXTENSION_API_ONLY` — all
+in `app/Package.swift`. Any one missing yields a widget that never appears: without
+`@main` the linker drops the bundle and the extension registers with nothing to offer, and
+without the entry override ExtensionFoundation traps during bootstrap. Nothing observable
+distinguishes these from a working widget, because the bundle still builds, signs and
+registers. `com.apple.security.app-sandbox` is also mandatory — `pkd` refuses to register
+an unsandboxed plug-in at all — which is why the shell writes its snapshot into the
+extension's own container rather than a shared App Group, which ad-hoc signing cannot use.
+
+`desktop/scripts/prepare-sidecar.ts` maps Rust target triples to the standalone
+Bun targets and prepares the external binary plus dashboard resources used by
+Tauri. Generated files under desktop/src-tauri/binaries/ and
+desktop/src-tauri/resources/ remain ignored.
+
+The management API companion presence check in
+`src/server/management/companion-routes.ts` accepts both
+`OpenCodexMenuBar/` (legacy Swift companion) and `OpenCodexDesktop/` user agents.
+This is presence telemetry only; management
+authentication remains in the shared API boundary.
+The desktop webview uses a Mozilla-compatible `OpenCodexDesktop/` user-agent
+marker, which the GUI detects to identify the shell without using IPC.
+
+## Release packaging and updater
+
+The release workflow packages the desktop shell as `OpenCodex-<version>-macos.dmg`,
+`OpenCodex-<version>-windows-x64.msi`, `OpenCodex-<version>-linux-x86_64.AppImage`, and
+`OpenCodex-<version>-linux-amd64.deb`. Each artifact is collected with a `.sha256` file;
+signed updater artifacts also carry `.sig` files. A pre-publication verification job
+combines the standalone and desktop assets, derives the expected file set from the
+packaging matrices, verifies every checksum and every updater signature, and writes
+`latest.json` only when the updater key secret is configured, requiring all four
+platforms to have updater signatures. Publication waits for that verification, and the
+attachment job uploads the verified bundle only after the verification receipt names
+the same version and commit.
+On macOS, in-app updates download `OpenCodex-<version>-macos.app.tar.gz`; the DMG is for
+the first installation.
+
+The Tauri updater public key and endpoint are checked in to
+`desktop/src-tauri/tauri.conf.json`. Private updater and Apple signing credentials are
+provided only as release secrets. Windows certificate signing is not wired yet, so MSI
+users may see a SmartScreen warning.
+
+## Widget snapshot
+
+The macOS desktop shell writes the WidgetKit snapshot to
+`~/Library/Containers/com.opencodex.desktop.widget/Data/Library/Application Support/OpenCodex/snapshot.json`.
+The schema version is `1`; the Rust writer refreshes it every five minutes after an
+immediate first write. The WidgetKit appex reads this privacy-safe file and performs no
+network access.
diff --git a/structure/gui-and-management-api.md b/structure/gui-and-management-api.md
index 5ba41a3575d..726af4a7023 100644
--- a/structure/gui-and-management-api.md
+++ b/structure/gui-and-management-api.md
@@ -1,5 +1,9 @@
 # GUI And Management API
 
+The companion settings contract in `src/companion/` persists menu-bar and widget display
+preferences, while `src/server/management/companion-routes.ts` exposes those settings and the
+usage timeline assembled by `src/usage/timeline.ts` to local clients.
+
 Native result continuations and function-result injection follow [the mode-specific result and control contract](transports/streaming-health.md#experimental-native-function-result-injection); this surface does not infer upstream support or alter its defaults.
 Explicit Codex CLI installation observation is a local CLI surface, not a management API or GUI update permission. See the [read-only observation contract](runtime.md#explicit-codex-cli-installation-observation).
 
@@ -142,7 +146,7 @@ this document owns is which module holds which area and what invariant that area
 | Subagents | Read/write the featured `subagentModels` list capped at five ids. `GET/PUT /api/injection-model` manages the shared delegation model/effort selection, the independent OpenCodex guidance switch, and the default-off `syncCodexSubagentDefaults` opt-in for native Codex subagent defaults. When OpenCodex owns the active Codex routing, native `[agents]` defaults apply to newly created Codex tasks after sync/restart; external user-managed provider configs remain untouched. The defaults do not cause delegation and preserve existing user-owned defaults rather than overwriting them. PUT is partial-update: absent keys are unchanged, `null` clears, and non-object bodies are rejected with 400 before field validation. `syncCodexSubagentDefaults: true` requires a nonblank `model` and a supported Codex reasoning effort when effort is set; clearing `model` (null/empty) always clears effort and disables native-default sync even when the stored effort was invalid. |
 | V2 / Multi-agent mode | `GET/PUT /api/v2` — reports/sets the codex `multi_agent_v2` feature flag, the 3-state `multiAgentMode` override (`v1`/`default`/`v2`), the `keepNativeChatGptOnV1` hybrid pin, and the logical maximum thread count. Selecting `v2` normally enables the native flag; with the hybrid pin it disables that global override so native rows can resolve to v1 while routed rows resolve to v2. Selecting `v1` disables the flag; `default` leaves it unchanged. PUT rejects an explicit enabled flag that conflicts with the selected mode or hybrid pin. Every transition preserves the logical thread limit, is rollback-safe, and resyncs the catalog. GET and successful PUT also return stored `multiAgentModeHintText` plus response-only `multiAgentModeHintRecommendation: { text, revision }`; the recommendation is not a writable or persisted config field. Both also return response-only `multiAgentSurfaceAdvisory: { required, mode, recommended, version, docsUrl }`, true while the resolved mode is not v1 and the stored acknowledgement version is behind; PUT accepts `multiAgentSurfaceAdvisoryAcknowledged`, where only `true` stores the current version and `false` is an explicit no-op, and it composes with a `multiAgentMode` write in the same body so the dialog's recommended answer is one request. |
 | Logs & Debug | One sidebar entry (`/#logs`) with two tabs. Logs tab: request/runtime logs for local diagnosis. `LogsFilterBar` owns controls over the shared `LogFilterState`; `filterLogs` composes filters over the loaded ring. The logs envelope adds `generatedAt` (proxy epoch milliseconds); the page advances that sample with monotonic elapsed time and retains a browser-clock fallback for older proxies. Reset returns focus to the stable All surface radio. Provider/model options include attempts, model choices match normalized complete identities, and relative-time filtering refreshes every 30 seconds while the Logs tab is active, independently of network auto-refresh. Debug tab (`/#logs/debug`; legacy `/#debug` deep links redirect there): provider + usage toggles, refresh/follow log viewer. `GET/PUT /api/debug`; `GET /api/debug/logs` and `GET /api/debug/usage-logs` (monotonic `after` cursor, legacy `since` accepted). CLI: `ocx debug provider|usage …` (both streams via running proxy API). |
-| Usage | `GET /api/usage` read-only aggregates of readable rows from `~/.opencodex/usage.jsonl`; the ledger is streamed in fixed 1 MiB chunks, so the former read-byte and parsed-row caps cannot omit its prefix. Oversized skipped rows produce positive `usageIncomplete` metadata. The response includes measured / reported / unreported / unsupported / estimated counts, a daily zero-filled grid, and model and provider breakdowns. Never exposes prompts. |
+| Usage | `GET /api/usage` read-only aggregates of readable rows from `~/.opencodex/usage.jsonl`; the ledger is streamed in fixed 1 MiB chunks, so the former read-byte and parsed-row caps cannot omit its prefix. Oversized skipped rows produce positive `usageIncomplete` metadata. The response includes measured / reported / unreported / unsupported / estimated counts, a daily zero-filled grid, and model and provider breakdowns. `GET /api/usage/timeline` uses the same ledger and canonical attribution helpers for bounded bucketed model series. Never exposes prompts. |
 | Request metrics | `GET /api/metrics` exposes process-local Prometheus text format v0.0.4 only when `metricsExport.enabled` was true at startup. The ordinary management gate applies; data-plane credentials do not grant access, and disabled mode is 404. `src/server/request-metrics.ts` owns fixed counters/histograms and receives a narrow final-request fact from `src/server/request-log.ts`; `src/server/index/serve-options.ts` creates one owner and injects the recorder and read-only snapshot into the request and management paths. |
 | System | `POST /api/system/restart` restarts the proxy in place. Local CLI/tray callers first attest the exact runtime PID and port, then send a process-scoped HMAC capability bound to that method, path, PID, and port; the capability authorizes no other management route and is invalid after replacement. The caller observes one absolute deadline and accepts success only after a different runtime PID is healthy on the same port. `GET /api/system/health` is the authenticated scalar-only identity used by shared-plane Dashboard status and restart reconnect polling; its `spendLedger` block reports only ownership held/unheld, initialized/configured/degraded booleans and bounded persistence/corruption counters. Reading it never constructs, replays or prunes the ledger. Paths, scopes, accounts and request ids are absent, and the block never moves to unauthenticated `/healthz`. `GET /api/system/memory` — service-process runtime/memory identity (pid, Bun version/revision, optional `bunRuntimeSource` provenance, platform, RSS/heap/external/ArrayBuffers scalars, observed memory = max(RSS, external, ArrayBuffers), `bun:jsc` heap context, streamMode + eager-relay gate decision, watchdog snapshot sliced to the last 60 samples) plus privacy-safe `appOwnedBytes` retained-store totals/counters under static store ids. Its response-state block also reports spill-write `initial`/`healthy`/`degraded` status, a consecutive-failure streak, fixed error class, and failure/success timestamps. A successful publication clears the streak in the same process; raw error text and paths never enter this surface. Scalar-only payload; dashboard/admin callers use the standard management gate, while `ocx doctor` may use only the exact process-scoped local-read capability. It must never move to unauthenticated `/healthz`. |
 | Stop | `POST /api/stop` — restore native Codex, stop any installed service, and exit the proxy. |
@@ -152,7 +156,7 @@ this document owns is which module holds which area and what invariant that area
 | Provider quotas and tests | `src/server/management/provider-routes.ts` — `GET /api/provider-quotas`, `POST /api/providers/test`, `GET/PUT /api/provider-context-caps`, `GET /api/provider-presets`. A quota read may be served from cache or force-refreshed; absent quota data is reported as unknown rather than as a measured zero. |
 | Models and visibility | `src/server/management/model-routes.ts` — `GET /api/models`, `PUT /api/disabled-models`, `PUT /api/model-visibility`, `PUT /api/selected-models`, `GET/POST /api/custom-models`. Visibility writes trigger catalog sync through the owning server path. |
 | Effort and fallback | `src/server/management/agent-settings-routes.ts` — `GET/PUT /api/effort-caps`, `/api/subagent-models`, `/api/subagent-model-fallback`. Caps clamp; they do not reject. |
-| Grok and Claude integrations | `src/server/management/agent-settings-routes.ts` — `GET /api/grok`, `PUT /api/grok/selection`, `POST /api/grok/apply`, `GET/PUT /api/claude-desktop`, `POST /api/claude-desktop/apply`, `GET /api/claude-desktop/status`, `GET/PUT /api/claude-code`. Apply writes an external app's profile, so its status probe must read the same resolved path it writes (see [`responses.md`](transports/responses.md)). |
+| Grok and Claude integrations | `src/server/management/agent-settings-routes.ts` — `GET /api/grok`, `PUT /api/grok/selection`, `POST /api/grok/apply`, `GET/PUT /api/claude-desktop`, `POST /api/claude-desktop/apply` (`mode`: `first-party` default, `gateway`, or legacy shapes), `GET /api/claude-desktop/status` (`mode`, `firstParty`), `GET/PUT /api/claude-code`. Gateway apply writes an external app's profile, so its status probe must read the same resolved path it writes (see [`responses.md`](transports/responses.md)); first-party apply writes only the Claude Code proxy env, see [`clients/claude-desktop.md`](clients/claude-desktop.md#desktop-modes-first-party-and-gateway). `gui/src/pages/ClaudeDesktop.tsx` renders the mode selector and sends the chosen `mode` with apply. |
 | File-integration plans | `src/server/management/integration-routes.ts` and `aside-profile-routes.ts` — `POST /api/client-integrations/preview`, `POST /api/client-integrations/restore/preview`, and `POST /api/client-integrations/aside/profiles/{profileId}/preview`. Management-authenticated, declared non-mutating, and they write nothing: no snapshot, no lock, no maintenance, no recovery. They answer `409 integration_preview_unavailable` rather than gathering a model roster, because discovery refreshes credentials and writes the provider cache. Responses carry only declared managed schema paths, closed change kinds and an opaque fingerprint; no value, filesystem location or selected member identity appears. Mutation routes accept `operation` and `planFingerprint` together or not at all, reject a half-bound request and an operation that disagrees with the change, and answer `409 integration_preview_stale` with a freshly computed plan. Binding is an optimistic token, never authorization. [The integration contract](clients/integrations.md) owns the ordering. |
 | Grok reset coupons | `src/server/management/grok-coupon-routes.ts` — `GET /api/grok/reset-coupons`, `POST /api/grok/reset-coupons/consume`. The dashboard owner is `gui/src/hooks/useGrokResetCoupons.ts` with `gui/src/components/provider-workspace/GrokResetCoupons.tsx`, wired into the xAI OAuth rows of `ProviderAuthPanel`. Redemption truth is the settled ledger `code`, not the HTTP status: a replayed failure returns 200 with `replayed: true`. See [`providers/xai-grok.md`](providers/xai-grok.md). |
 | Combos | `src/server/management/combo-routes.ts` — `GET/PUT/DELETE /api/combos` own provider combination and failover definitions. |
@@ -524,6 +528,21 @@ monitoring or protection against another process changing the path again after t
 An opt-in shadow-call rewrite persists the bounded, redacted original helper model as
 `shadowCallRewrittenFrom`, so helper traffic remains identifiable after restart without storing
 request content or inferring a helper subtype from timing.
+A failed request persists closed `failureStage` and `failureCause` members on the attempt that ended
+it and on the logical row, derived once at `addFinalRequestLog` from facts that are themselves
+closed; `errorCode` and `upstreamError` carry upstream text and are deliberately not read there. The
+resend verdict they imply is never stored — `/api/logs` computes `resendPermission` at read time, so
+a row written by an older build cannot assert a permission the current tables refuse. An attempt also
+carries `deliverySummary`: adapter events, relayed frames, semantic bytes, side effects and terminal
+frames, counted where each event is delivered rather than where it is read, so the gap between the
+first two is the loss signal. Provider debug formats one ring line per finalized attempt from those
+counts and writes no second record. `GET /api/usage?failures=1` groups failed rows by a versioned
+fingerprint over closed vocabularies only, rebuilt through the same cooperative scanner and
+inheriting its bounds, so deleting a ledger row removes it from the grouping.
+`usageLedgerMaxBytes` is unset by default; when set, an append that crosses it publishes the newest
+whole rows byte for byte through the shared atomic writer, refuses the rename unless the source is
+the exact revision that was copied, and then discards the Logs ring, the retained aggregates and the
+request-history index so no surface serves rows the ledger no longer has.
 `src/usage/summary.ts` turns that file into the `/api/usage` shape — totals, daily zero-filled
 grid, model and provider breakdowns, and `measured / reported / unreported / unsupported / estimated` counts.
 The management route scans the ledger from its beginning in fixed 1 MiB chunks on a
@@ -620,9 +639,16 @@ log scan, or persistence. Restart creates a fresh owner, resets every counter/hi
 `opencodex_metrics_process_start_time_seconds`.
 
 The label vocabularies are closed: protocol is `responses`, `chat`, `messages`, or `unknown`; result
-is `completed`, `failed`, `incomplete`, or `aborted`; recovery is one of eight coarse classes. A
+is `completed`, `failed`, `incomplete`, or `aborted`; recovery is one of the coarse classes listed in
+`REQUEST_METRICS_RECOVERY_CLASSES`, and cause is one of the shared failure causes in
+`REQUEST_METRICS_FAILURE_CAUSES`, which aliases the dictionary rather than copying it. Each is the
+roster the exporter itself iterates. The count is
+deliberately not restated here: it was written as eight, a bounded label value was added, and the
+documentation then contradicted the output it describes. A
 logical request increments once, physical sends sum the finalized attempt counts, and each distinct
-recovery kind already retained on an attempt contributes once to its coarse class. HTTP 200 never
+recovery kind already retained on an attempt contributes once to its coarse class.
+`opencodex_request_failures_total` counts the cause the recorder derived and never re-derives one,
+and it labels a counter only: no histogram carries a cause. HTTP 200 never
 overrides a failed terminal event. Duration observes every valid finalized duration; TTFT observes
 only finite nonnegative first-output values, while `opencodex_ttft_missing_total` is the complementary
 denominator. No request, credential, account, provider, model, conversation, raw error, prompt, tool,
@@ -635,6 +661,16 @@ once it exceeds 200) with the upstream content-type, body kind (`sse / json / ot
 body sample, and the extracted usage. Off by default; the hot path is guarded so production stays
 untouched.
 
+For diagnosing cache-read instability without capturing content, set `OPENCODEX_CACHE_DEBUG=1`
+before start. `src/usage/cache-diagnostic.ts` then writes one record per finalized request to
+`~/.opencodex/cache-debug.jsonl` (same `0o600` file, same 200-to-100 rolling bound) holding only
+presence booleans, counts, closed enums, the raw upstream cache counter before defaulting, and
+process-local HMAC equality tags for the prompt-cache key, allowlisted session headers, the account
+log label, and ordered instruction/tool/message blocks (capped at 128 per section, first divergent
+section/index only). The signing key is created at process start and never persisted, so tags
+compare values within one proxy process and never become a durable correlation key; no prompt
+text, tool name, raw identifier, or header value is recorded. Off by default.
+
 ## Z.ai quota destination ownership
 
 `src/providers/quota/vendor-probes-key.ts` uses one exact normalized-base mapping for both Z.ai quota
@@ -749,3 +785,8 @@ is chosen; for a combo selector the warning lists the combo's target providers f
 and states that failover targets receive the conversation too. `GET /api/settings` returns
 the override or null; `PUT /api/settings` accepts a complete validated object or null to clear it.
 Save failure restores live settings and deletion provenance; the dashboard retains the draft for retry.
+
+`src/server/gui-static.ts` serves the dashboard from `gui/dist`, with `OPENCODEX_GUI_DIST` taking
+priority and standalone binaries resolving the copied directory beside `ocx`. Runtime package
+metadata comes from the bundled `src/lib/package-version.ts` manifest import so compiled binaries
+do not read a source-tree `package.json`.
diff --git a/structure/manifest.json b/structure/manifest.json
index cbd3c7da0fc..4f5dc0b3da8 100644
--- a/structure/manifest.json
+++ b/structure/manifest.json
@@ -49,7 +49,9 @@
       "title": "Overview",
       "scope": "Product boundary, local state ownership, and the non-negotiable invariants index.",
       "documents": [
+        "app/",
         "gui/",
+        "src/companion/",
         "scripts/",
         "src/config.ts",
         "src/lib/"
@@ -310,14 +312,14 @@
       ]
     },
     {
-    "path": "adapters/compatibility-lab.md",
-    "tier": 4,
-    "title": "Compatibility Lab",
-    "scope": "Optional Lab evidence, automation, and its core-runtime isolation boundary.",
-    "documents": [
-      "src/lab/",
-      "src/server/index.ts"
-    ]
+      "path": "adapters/compatibility-lab.md",
+      "tier": 4,
+      "title": "Compatibility Lab",
+      "scope": "Optional Lab evidence, automation, and its core-runtime isolation boundary.",
+      "documents": [
+        "src/lab/",
+        "src/server/index.ts"
+      ]
     },
     {
       "path": "gui-and-management-api.md",
@@ -326,10 +328,12 @@
       "scope": "Dashboard serving, authentication boundaries, /api/* ownership, and usage accounting.",
       "documents": [
         "gui/",
+        "src/companion/",
         "src/codex/",
         "src/lib/",
         "src/server/",
         "src/usage/",
+        "src/usage/timeline.ts",
         "src/vision/"
       ]
     },
@@ -356,6 +360,16 @@
         "src/server/"
       ]
     },
+    {
+      "path": "desktop-shell.md",
+      "tier": 6,
+      "title": "Desktop shell",
+      "scope": "Tauri desktop shell, proxy attachment and sidecar lifecycle, tray controls, bootstrap navigation, and desktop companion presence.",
+      "documents": [
+        "desktop/",
+        "src/server/management/companion-routes.ts"
+      ]
+    },
     {
       "path": "ops/service-and-sidecars.md",
       "tier": 6,
diff --git a/structure/ops/docs-and-release.md b/structure/ops/docs-and-release.md
index 89fe8db595a..1d1000b6678 100644
--- a/structure/ops/docs-and-release.md
+++ b/structure/ops/docs-and-release.md
@@ -46,9 +46,9 @@ Manual navigation is defined in `docs-site/astro.config.mjs`. When adding a publ
 sidebar and either add localized copies or intentionally accept Starlight fallback behavior.
 
 Provider preset totals are recounted from the current registry when a preset lands. The
-documented split is 95 total: 79 key-based, 12 OAuth, three local, and one default
+documented split is 96 total: 80 key-based, 12 OAuth, three local, and one default
 ChatGPT-forward preset. The English provider guide, all seven translated copies, and all eight
-quickstarts carry the same counts, and the guides carry the same fixed-host discovery limits.
+quickstarts carry the same counts.
 
 That recount is no longer a manual obligation. Seventeen places restate these numbers and sixteen
 of them drifted once already — the English guide reached 95 while every translation and every
@@ -58,6 +58,19 @@ key-based split from `PROVIDER_REGISTRY` and asserts them against each page, so
 fails every locale at once instead of drifting. Each page is located by a locale-specific phrase
 rather than by its number, so rewording a sentence fails the check and asks to be re-anchored.
 
+The fixed-host discovery limits are the same shape one layer down, and this document used to
+assert their parity in prose: it claimed the guides carried the same limits, across sixteen-plus
+files, verified by nobody. That claim was false when it was written — the Korean guide had no
+Featherless section at all, so it documented twelve of the thirteen limited presets.
+`tests/ci-workflows/docs-provider-discovery-limits.test.ts` replaces the claim with the check:
+each section's byte and row ceilings are read from that preset's `modelDiscovery` and asserted
+against every shipped guide, and a grouped section must first agree in the registry before one
+sentence may describe both presets. Sections are located by brand name and the presence of a
+`KiB`/`MiB` token rather than by a translated phrase, because a restated anchor is the same
+hand-copied value the guard exists to remove; a section that is missing or duplicated fails by
+name. The byte ceiling is compared as an exact token set, so a stale number left beside the
+current one fails instead of passing on a substring.
+
 Native retirement keeps active model/quota instructions aligned across locales with the
 [catalog contract](../catalog.md#shared-catalog). Historical records and other providers
 sharing a model-name fragment remain distinct from current Codex-native support.
@@ -256,6 +269,10 @@ typecheck and GUI build. `scripts/release.ts` accepts either an explicit version
 `bun run privacy:scan` before the version bump, commit/push, Cross-platform CI wait, and GitHub
 Release workflow dispatch. Docs publishing is separate from npm release publishing.
 
+The `package-standalone` job in `.github/workflows/release.yml` also builds Bun compiled
+`ocx` archives for Linux, macOS, and Windows, bundles `gui/dist`, smoke-tests `/healthz`, and
+publishes SHA-256 sidecars for the attach job.
+
 Opening a release starts with the `dev` pre-move. Dispatch
 `.github/workflows/dev-version-bump.yml` with the intended version, merge the pull request it opens,
 then promote and release. A no-op is valid when `dev` already outranks the target. `release.yml`
diff --git a/structure/ops/service-and-sidecars.md b/structure/ops/service-and-sidecars.md
index d293a286dfb..527702612aa 100644
--- a/structure/ops/service-and-sidecars.md
+++ b/structure/ops/service-and-sidecars.md
@@ -198,3 +198,8 @@ Dashboard Fast-row persistence and client refresh follow the [Fast selector rows
 The service loads the optional `compactionRouting` block from persisted configuration.
 [Responses ingress](../transports/responses.md#compaction-routing-overrides) applies it to individual compaction
 requests whose trigger the block names.
+
+Standalone binaries use `src/lib/standalone.ts` to detect the Bun `$bunfs` runtime and
+`src/service/state.ts` to compose durable service commands as `<execPath> start`, without a
+source-tree CLI path. The copied `gui/dist` directory is located by `src/server/gui-static.ts`;
+`OPENCODEX_GUI_DIST` remains an explicit override.
diff --git a/structure/overview.md b/structure/overview.md
index c0627e2dd7f..5c226f2dfc0 100644
--- a/structure/overview.md
+++ b/structure/overview.md
@@ -33,6 +33,14 @@ native Anthropic passthrough branch that forwards without translation. The Live/
 different in kind — it resolves an OpenAI/ChatGPT relay and forwards to it directly, without the
 adapter bridge.
 
+`app/` contains the native macOS WidgetKit extension bundled into the Tauri desktop app.
+`MenuBarCore` is its snapshot model/formatting layer; the desktop shell writes the
+privacy-safe snapshot that the widget reads without network access. It is a client of
+the management API, not part of the proxy — it adds no endpoint and changes no routing.
+Treat it the way you treat `gui/`: it may consume what `src/` already exposes,
+and a change that requires a new endpoint is a change to the proxy first.
+Its persisted display contract is owned by `src/companion/`.
+
 The default install keeps native OpenAI/ChatGPT passthrough working through one option-aware
 `openai` provider. Pool is the default and selects across main plus added accounts; Direct uses only
 the current caller/main login. `openai-apikey` explicitly selects API-key transport, and the two
@@ -130,6 +138,60 @@ still cover the rule, which is a judgement only review makes.
   there, reported as an unidentified holder otherwise. A configured `port: 0` still asks the OS for a
   port, and an explicit `--port` still waits for its pin instead of hopping.
   Enforced by `tests/cli/cli-dispatch.test.ts`.
+- **INV-RESEND-01** — One vocabulary states how far a failed request got, why it failed, and whether
+  it may be sent again. The rosters are declared in the import-free `src/usage/telemetry-contract.ts`
+  so the dashboard can name their members, and `src/lib/request-failure-model.ts` re-exports them and
+  owns the decision. Once the caller has observed output or an externally visible effect, no cause
+  automatically permits a resend, and a cause whose upstream execution state is unknown is not made
+  replayable by having budget left. A refusal names which of the three refusals it is. The decision is
+  derived from per-stage and per-cause facts rather than written out as a stage-by-cause matrix, so a
+  new member cannot leave a stale cell.
+  Enforced by `tests/lib/failure-stage-model.test.ts`.
+- **INV-ATTRIBUTION-01** — `src/lib/request-failure-attribution.ts` derives the persisted failure
+  stage and cause from closed recorder facts only, never from `errorCode` or `upstreamError`, which
+  are assembled partly from upstream text. An unknown upstream execution state is attributed to a
+  cause that refuses an automatic resend rather than to one that permits it, and the resend verdict
+  the pair implies is computed at read time and never persisted.
+  Enforced by `tests/lib/failure-attribution.test.ts`.
+- **INV-RESEND-02** — One logical request holds one operator-granted replacement for an ambiguous
+  failure, however many stages ask for it. `src/lib/request-resend-gate.ts` is the only place
+  that override is applied, it claims the grant at the moment it authorises rather than earlier,
+  and a stage the caller observed something at refuses without spending it. The grant never
+  widens a send budget: an authorised replacement still has to fit the allowance the leg already
+  had. The ceiling is the request's, not the asking leg's: a leg reads its number from the
+  provider row it is currently running against, rotation, refresh, transport resolution and each
+  combo target reassign that row, so the request keeps the smallest ceiling any leg presented and
+  a more permissive row arriving later buys nothing.
+  Enforced by `tests/lib/ambiguous-resend-gate.test.ts`.
+- **INV-CHAT-01** — One developer-role policy governs the translated Chat wire and every document
+  that describes it. `foldDeveloperRoleToSystem` unset and `true` send `system`, `false` sends
+  `developer`, and the message never leaves the slot it arrived in. The documented sentence is
+  built from the role the adapter serializes rather than written out again, and the translated
+  pages are compared against their English source, so a changed default fails a check instead of
+  leaving two documents to disagree; see [`chat-compat.md`](providers/chat-compat.md).
+  Enforced by `tests/ci-workflows/docs-developer-role-policy.test.ts`.
+- **INV-DESKTOP-01** — Where the desktop app has a usable tray, only the tray's Quit ends it:
+  closing the window and the platform's quit gesture hide, which on macOS needs the default menu's
+  predefined Quit replaced because it raises no cancellable event. Every ending drains first — the
+  tray's Quit, an update's coordinated restart, and a window close on a session with no tray all
+  hold the exit, stop the app-owned runtime through the management stop, and treat only an observed
+  child exit or a refused connection as proof it stopped. The stop is the bundled `ocx stop --json`,
+  accepted only on exit 0 with the runtime reported down. Ownership is re-established from the pid
+  the endpoint reports rather than carried in a flag, a drain that does not complete is recorded as
+  failed rather than drained — which a quit tolerates and a coordinated restart refuses — and an
+  update installs only after the runtime it is replacing is confirmed stopped. No shell file kills
+  the child, a runtime this app did not start is never stopped, and a quit that lands while one is
+  being started or stopped is deferred rather than lost;
+  see [`desktop-shell.md`](desktop-shell.md).
+  Enforced by `tests/clients/desktop-exit-ownership.test.ts`.
+- **INV-DESKTOP-02** — Tray availability is an answer from the session, not the tray backend's
+  construction result and not the watcher's mere existence: the shell asks whether
+  `org.kde.StatusNotifierWatcher` reports a host registered, and reads an unanswerable probe the
+  same way as an unregistered one. Linux assumes no tray until the probe answers, and the verdict is
+  published only once an icon exists, so a tray that fails to build is a session without one. Where
+  there is none, no icon is claimed, the window is shown on launch whatever the launch origin, and
+  closing it quits through the same drain; see [`desktop-shell.md`](desktop-shell.md).
+  Enforced by `tests/clients/desktop-tray-availability.test.ts`.
 
 CI enumerates that domain layout through `scripts/ci/run-bun-test-batches.sh`. Its default general
 scope and 12-file/120-second process shape leave the dedicated Linux storage-policy and api-usage
diff --git a/structure/providers-and-adapters.md b/structure/providers-and-adapters.md
index 0121fb76e40..7dda9c214c6 100644
--- a/structure/providers-and-adapters.md
+++ b/structure/providers-and-adapters.md
@@ -15,9 +15,10 @@ the [bounded ingestion contract](transports/inventory.md#bounded-response-ingest
 | `src/combos/request.ts` | Clones each selected combo target request and applies the existing target capability ladder: adaptive unknown targets and explicit empty ladders receive no unsupported reasoning/thinking controls, while known ladders retain per-target resolution. |
 | `src/adapters/openai-responses.ts` | Native OpenAI/ChatGPT Responses passthrough. |
 | `src/responses/muse-tool-name-alias.ts` | Host-gated Meta Muse 64-char tool-name alias/restore used by the Responses passthrough. |
-| `src/adapters/openai-chat.ts`, `src/adapters/openai-chat/` | OpenAI-compatible Chat Completions bridge, split into leaves (`wire.ts`, `messages.ts`, `response-events.ts`, `passthrough.ts`, `tool-call-validation.ts`, `tool-schema.ts`, `errors.ts`). Its client delivery shapes in `src/chat/outbound.ts` and `src/server/chat-native-sse.ts` relay the upstream `service_tier` echo on non-stream, folded-stream, and synthesized-SSE bodies, never inventing the key when the upstream omits it. |
-| `src/adapters/anthropic.ts` | Anthropic Messages bridge. A `refusal` or `content_filter` stop reason yields an explicit `incomplete` event with `retryable: false` rather than `done` with that stopReason (#4312); `max_tokens` remains `done`. |
-| `src/adapters/google.ts` | Gemini bridge. The final wire compiler owns [endpoint-scoped tool-schema loss policy](providers/google.md#google-tool-schema-loss-reporting): compatible mode changes no request bytes, strict initial loss creates no physical send, and strict non-direct repair creates no changed repair send. |
+| `src/adapters/openai-chat.ts`, `src/adapters/openai-chat/` | OpenAI-compatible Chat Completions bridge, split into leaves (`wire.ts`, `messages.ts`, `response-events.ts`, `passthrough.ts`, `parallel-tool-calls.ts`, `reasoning-wire.ts`, `tool-call-validation.ts`, `tool-schema.ts`, `errors.ts`). `parallel-tool-calls.ts` owns the `parallel_tool_calls` wire value for both the translated and native builders, so the three provider states — configured opt-out, configured opt-in, and the unset default that forwards only a caller's explicit `false` — cannot drift between them. `reasoning-wire.ts` applies explicit gateway-object and tool-bearing effort-omission declarations to both builders; absent declarations leave native raw forwarding unchanged. Its client delivery shapes in `src/chat/outbound.ts` and `src/server/chat-native-sse.ts` relay the upstream `service_tier` echo on non-stream, folded-stream, and synthesized-SSE bodies, never inventing the key when the upstream omits it. |
+| `src/adapters/anthropic.ts` | Anthropic Messages bridge. A `refusal` or `content_filter` stop reason yields an explicit `incomplete` event with `retryable: false` rather than `done` with that stopReason (#4312); `max_tokens` remains `done`. It is the wire that defines `tools[*].strict` and `tools[*].allowed_callers`, so a rebuilt declaration carries both: an explicit `strict: true` and any `allowed_callers` the caller declared. An absent `strict` stays absent, because the Messages inbound records it as `false` and a `false` on the wire would read as an opt-out nobody asked for. |
+| `src/adapters/google.ts` | Gemini bridge. The final wire compiler owns [endpoint-scoped tool-schema loss policy](providers/google.md#google-tool-schema-loss-reporting): compatible mode changes no request bytes, strict initial loss creates no physical send, and strict non-direct repair creates no changed repair send. A caller-declared strict tool selects `functionCallingConfig.mode: "VALIDATED"` in place of the absent-choice default; `NONE`, `ANY` and a forced-name choice are stronger constraints the caller asked for and are never overwritten. |
+| `src/adapters/declaration-carrier.ts`, `src/adapters/input-media-guard.ts` | Default-deny allowlists for constraints the normalized request carries but a wire may not be able to express: `tools[*].allowed_callers`, which fences a tool off from callers, and inline document bytes. Both are refused with a 400 at the single guard every registered adapter passes through, rather than left to each adapter, because an adapter that never learned about the carrier rebuilds without it and answers normally. `allowed_callers` reaches the `anthropic` wire; document bytes reach `anthropic`, `openai-chat` and `google`; the `openai-responses` wire is exempt from the whole guard because it forwards the original body. Adding an `AdapterWire` member makes the omission visible in these lists instead of at a customer's upstream. The unrestricted `["direct"]` caller default is not a restriction. |
 | `src/adapters/azure.ts` | Azure OpenAI bridge. |
 | `src/adapters/cursor.ts`, `src/adapters/cursor/` | Cursor protobuf transport: discovery, request builder, event decoding, MCP, thread continuity, native-exec policy. |
 | `src/adapters/devin.ts`, `src/adapters/devin/cloud-direct/` | Devin runTurn transport over Cognition Connect-RPC. `GetChatMessage` uses the Responses provider executor and shared physical-send budget; catalog and JWT support RPCs remain outside inference-send accounting. |
diff --git a/structure/providers/chat-compat.md b/structure/providers/chat-compat.md
index 6fe286bd76d..1c7465bde6e 100644
--- a/structure/providers/chat-compat.md
+++ b/structure/providers/chat-compat.md
@@ -9,18 +9,38 @@ Native Codex Spark-specific request exceptions are absent. General Lite and name
 remain shared [Responses compatibility](../transports/responses.md#responses-httpsse), including
 other providers whose models happen to share a name fragment.
 
-## OpenCode Go chronological instructions
-
-For the registry-recognized OpenCode Go Chat destination and exact model
-`deepseek-v4.1-flash`, `src/adapters/openai-chat.ts` keeps text-only timeline
-developer messages in place as system messages. Appending a reminder therefore
-does not hoist new text into the leading system prompt and rewrite the existing
-serialized message prefix. Pending tool results still precede deferred reminders.
-The base system prompt, vision conversion and native OpenAI developer roles retain
-their existing behavior; other Chat destinations and models retain leading-system
-folding. This is independent of the Claude trailing-notice stabilization option
-and does not guarantee upstream cache hits. Regression coverage is in
-`tests/adapters/openai/openai-chat-system-order.test.ts`.
+## Chronological in-conversation instructions
+
+`src/adapters/openai-chat/messages.ts` keeps a text-only timeline developer message in the
+slot it arrived in, on every Chat destination and model. Appending a reminder therefore does
+not hoist new text into the leading system prompt and rewrite the existing serialized message
+prefix, and a mid-conversation instruction no longer moves ahead of the turns it was written
+to follow. Pending tool results still precede deferred reminders. This was previously scoped
+to the registry-recognized OpenCode Go destination and the exact model
+`deepseek-v4.1-flash`, which made prompt-prefix stability read as a property of that one
+destination. The base system prompt, vision conversion and native OpenAI developer roles
+retain their existing behavior. This is independent of the Claude trailing-notice
+stabilization option and does not guarantee upstream cache hits. Regression coverage is in
+`tests/adapters/openai/openai-chat-system-order.test.ts` and
+`tests/adapters/openai/openai-chat-developer-position.test.ts`.
+
+The role that slot carries is a separate decision, and the setting that makes it is tri-state.
+`foldDeveloperRoleToSystem` unset sends `system`, `true` sends `system`, and `false` sends
+`developer`. Unset means nothing has been recorded about the destination; `true` records an
+upstream that rejects the role; `false` records one that accepts it. The message keeps the slot it
+arrived in in every case — only the role changes, never the position. The unrecorded state is the
+folded one because a destination that rejects the role answers
+`400 role 'developer' is not allowed` and the turn never starts, a failure that lands outside this
+repository where no test can reach it. The role was previously decided by testing the base URL host
+against `api.openai.com`, so every OpenAI-compatible gateway was assumed not to support a standard
+role until proven otherwise, and the instruction silently lost `developer` precedence.
+
+That mapping is not prose to be restated. `tests/ci-workflows/docs-developer-role-policy.test.ts`
+builds the sentence above from the role `src/adapters/openai-chat/messages.ts` serializes for each
+of the three states, and requires this document and
+`docs-site/src/content/docs/reference/configuration/providers.md` to carry it word for word, so a
+changed default fails a check rather than only a document review (INV-CHAT-01). The translated
+configuration pages and Claude Code guides are held against their English source in the same file.
 
 Shared parsing and streaming follow the [request-copy](../transports/byte-accounting.md#request-copy-accounting) and [stream-buffer accounting](../transports/byte-accounting.md#stream-buffer-accounting) contracts.
 
@@ -57,7 +77,9 @@ boundary, so parsed messages and stored raw history retain the same task/guidanc
 
 Native OpenAI passthrough consults the existing configured capability ladder before forwarding
 `reasoning_effort`; an explicitly empty ladder removes that unsupported control while an unknown
-ladder remains unclassified. It also sanitizes routed reasoning history so `reasoning` input items do not send
+ladder remains unclassified. Both Chat builders then apply the same explicit provider declarations:
+gateway-object projection and tool-bearing model effort omission. An unset declaration preserves the
+native caller field exactly. Native passthrough also sanitizes routed reasoning history so `reasoning` input items do not send
 non-empty `content` arrays to upstream models that reject them. Chat Completions bridging repairs
 orphan `toolResult` messages by inserting a synthetic assistant `tool_call` before tool messages.
 It also repairs the opposite direction (260718): an assistant `tool_calls` round left dangling —
@@ -418,8 +440,9 @@ The final registered adapter also checks the original input under the
 [untranslated-media contract](../adapters/registry.md#untranslated-input-media). Audio/file
 attachments cannot succeed merely because the normalized representation retained a text
 marker: translated adapters refuse them, while native Responses retains the original body.
-Chat conversion rejects recognized audio/file parts before projection; the native Chat wire
-is unchanged. No audio/file transport or automatic URL fetch is added, and no client filename,
+Chat conversion rejects recognized audio/file parts before projection, except a user-content
+file part whose inline base64 bytes now have a lossless carrier; the native Chat wire is
+unchanged. No audio transport and no automatic URL fetch is added, and no client filename,
 payload, URL or metadata is included in the new error messages.
 
 The shared coding-agent projection (CodeBuddy, Qoder) carries tool-result images as
diff --git a/structure/providers/cursor.md b/structure/providers/cursor.md
index 3f047315203..7252130843a 100644
--- a/structure/providers/cursor.md
+++ b/structure/providers/cursor.md
@@ -8,7 +8,7 @@ namespace handling retain their provider contract; the bounded native scope live
 [the shared catalog](../catalog.md#shared-catalog).
 
 Cursor's direct adapter does not enter the OpenAI Chat serializer's
-[OpenCode Go instruction ordering](chat-compat.md#opencode-go-chronological-instructions).
+[chronological instruction ordering](chat-compat.md#chronological-in-conversation-instructions).
 
 Shared parsing and streaming follow the [request-copy](../transports/byte-accounting.md#request-copy-accounting) and [stream-buffer accounting](../transports/byte-accounting.md#stream-buffer-accounting) contracts.
 
diff --git a/structure/providers/openai-tiers.md b/structure/providers/openai-tiers.md
index c9479b1b051..0fde5683acd 100644
--- a/structure/providers/openai-tiers.md
+++ b/structure/providers/openai-tiers.md
@@ -387,8 +387,11 @@ has headroom, auth resolution validates the caller bearer's own gated-model rost
 request-owned credential before stored-Pool selection. The credential never enters Pool persistence,
 affinity, entitlement cache, or health state, and this decision never reads the physical main credential.
 If the caller lacks the requested model, a stored-account model detour may serve the request without
-clearing the healthy shared main pin. A paused or quota-drained main skips this exception and follows the
-ordinary Pool promotion path.
+clearing the healthy shared main pin. With quota-strategy cache affinity, the same detour preserves an
+ordinary added-account binding and shared selection beyond the proactive-switch threshold until genuine
+exhaustion; pause, cooldown, reauthentication, quota refusal, and failover evidence still retire shared
+state normally. A paused or quota-drained main skips the request-owned credential exception and follows
+the ordinary Pool promotion path.
 
 > Decision record: [ADR-0086](../decisions/ADR-0086-public-provider-contract.md)
 
diff --git a/structure/runtime.md b/structure/runtime.md
index 130ab5d4bfe..384b6b394e6 100644
--- a/structure/runtime.md
+++ b/structure/runtime.md
@@ -30,9 +30,10 @@ OAuth refresh coordination follows the [refresh-lock identity contract](catalog.
 The configuration-only [plaintext V2 contract](subagents.md#plaintext-v2-agent-messages)
 is scoped to canonical ChatGPT Responses forwarding; other source-area behavior described here is unchanged. Cursor's localized native-shell names follow the [routing-commentary guard contract](providers/cursor.md#cursor-native-exec).
 
-Chat request serialization owns the destination-scoped
-[OpenCode Go instruction ordering](providers/chat-compat.md#opencode-go-chronological-instructions);
-it requires no runtime lifecycle change or new configuration option.
+Chat request serialization owns
+[chronological instruction ordering](providers/chat-compat.md#chronological-in-conversation-instructions)
+and the developer wire role; it requires no runtime lifecycle change, and its one
+configuration option is a per-provider role opt-out.
 
 Shared parsing and streaming follow the [request-copy](transports/byte-accounting.md#request-copy-accounting) and [stream-buffer accounting](transports/byte-accounting.md#stream-buffer-accounting) contracts. Response-attached WebSocket telemetry follows the [stage record identity contract](transports/responses.md#passthrough-sse-stream-shapes-314).
 
@@ -49,6 +50,12 @@ this wire projection does not change the usage ledger.
 
 Catalog-derived reasoning-level diagnostics are escaped only at the human-output boundary, which `src/cli/runtime-api.ts` owns alongside the human/JSON print split. Every CLI path that prints a hub-supplied catalog value renders it there: the first-time refusal in `src/cli/connect.ts` and the connected `ocx sync` refusal in `src/cli/dispatch.ts`. C0/C1 controls, DEL, and Unicode line/paragraph separators print as visible hexadecimal escapes; structured status retains the exact reason, and a rendered failure keeps the domain error as its `cause`. The ready/unverified/incompatible classification and exit policy are unchanged.
 
+## CLI resolve and stop contracts for embedding shells
+
+`ocx resolve` (`src/cli/resolve.ts`) is the machine surface a desktop shell asks instead of resolving the config home, the port, and liveness itself: the home comes from `src/config/paths.ts`, the effective port is the live listener's when the identity-checked `findLiveProxy` answers and the configured `config.port ?? 10100` otherwise, and the liveness verdict is that same module's output (pid, runtime-versus-config provenance, version, role). Config reads go through `readConfigDiagnostics`, not `loadConfig`: a missing file is defaults, but an invalid file exits 1 instead of being repaired to defaults, because a defaulted port is a guess the caller must refuse. Liveness is three-valued: when `findLiveProxy` returns null, resolve re-asks the endpoints with the updater's tri-state probe (`endpointsToProve` + `everyEndpointProvenDown` + `probeProxyLiveness`), and only a unanimous definitive "dead" becomes `absent-proven`; unknown exits 1 and never authorises a start. Discovery borrows `START_OWNERSHIP_LIVENESS`, the start path's ownership budget — the verdict feeds the shell's launch decision, so the cost of a false "nobody listening" is the duplicate proxy (#5004). The verb is in `skipsCodexShimAutoRestore`, so a read-only lookup never triggers a shim repair. Arguments are pre-parsed in `src/cli/root.ts` and exit 64 before any preflight side effect, the same ordering `ocx ready` obeys.
+
+`ocx stop --json` is a reporting layer over the unchanged stop path. `src/cli/index.ts` threads a `StopRunRecord` through the existing receipt, drain, respawn-verification and restore flow, and `src/cli/stop-report.ts` maps the recorded facts plus the signals that already pick the exit code into one versioned document (`schema: "ocx-stop/1"`). With `--json` the human lines print on stderr and stdout carries only that document; exit codes 0/1/79/80 cross the process boundary unchanged.
+
 ## Native main reauth JSON output
 
 `src/cli/account-main.ts` emits one JSON object to stdout when `ocx account main reauth --device --no-wait --json` succeeds. The human-readable `follow up:` line is emitted only without `--json`; `flowId` remains available for status polling. `tests/cli/cli-native-profile.test.ts` parses the complete captured stdout and preserves coverage of the human follow-up.
@@ -57,6 +64,14 @@ Catalog-derived reasoning-level diagnostics are escaped only at the human-output
 
 `ocx system codex-restart` requests a full Codex desktop-app restart and app-server restarts through the management endpoint. `src/cli/capabilities.ts` names that scope in its summary and `--yes` description; `src/cli/system-command.ts` explains the desktop interruption when confirmation is missing and sends no restart request. Human output says the restart was requested, while `--json` preserves the complete server result, including skipped or refused desktop outcomes.
 
+After a CLI catalog/cache write, advisory restart guidance compares each running Codex app-server's
+start time with the written catalog mtime. It reports only processes proven stale; a fresh or
+unreadable observation does not claim that another restart is required. Explicit
+`--restart-codex` and `--restart-app-server-only` retain their operator-consent semantics and act on
+verified matching processes regardless of the advisory freshness result.
+
+> Decision record: [ADR-0097](decisions/ADR-0097-post-write-app-server-freshness.md)
+
 ## Hub management dashboard address
 
 When hub management ingress is enabled, `src/cli/dispatch.ts` opens the dashboard on the literal IPv4 loopback address and configured ingress port, matching the listener in `src/server/index.ts`. Other dashboard address selection is unchanged.
@@ -214,6 +229,27 @@ The hub-management socket is enabled only by `runtimeRole: "hub"` plus
 `hub.managementIngress.enabled`, always binds `127.0.0.1`, and default-denies everything except
 GUI, session bootstrap/exchange, and `/api/*`.
 
+### Claude intercept pair
+
+At the end of the startup transaction, `startServer` also starts the optional Claude intercept pair
+through `src/server/index/claude-intercept-lifecycle.ts` (fire-and-forget start, `ownsListener` for
+the ingress decision, `stop` joined into the listener shutdown) from `src/claude/intercept/runtime.ts`: a loopback HTTP CONNECT proxy (`src/claude/intercept/connect-proxy.ts`)
+and a loopback TLS listener (`src/claude/intercept/listener.ts`) that presents a leaf for
+`api.anthropic.com` signed by a per-install authority (`src/claude/intercept/local-ca.ts`, persisted
+under `<OPENCODEX_HOME>/claude-intercept/` with a 0600 key; never installed into an OS trust store).
+Claude Code reaches the pair through `HTTPS_PROXY` plus `NODE_EXTRA_CA_CERTS` in its settings env
+(`src/claude/intercept/settings.ts`), so no `ANTHROPIC_BASE_URL` rewrite is involved and the client
+still believes it talks to Anthropic. The proxy splices `CONNECT api.anthropic.com:443` onto the TLS
+listener, relays every other CONNECT target blind, and refuses plain proxied HTTP and loopback targets.
+The TLS listener rewrites `POST /v1/messages` and `POST /v1/messages/count_tokens` onto a loopback
+origin and dispatches them to the same route table under the `claude-intercept` ingress, which takes
+the loopback request policy; every other path on the intercepted host is relayed verbatim to the
+configured Anthropic upstream. The pair is on by default on a hub (`claudeCode.intercept.enabled`),
+its proxy port defaults to the public port + 100 (`claudeCode.intercept.port`), and a bind failure
+degrades to a startup warning rather than a startup failure; stop joins both sockets. A server asked
+for an ephemeral public port (`startServer(0)`, the shape every in-process test fixture uses) has no
+stable port to derive from, so the pair stays off unless `claudeCode.intercept.port` is explicit.
+
 Auxiliary listener bind failures carry the listener key and effective address through `AuxiliaryListenerBindError` in `src/server/ports.ts`. `src/cli/index.ts` reports them without retrying the public port. Startup still rolls back every earlier socket synchronously.
 
 A failed optional bind initiates rollback of every earlier socket; normal stop joins all bound
@@ -399,6 +435,8 @@ privately to final dispatch; preliminary route selection does not inject Go-only
 Private pool credential metadata follows the [quota-history publication identity contract](providers/openai-tiers.md#quota-history-publication-identity); credential-only and account DTO projections omit it.
 
 Cline CLI joins the existing export/client integration registries. Explicit CLI sync and POST /api/sync refresh its owned pair; unattended catalog refresh excludes it. See [Cline paired files](clients/integrations.md#cline-paired-files).
+Its paired-file writer uses the config atomic-write primitive that replaces the named entry without
+following a final symlink, so an exchange during a mutation cannot redirect the write.
 
 `claudeCode.stabilizePromptCache` is a default-off operator setting for
 [translated instruction stabilization](data-planes/inbound-compat.md#opt-in-claude-instruction-stabilization).
@@ -491,3 +529,63 @@ Unicode pattern normalization uses [copy-on-write traversal](transports/byte-acc
 
 Codex compaction uses a request-local model override for the configured triggers; the
 [Responses compaction contract](transports/responses.md#compaction-routing-overrides) owns its trigger and replay boundaries.
+
+## Background-service runtime ownership
+
+`src/service/state.ts` records who owns the running proxy in the shared service install
+state, beside the install provenance. The claim carries an `owner` (`cli` or `desktop`), an
+opaque `installId` naming the owning installation rather than the user or the machine, and a
+`consentGeneration`. An absent claim means the CLI install that registered the service owns
+the runtime, which is what every record written before the field existed says.
+
+Every write goes through `swapServiceInstallState`. With a custom home, the default-home
+record is the authority every writer can derive and the active-home record is a compatibility
+mirror; with one path, that path is authoritative. `src/service/state-lock.ts` holds
+token/PID/process-instance locks for every path in canonical order. A live holder is never
+evicted because of age, and release deletes only its token-named owner. The authoritative
+file is fsynced and atomically renamed through `src/config/atomic-write.ts`; that rename is
+the commit point. Mirrors receive the exact committed bytes afterwards. A mirror failure is
+diagnostic rather than rollback, and the next writer repairs it. An absent authority imports
+one valid legacy mirror once; same-or-newer mirror disagreement and unreadable authority are
+`unknown`, never ownership votes. Uninstall removes mirrors before the authority, so a
+partial deletion cannot turn a revoked mirror claim back into migration input.
+
+`resolveServiceOwnership` answers `none`, `owned` or `unknown` from that authoritative
+generation. `consentGenerationCeiling` survives a release, so granting, releasing and
+granting again cannot reuse a number an app-local record may still hold.
+`recordServiceOwner` requires the exact `owner`/`installId`/`consentGeneration`/`revision`
+subject shown on the consent surface. The comparison runs again inside the same lock and on
+every internal retry; a mismatch or unknown subject writes nothing and requires fresh user
+approval. `ownershipGrantedTo` remains the narrower relaunch test for an already-owned app.
+
+Permanent takeover also requires `assessServiceTakeoverCompatibility` to approve both the
+preserved service launcher and the selected PATH launcher. Every observed manager must be
+OpenCodex 2.61.0 or later, and a preserved registration must carry ownership protocol 1.
+Missing, old, malformed or unknown manager evidence blocks takeover and leaves registration
+and autostart untouched. The supported verdict carries an opaque token over the approved
+subject and both manager identities; `recordServiceOwner` re-observes and compares it inside
+the lock, so a mutable shim or downgrade cannot inherit earlier consent. An upgrade is a
+separate user-authorized action; declining or failing it leaves the app a guest.
+
+The verbs that activate the npm registration refuse on a foreign or unknown owner:
+`src/service/repair.ts` stops before it asserts, writes, stops or starts anything, and
+`ocx service start` reports the same refusal. `stop` and `uninstall` are not gated, because
+they deactivate. `src/update/runtime-ownership.mjs` vetoes both the pre-update stop and the
+post-update service refresh for all three update lanes — `src/update/index.ts`,
+`bin/ocx.mjs` and the dashboard worker in `src/update/job.ts`. The shared update decision has
+three independent authorities: package replacement, runtime stop and service restoration.
+Unknown and desktop ownership deny all three because a claim alone does not prove that the live
+process is detached from the npm package; CLI ownership permits the ordinary stop-first
+flow. Both package updaters use `src/service/install-state-contract.mjs`, backed by the single
+`state-record.mjs` parser and authority selector. One mutation lease covers the fresh stop
+authorization, the stop child, the current runtime-record re-read and package replacement.
+The updater never treats the pre-stop address as proof that this installation is idle;
+an unreadable current record is unknown, and a valid address is probed even when its recorded
+PID is gone. Lease delegation is passed only to stop and recovery children, never package
+manager children. A replacement refusal passes through owner-aware recovery: only the same CLI
+owner revives the stopped runtime; foreign ownership stays transferred and unknown ownership
+remains a reported recovery requirement. Dashboard restart delegates the lease token to its repair child. Direct
+start holds the same lease through bind plus PID and runtime-address publication. If listener
+rollback cannot prove the socket closed, the process retains its lease until exit.
+The registration is never deleted; `ocx service install` releases the marker only after the
+registration succeeds.
diff --git a/structure/transports/inventory.md b/structure/transports/inventory.md
index e81ec55dc57..bfd34825f7d 100644
--- a/structure/transports/inventory.md
+++ b/structure/transports/inventory.md
@@ -12,8 +12,9 @@ The existing Responses transport is divided by responsibility in the
 The configuration-only [plaintext V2 contract](../subagents.md#plaintext-v2-agent-messages)
 is scoped to canonical ChatGPT Responses forwarding; other source-area behavior described here is unchanged. Cursor's localized native-shell names follow the [routing-commentary guard contract](../providers/cursor.md#cursor-native-exec).
 
-The Chat adapter's [OpenCode Go instruction ordering](../providers/chat-compat.md#opencode-go-chronological-instructions)
-changes translated message placement only; endpoint selection and transport stay with their existing owners.
+The Chat adapter's [chronological instruction ordering](../providers/chat-compat.md#chronological-in-conversation-instructions)
+changes translated message placement and the developer wire role only; endpoint selection and transport
+stay with their existing owners.
 
 Shared parsing and streaming follow the [request-copy](byte-accounting.md#request-copy-accounting) and [stream-buffer accounting](byte-accounting.md#stream-buffer-accounting) contracts. Response-attached WebSocket telemetry follows the [stage record identity contract](responses.md#passthrough-sse-stream-shapes-314).
 
@@ -35,7 +36,7 @@ surface is listed here so a maintainer can find the owner without grepping:
 | Adapter execution support | `src/adapters/run-turn-queue.ts`, `src/adapters/tool-catalog-nudge.ts`, `src/adapters/identity.ts`, `src/adapters/image.ts`, `src/adapters/upstream-http-error.ts` | Shared machinery: turn ordering, tool-catalog nudging, client fingerprinting, image conversion, upstream error normalization. |
 | Cursor (beyond the sections above) | `src/adapters/cursor/live-transport.ts`, `src/adapters/cursor/http1-bidi.ts`, `src/adapters/cursor/live-models.ts`, `src/adapters/cursor/transport-retry.ts`, `src/adapters/cursor/mcp-manager.ts`, `src/adapters/cursor/thread-continuity.ts`, `src/adapters/cursor/checkpoint-store.ts` | Thread continuity is the point: a retry must not start a new Cursor thread, and a validated checkpoint must not rebuild the full root history. HTTP/2 remains the default; an explicit `http1.1`/`h1` pin maps the bidi run onto Cursor's `RunSSE` receive stream plus sequenced `BidiAppend` sends, and applies to live discovery too. |
 | Claude Messages | `src/server/claude-messages.ts` | Routed translation, a native Anthropic passthrough branch, and `count_tokens`. |
-| Chat Completions inbound | `src/server/chat-completions.ts`, `src/server/chat-native.ts`, `src/chat/`, `src/adapters/openai-chat.ts` | Inbound translation onto the same routing pipeline. The content mapper preserves image URLs and supported detail, including screenshot-bearing tool results; target adapters own image placement on their wire. Image-free tool results stay strings. The native handler owns pin/cap normalization; the adapter wire builder removes effort only for explicit empty declarations or no-reasoning models, preserving unknown raw declarations. On the response side, the upstream `service_tier` echo relays on every delivery shape (`src/chat/outbound.ts` projections, `src/server/chat-native-sse.ts` chunks); an upstream without the field gets no injected key. |
+| Chat Completions inbound | `src/server/chat-completions.ts`, `src/server/chat-native.ts`, `src/chat/`, `src/adapters/openai-chat.ts` | Inbound translation onto the same routing pipeline. The content mapper preserves image URLs and supported detail, including screenshot-bearing tool results; target adapters own image placement on their wire. Image-free tool results stay strings. The native handler owns pin/cap normalization; both adapter builders share explicit gateway-object and tool-bearing effort-omission policy, while the native builder preserves unknown or undeclared raw behavior and removes effort for explicit empty declarations or no-reasoning models. On the response side, the upstream `service_tier` echo relays on every delivery shape (`src/chat/outbound.ts` projections, `src/server/chat-native-sse.ts` chunks); an upstream without the field gets no injected key. |
 | Hosted search relay | `src/server/search.ts` | Verbatim ChatGPT relay, or an explicitly configured web-search sidecar backend when no forward provider exists; distinct from the web-search sidecar loop below. |
 | Image/video generation loop | `src/images/loop.ts`, `src/images/plan.ts`, `src/images/fulfill.ts`, `src/images/xai-client.ts`, `src/images/xai-video-client.ts`, `src/images/artifacts.ts` | A provider-returned image URL is downloaded into a local artifact once, then served locally; warnings stay URL-free because provider CDN URLs may embed credentials. |
 | GitHub Copilot | `src/providers/xai-transport.ts` (`resolveProviderTransport`), `src/providers/github-copilot-transport.ts` | `resolveProviderTransport` selects the Copilot transport when the routed provider name is `github-copilot`; the Copilot module then resolves its headers and base URL, and the registry seeds the provider row and model fallback. |
@@ -118,6 +119,32 @@ rejected body returns no credentials, an oversized, malformed, or aborted key re
 login before credential persistence or dashboard convergence, leaving only the fixed size-limit or
 invalid-JSON message described above.
 
+## Per-provider egress coverage
+
+`src/lib/provider-egress.ts` resolves a provider route for one destination. The route is carried only
+by transports that can preserve that request-local decision:
+
+| Request path | Per-provider route | Current contract |
+| --- | --- | --- |
+| Main routed inference through `providerFetch` in `src/server/responses/fetch-helpers.ts` | Honoured | Applied at the physical send in `sendWithConnectionPolicy`, so a request rebuilt against a different destination or a reselected provider transport resolves its route against the destination actually used. The built-in executor passes direct, HTTP(S)-proxy, and SOCKS5(H)-proxy choices through `configuredOutboundFetch` in `src/lib/proxy-env.ts`; an inherited route leaves the global decision unchanged. Native Chat in `src/server/chat-native.ts` and the Responses transport in `src/server/responses/request-transport.ts` bind their own sends. |
+| Every caller of `providerOutboundGet` or `providerOutboundPost` in `src/lib/provider-outbound.ts` | Honoured | This includes provider discovery and model-catalog gathering in `src/codex/catalog/provider-models.ts`, management provider tests in `src/server/management/provider-routes.ts`, and the Ollama show probe in `src/providers/ollama-show.ts`. |
+| API-key quota probes in `src/providers/quota/vendor-probes-key.ts` | Honoured | Each probe receives its provider config and sends through `configuredOutboundFetch` with the resolved route, so a quota reading and the inference it describes leave by the same exit. |
+| OAuth token exchange and refresh under `src/oauth/` | Not honoured | These reach fixed vendor endpoints from modules that hold no provider config, so no provider route is in scope at the call site. A provider pinned to its own proxy or to direct still refreshes credentials by the process-wide route. |
+| OAuth-backed quota probes in `src/providers/quota/vendor-probes-oauth.ts` | Not honoured | `fetchXaiQuota`, `fetchAnthropicQuota`, `fetchCursorQuota` and their neighbours receive a provider name and a token rather than a provider config. |
+| API-key validation probes in `src/oauth/key-providers.ts` | Not honoured | `validateApiKey` receives a `KeyLoginProvider` derived preset, which carries no egress fields, and its caller builds the real provider record afterwards. |
+| Responses WebSocket upstream in `src/server/responses/ws-upstream.ts` | Not directly | The WebSocket dial selects its proxy from the process environment. An explicit provider route therefore serves that provider's turns over HTTP/SSE instead and emits one warning per provider per process. |
+| Caller-supplied `provider.fetch` executor | Not honoured | The caller owns that executor's transport. An explicit provider route is refused instead of being ignored. |
+| Cursor's default HTTP/2 transport in `src/adapters/cursor/live-transport.ts` | Not honoured | The native HTTP/2 dial does not consume the provider route. |
+| Coding-agent subprocess providers in `src/adapters/coding-agent/turn.ts` | Not honoured | Their scoped child environment omits proxy variables, so a provider route is not projected into the subprocess. |
+| Compatibility Lab pinned sender in `src/lib/lab-live-pinned-sender.ts` | Not honoured | The sender uses the approved pinned address and does not resolve a provider route. |
+
+The following authenticated data-plane endpoints do not resolve a provider route because they do
+not route a model through the router: `/v1/images/generations`, `/v1/images/edits`,
+`/v1/audio/transcriptions` and `/v1/audio/transcriptions/stream`, `/v1/live`,
+`/v1/realtime/calls`, the standalone realtime WebSocket routes, and the non-account-qualified
+branch of `/v1/alpha/search`. Their dispatch remains with the endpoint owners in
+`src/server/index/serve-options.ts`.
+
 ## Provider diagnostic outbound safety
 
 Google tool-schema loss diagnostics follow the same outbound boundary. The compiler retains only
diff --git a/structure/transports/responses.md b/structure/transports/responses.md
index 09bf0d1ccb7..a82e8f8cb08 100644
--- a/structure/transports/responses.md
+++ b/structure/transports/responses.md
@@ -125,6 +125,16 @@ Function-call wrappers around freeform bodies are restored by
 is recoverable because the wrapper is otherwise unusable; two alternate fields are ambiguous and
 therefore remain untouched. Foreign freeform grammars never receive that compatibility rewrite.
 
+#### Schema-bound flat shell repair
+
+Completed Responses function calls have one separate schema-bound flat-shell repair. When the
+exact bare `exec_command` declaration requires a string `cmd`, a provider result containing only
+the string member `{ "input": "..." }` is rewritten to `{ "cmd": "..." }`; the call name is not
+changed. Namespaced tools, additional or conflicting members, non-string values, malformed JSON,
+partial streaming previews, and schemas that do not prove this exact contract remain byte-exact.
+
+> Decision record: [ADR-0098](../decisions/ADR-0098-schema-bound-exec-command-input-repair.md)
+
 Progressive preview for those wrappers is decoded by
 `src/responses/progressive-freeform-input.ts` in both the adapter-event bridge and routed
 function-call restoration, over the classification in `src/responses/freeform-wrapper-scan.ts`.
@@ -667,6 +677,57 @@ and continuation-state suppression as well as the refusal, and it stands down on
 `src/server/responses/run-turn-execution.ts` and `src/server/responses/adapter-delivery.ts` set the
 flag from `inboundWire` on the streaming, buffered, and JSON paths alike, so the three cannot drift.
 
+### Selection outlives the declaration check
+
+Declaration and selection are different questions, and the guard above answers only the first.
+`tool_choice: "none"`, a forced selector and an `allowed_tools` allow-list each narrow a catalog
+without removing a declaration, so a name can be declared and forbidden at the same time — and a
+guard that compares names against the catalog passes it.
+
+The gap is reachable because a repair can put such a call back.
+`createGrokResponsesSparseTerminalBlockRewrite` in `src/server/grok-responses-snapshot-repair.ts`
+rebuilds a terminal `output` the upstream never sent from the items it collected during the turn.
+`src/server/responses-request-tool-scope.ts` reads the boundary the request states, and the repair
+applies it to what it publishes: a client call outside the selection is left out of the
+reconstruction. The scope comes from the final outbound body, after every removal, rename and
+translation, so a catalog that ends up empty there authorizes no client call whatever the selector
+still says. An absent catalog states no boundary, exactly as it states none for the declaration
+guard.
+
+Selection matching follows request-local identity correspondence instead of regenerating a set of
+name spellings. The outbound selector keeps its exact kind and wire name; namespace lowering
+contributes only its collision-checked `{namespace, name, kind}` aliases, and the Muse length rewrite
+composes its final wire alias over those identities. After client-facing restoration, two namespaces
+that share one basename remain distinct, as do a function and a custom tool that share one name. A
+custom call may match a function selector only when the same request records that exact
+custom-to-function conversion; malformed narrowing selectors and contradictory alias maps fail
+closed. Payload restoration still precedes sparse-terminal reconstruction, so the scope compares the
+restored call through that correspondence while preserving its item and call identifiers.
+
+The refusal is narrow and it is visible. Only the offending item is dropped, so the assistant text
+that arrived in the same turn still reaches the client rather than being discarded with it. Because
+the turn no longer ended the way the upstream said it did, the reconstructed terminal is published
+as `response.incomplete` carrying `incomplete_details.reason: forbidden_tool_call`, not as a clean
+`response.completed` with a quietly shorter output. The repair edits nothing but the terminal it
+synthesizes; the raw stream remains the declaration guard's to police.
+
+The selection is kept honest on the way out as well. `src/adapters/xai-web-search.ts` omits an
+`auto`/`none` selector once normalization has left nothing for it to select, because xAI answers
+that request with a 400. A forced function selector is preserved: a selector this proxy cannot
+honor is a client input error, and `src/server/responses/passthrough-dispatch.ts` already answers
+it with one.
+
+Those two omissions are not the same edit, because the scope above is read from the body this
+normalization produces. `auto` selects from the catalog, so removing it from a request with an
+empty one states nothing new. `none` is a prohibition, and on a request whose catalog this
+normalizer emptied it is the only place the turn's client-call boundary is written down. Dropping
+the word alone would let the reconstruction hand back a call the caller ruled out, and nothing
+behind it would catch that: the repair runs on the grok client surface, while the declaration
+guard stands down whenever the provider's `authMode` is `forward` — which is what the xAI OAuth
+lane is. So the prohibition is restated as the explicit empty catalog, which carries the same
+deny-all, which the scope and the declaration guard both already read that way, and which this
+destination receives unchanged whenever a caller sends one itself.
+
 ### Passthrough SSE stream shapes (#314)
 
 Native passthrough SSE has TWO shapes, selected per request in
@@ -849,6 +910,39 @@ compact, and native Chat — are deliberately not opted in. Adapters with their
 `fetchResponse` (kiro, cursor, google) keep their own retry policies; kiro imports the shared
 abort/sleep helpers from this module.
 
+## Ambiguous-resend gate
+
+A model POST that fails with the caller having observed nothing is one question asked at two
+points: before any response head, and after a head whose SSE body carried only control events.
+`src/lib/request-resend-gate.ts` is the single answer. It derives stage, cause, permission and
+send class from `src/lib/request-failure-model.ts` and adds exactly one thing the table names
+but does not implement — the narrowly scoped operator override for `refused-ambiguous`.
+
+The override is bounded on three axes at once. The provider opts in with
+`providers.<name>.retryOnReset`; the request must be one
+`src/server/responses/reset-replay.ts` can judge self-contained, meaning nothing stored, no
+server-side continuation state, complete input and only client-executed tools; and the whole
+logical request holds one replacement grant, whichever stage asks for it. The grant lives on the
+request's execution budget, so a combo child that derives its own scope draws on the same
+counter rather than holding a second. A replacement never widens a send budget: it still has to
+fit inside the allowance the leg already had, and it is charged to the same counter every other
+send goes through.
+
+The number of replacements is the request's as well. A leg reads it from `route.provider`, which
+credential rotation, OAuth refresh, transport resolution and each combo target reassign inside one
+request, so the grant is held to the smallest ceiling any leg has presented rather than to
+whatever the asking leg presents. Otherwise a request that had already spent the one replacement a
+strict row granted bought a second duplicate inference as soon as a more permissive row asked, and
+how many times one turn could be re-sent depended on the order the rows happened to ask in. A
+derived scope draws on the same grant even when its parent is a hand-built view rather than a
+factory budget: the claim is public on the parent, so unlike a pending external booking there is
+nothing private that forces a second counter.
+
+A committed or futile failure refuses without touching the grant, so a turn that already emitted
+output cannot drain the replacement a later ambiguous reset would have been entitled to. The
+cause is derived from the `AttemptRecoveryKind` the send will be recorded as, which is what
+keeps the reason in the log and the reason the gate weighed from being two different values.
+
 ## Console upload rejection recovery
 
 `src/providers/opencode-zen-rate-limit.ts` recognizes the complete Console upload-rejection envelope only at the effective HTTPS opencode.ai Zen/Go generation endpoint. A provider row name cannot authorize another destination. The two recovery loops in `src/server/responses/core.ts` wait 800 ms and replay the captured serialized request once; cancellation, nonreplayable responses, other errors and a second upload rejection keep their failure semantics. The recovery kind is persisted as `console-go-upload-retry` and has a localized Logs label.
@@ -899,6 +993,13 @@ An HTTP 200 does not by itself commit a streaming combo child. The combo parent
 downstream Responses SSE through `src/server/responses/combo-stream-preflight.ts`, which owns one
 reader and buffers only until one of these boundaries:
 
+Native post-header reset recovery shares that boundary, because it is asking the same question
+about the same bytes. With `replayReadErrors`, the preflight reports the stage it observed —
+`headers-only` before any parsed event, `protocol-prelude` after `response.created`,
+`semantic-output` once anything else arrives, including a payload it could not parse — and the
+resend gate decides. A `response.created` whose snapshot already carries output items is not a
+prelude.
+
 - a non-control Responses event begins client-visible output or a tool/action item, after which the
   target is committed and cross-target replay is forbidden;
 - a `response.failed` terminal arrives first, in which case the terminal is converted back through
@@ -1012,7 +1113,8 @@ is composed from the following owners in `src/server/responses/`; none is a gene
 | `request-transport.ts` | Live credential selection, dispatch bindings, adapter replacement and same-target request identity. |
 | `request-sidecar-auth.ts` | Sidecar credential resolution and vision preprocessing. |
 | `response-effects.ts` | Completion notification, replay publication and live request-tool aliases. |
-| `request-send-budget.ts` | Request-wide send accounting, remaining allowance and the pending recovery permit. |
+| `request-send-budget.ts` | Request-wide send accounting, remaining allowance, the pending recovery permit and the shared ambiguous-resend grant. |
+| `reset-replay.ts` | The operator opt-in for replacing an ambiguous native Responses send, and the per-request grant both stages claim from. |
 | `request-spend.ts` | This request's entries in the durable spend ledger: one per physical send, settled from the terminal usage. |
 | `passthrough-execution.ts` | Native host-lease transfer and the enclosing dispatch/delivery `finally`. |
 | `passthrough-dispatch.ts` | Native request preparation, upstream sends and pre-commit recovery. |
@@ -1250,7 +1352,11 @@ turn up to four more times, and a 429 is where the client stops.
 `upstream_reset_replay_refused`. No response headers is not evidence that the model POST
 was never processed, so the decision not to replay is ours, made before any response
 existed — the same shape as `request_send_budget_exhausted`, and it takes the same status
-for the same reason. Only an explicitly replay-safe operation opts into reset retries.
+for the same reason. An explicitly replay-safe operation retries instead, and a provider that
+opted into `retryOnReset` may spend the request's single replacement grant; once that grant is
+gone, or the leg has no send left, or a later attempt fails any other way, the leg settles as
+this same refusal. Nothing on that path hands the client a status that invites the whole turn
+to be sent again. See [ambiguous-resend gate](#ambiguous-resend-gate).
 
 **An upstream reset observed mid-stream or after a terminal keeps its existing behaviour.**
 The passthrough read path still settles a genuine upstream reset as a synthetic 502, and the
@@ -1303,6 +1409,33 @@ the default fires on; and `src/server/chat-native.ts` restores the code its own
 429 maps to `rate_limit_error`, which already carries a code, so the branch that copies an
 upstream code could never reach it — and suppresses the same synthetic wait.
 
+**The verdict is a property of the response, and every surface states it the same way.** The
+translated Chat wrapper in `src/server/chat-completions.ts` was the fourth writer and the one
+that had none of this: it preserved the cyber-policy code and `model_not_found`, took the
+upstream code only when `classifyError` had produced none, and then attached the retryable-429
+default. A refusal therefore left the Chat bridge as an ordinary rate limit carrying an
+instruction to send the turn again. It now reads the same two things the native surface reads —
+`isReplayRefusalResponse` on the response it still holds, and `isReplayRefusalCode` on a body
+that came through an intermediate formatter — and never the status, which a refusal and a real
+rate limit share. The failed-envelope path in the same function restates it too, so a refusal
+arriving as `status: "failed"` is not reported as the 502 a Codex client retries four times.
+Because a re-wrap is where the in-process marker is lost, `retainReplayRefusal` and
+`carryReplayRefusal` in `src/lib/upstream-retry.ts` are what each formatter calls:
+`src/bridge/errors.ts`, `src/server/responses/passthrough-error.ts`, both Chat wrappers, the
+routed Claude Messages wrapper, and the deferred-logging re-wrap in `src/server/relay.ts`.
+
+**Dropping `Retry-After` is necessary and not sufficient.** The status stays 429 because Codex
+stops there and a 5xx invites four more sends, but the Stainless-generated clients — `openai`
+and `anthropic`, Python and Node — decide from a status table that includes 429 and compute
+their own backoff when no wait is named, so a bare 429 is still resent by most callers of this
+proxy. Every surface therefore also emits `x-should-retry: false`, the one signal those clients
+read before that table. The refusal is the only code that gets it: the WebSocket post-send
+verdicts are genuine upstream observations and keep their existing 502/504 contract. The
+acceptance evidence is a count, not a shape — `tests/server/replay-refusal-parity.test.ts` runs
+the proxy over a socket, drives all four surfaces with a client that implements the published
+SDK rule, and asserts one physical upstream send per logical request, with a rate-limit control
+that shows the same client resending.
+
 The existing provider HTTP-status policy and the shared physical-send budget remain
 independent: zero refuses dispatch, invalid counts fail, and a stopped send is counted once.
 `src/bridge/errors.ts` retains only the allowlisted non-replayable transport codes,
diff --git a/tests/adapters/adapter-input-media-guard.test.ts b/tests/adapters/adapter-input-media-guard.test.ts
index c63c137d52b..ff98aa347d8 100644
--- a/tests/adapters/adapter-input-media-guard.test.ts
+++ b/tests/adapters/adapter-input-media-guard.test.ts
@@ -8,13 +8,17 @@ import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig } from "../../sr
 import { createTestTranslatorBudget, withTestTranslatorBudget } from "../helpers/translator-budget";
 
 const AUDIO = { type: "input_audio", audio_url: "data:audio/wav;base64,YWJj" };
-const FILE = { type: "input_file", filename: "private.pdf", file_data: "data:application/pdf;base64,JVBERi0=" };
+// A reference this route cannot dereference: there are no bytes to carry anywhere.
+const FILE = { type: "input_file", filename: "private.pdf", file_id: "file-private" };
+// The same attachment with its bytes. User content has a carrier for it (#5212); no other
+// position does, because every other converter reduces its content to text.
+const INLINE_FILE = { type: "input_file", filename: "private.pdf", file_data: "data:application/pdf;base64,JVBERi0=" };
 
 function request(content: unknown[]): OcxParsedRequest {
   return parseRequest({ model: "test-model", input: [{ type: "message", role: "user", content }] });
 }
 
-function fakeAdapter() {
+function fakeAdapter(wire: "openai-chat" | "cursor" = "openai-chat") {
   const seen = { builds: 0, runs: 0, terminals: 0 };
   const adapter: ProviderAdapter = {
     name: "stub",
@@ -26,7 +30,7 @@ function fakeAdapter() {
     async runTurn(_parsed, _incoming, emit) { seen.runs++; emit({ type: "done", endTurn: true }); },
     localTerminal() { seen.terminals++; return { reason: "already answered" }; },
   };
-  return { adapter: withInputMediaGuard(adapter), seen };
+  return { adapter: withInputMediaGuard(adapter, wire), seen };
 }
 
 describe("typed input media inspection", () => {
@@ -39,6 +43,43 @@ describe("typed input media inspection", () => {
     for (const type of ["function_call_output", "custom_tool_call_output"]) {
       expect(untranslatedResponsesInputMedia({ input: [{ type, call_id: "call1", output: [AUDIO] }] })).toBe("audio");
       expect(untranslatedResponsesInputMedia({ input: [{ type, call_id: "call1", output: [FILE] }] })).toBe("file");
+      // Bytes do not help here: the tool-output converter flattens its content to text.
+      expect(untranslatedResponsesInputMedia({ input: [{ type, call_id: "call1", output: [INLINE_FILE] }] })).toBe("file");
+    }
+  });
+
+  test("an inline document is permitted only where a converter carries it", () => {
+    expect(untranslatedResponsesInputMedia(request([INLINE_FILE])._rawBody)).toBeUndefined();
+    for (const role of ["developer", "user"]) {
+      expect(untranslatedResponsesInputMedia({ input: [{ type: "message", role, content: [INLINE_FILE] }] }))
+        .toBeUndefined();
+    }
+    for (const role of ["system", "assistant"]) {
+      expect(untranslatedResponsesInputMedia({ input: [{ type: "message", role, content: [INLINE_FILE] }] }))
+        .toBe("file");
+    }
+  });
+
+  test("a document still has to reach a wire that can hold its bytes", () => {
+    const incoming = { headers: new Headers(), translatorBudget: createTestTranslatorBudget() };
+    const carrier = fakeAdapter("openai-chat");
+    carrier.adapter.buildRequest(request([INLINE_FILE]), incoming);
+    expect(carrier.seen.builds).toBe(1);
+
+    // Cursor rebuilds user content as text, so admitting the bytes there would put the request
+    // upstream with only the marker and return a normal completion.
+    const nonCarrier = fakeAdapter("cursor");
+    let failure: unknown;
+    try { nonCarrier.adapter.buildRequest(request([INLINE_FILE]), incoming); } catch (error) { failure = error; }
+    expect((failure as Error).message).toContain("OpenCodex cannot translate document input");
+    expect((failure as Error).message).not.toContain("private.pdf");
+    expect(nonCarrier.seen.builds).toBe(0);
+  });
+
+  test("a base64 look-alike parameter is not an inline payload", () => {
+    for (const fileData of ["data:text/plain;notbase64,abc", "data:text/plain;x=base64,abc", "data:text/plain,abc"]) {
+      expect(untranslatedResponsesInputMedia(request([{ type: "input_file", file_data: fileData }])._rawBody))
+        .toBe("file");
     }
   });
 
diff --git a/tests/adapters/anthropic/anthropic-tool-declaration-constraints.test.ts b/tests/adapters/anthropic/anthropic-tool-declaration-constraints.test.ts
new file mode 100644
index 00000000000..841fe1fa933
--- /dev/null
+++ b/tests/adapters/anthropic/anthropic-tool-declaration-constraints.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, test } from "bun:test";
+import { createAnthropicAdapter } from "../../../src/adapters/anthropic";
+import { createRegisteredAdapter } from "../../../src/adapters/registry";
+import { anthropicToResponsesBody } from "../../../src/claude/inbound";
+import { parseRequest } from "../../../src/responses/parser";
+import { createTestTranslatorBudget } from "../../helpers/translator-budget";
+import type { OcxParsedRequest, OcxProviderConfig } from "../../../src/types";
+
+/**
+ * #5210. `strict` and `allowed_callers` are declaration fields Anthropic defines, and the
+ * Messages-to-Messages route rebuilt every tool from name, description and input_schema alone.
+ * The request succeeded, so a caller had no way to learn that the schema was no longer enforced
+ * or that the tool had been offered to a caller it was fenced off from. Each case below reads
+ * the request the adapter actually sends.
+ */
+
+const anthropicProvider = {
+  adapter: "anthropic",
+  baseUrl: "https://api.anthropic.com",
+  apiKey: "sk-x",
+  authMode: "apiKey",
+} as unknown as OcxProviderConfig;
+
+function claudeTool(extra: Record<string, unknown>): Record<string, unknown> {
+  return {
+    name: "tool_a",
+    description: "Controlled tool.",
+    input_schema: { type: "object", properties: {} },
+    ...extra,
+  };
+}
+
+function parsedFromClaude(tool: Record<string, unknown>): OcxParsedRequest {
+  return parseRequest(anthropicToResponsesBody({
+    model: "anthropic/claude-sonnet-4.5",
+    max_tokens: 64,
+    messages: [{ role: "user", content: "Call the tool." }],
+    tools: [tool],
+  }));
+}
+
+async function anthropicTools(tool: Record<string, unknown>): Promise<Array<Record<string, unknown>>> {
+  const { body } = await createAnthropicAdapter(anthropicProvider).buildRequest(parsedFromClaude(tool));
+  return (JSON.parse(typeof body === "string" ? body : JSON.stringify(body)) as {
+    tools: Array<Record<string, unknown>>;
+  }).tools;
+}
+
+describe("anthropic tool declarations carry their caller-supplied constraints", () => {
+  test("an explicit strict:true survives the round trip", async () => {
+    const [tool] = await anthropicTools(claudeTool({ strict: true }));
+    expect(tool.strict).toBe(true);
+    expect(tool.name).toBe("tool_a");
+    expect(tool.input_schema).toEqual({ type: "object", properties: {} });
+  });
+
+  test("an unstated strict stays absent rather than becoming an opt-out", async () => {
+    const [tool] = await anthropicTools(claudeTool({}));
+    expect(tool).not.toHaveProperty("strict");
+    const [explicitFalse] = await anthropicTools(claudeTool({ strict: false }));
+    expect(explicitFalse).not.toHaveProperty("strict");
+  });
+
+  test("allowed_callers reaches the upstream instead of being rebuilt away", async () => {
+    const [tool] = await anthropicTools(claudeTool({ allowed_callers: ["code_execution_20260120"] }));
+    expect(tool.allowed_callers).toEqual(["code_execution_20260120"]);
+  });
+
+  test("a tool without allowed_callers gains no key", async () => {
+    const [tool] = await anthropicTools(claudeTool({}));
+    expect(tool).not.toHaveProperty("allowed_callers");
+  });
+});
+
+describe("wires without an allowed_callers counterpart refuse rather than widen", () => {
+  const restricted = claudeTool({ allowed_callers: ["code_execution_20260120"] });
+  const unrestricted = claudeTool({ allowed_callers: ["direct"] });
+  const incoming = { headers: new Headers(), translatorBudget: createTestTranslatorBudget() };
+
+  // The refusal is default-deny at the single guard every registered adapter passes through, so
+  // a wire that never learned about the field cannot quietly rebuild the declaration without it.
+  test.each([
+    ["openai-chat", { adapter: "openai-chat", baseUrl: "https://gateway.example.internal/v1", apiKey: "k" }],
+    ["google", { adapter: "google", baseUrl: "https://generativelanguage.googleapis.com", apiKey: "key" }],
+    ["cursor", { adapter: "cursor", baseUrl: "https://api2.cursor.sh", apiKey: "k" }],
+    ["devin", { adapter: "devin", baseUrl: "https://api.devin.ai", apiKey: "k" }],
+    ["ollama-native", { adapter: "ollama-native", baseUrl: "http://127.0.0.1:11434", keyOptional: true }],
+  ])("the %s wire refuses a caller-restricted declaration", async (_name, config) => {
+    const adapter = createRegisteredAdapter(config as unknown as OcxProviderConfig);
+    await expect(Promise.resolve().then(() => adapter.buildRequest(parsedFromClaude(restricted), incoming)))
+      .rejects.toThrow(/cannot express tools\[\]\.allowed_callers/);
+  });
+
+  test("the Anthropic wire is the one that carries it", async () => {
+    const adapter = createRegisteredAdapter(anthropicProvider);
+    const { body } = await adapter.buildRequest(parsedFromClaude(restricted), incoming);
+    const sent = JSON.parse(typeof body === "string" ? body : JSON.stringify(body)) as {
+      tools: Array<Record<string, unknown>>;
+    };
+    expect(sent.tools[0]!.allowed_callers).toEqual(["code_execution_20260120"]);
+  });
+
+  test('the unrestricted ["direct"] default is not treated as a restriction', async () => {
+    const adapter = createRegisteredAdapter({
+      adapter: "openai-chat",
+      baseUrl: "https://gateway.example.internal/v1",
+      apiKey: "k",
+    } as unknown as OcxProviderConfig);
+    // Registered adapters may wrap buildRequest in a promise; await rather than assume a shape.
+    const { body } = await adapter.buildRequest(parsedFromClaude(unrestricted), incoming);
+    const built = JSON.parse(typeof body === "string" ? body : JSON.stringify(body)) as {
+      tools: Array<{ function: { name: string } }>;
+    };
+    expect(built.tools.map(tool => tool.function.name)).toEqual(["tool_a"]);
+  });
+});
diff --git a/tests/adapters/google/google-strict-tool-validated-mode.test.ts b/tests/adapters/google/google-strict-tool-validated-mode.test.ts
new file mode 100644
index 00000000000..f508162ec60
--- /dev/null
+++ b/tests/adapters/google/google-strict-tool-validated-mode.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { createGoogleAdapter } from "../../../src/adapters/google";
+import type { OcxParsedRequest, OcxProviderConfig } from "../../../src/types";
+
+/**
+ * #5210 case 3. Gemini expresses schema-enforced function calling as
+ * `functionCallingConfig.mode: "VALIDATED"`. The mode was plumbed all the way to the wire
+ * compiler but was only reachable by matching a model name, so a caller that declared strict
+ * tools got an ordinary AUTO turn and a normal answer. These assertions read the compiled
+ * request body, which is the only place the difference is visible.
+ */
+
+const provider = {
+  adapter: "google",
+  baseUrl: "https://generativelanguage.googleapis.com",
+  apiKey: "key",
+} as unknown as OcxProviderConfig;
+
+const STRICT_TOOLS = [
+  { name: "get_weather", description: "", parameters: { type: "object", properties: {} }, strict: true },
+  { name: "shot", description: "", parameters: { type: "object", properties: {} } },
+];
+const LOOSE_TOOLS = STRICT_TOOLS.map(({ strict: _strict, ...rest }) => rest);
+
+async function toolConfig(tools: unknown[], toolChoice?: unknown): Promise<unknown> {
+  const parsed = {
+    modelId: "gemini-3-pro",
+    stream: false,
+    options: toolChoice === undefined ? {} : { toolChoice },
+    context: { messages: [{ role: "user", content: "hi" }], tools },
+  } as unknown as OcxParsedRequest;
+  const { body } = await createGoogleAdapter(provider).buildRequest(parsed);
+  return (JSON.parse(body) as Record<string, unknown>).toolConfig;
+}
+
+describe("strict tool declarations select Gemini VALIDATED function calling", () => {
+  test("a strict declaration turns the absent-choice default into VALIDATED", async () => {
+    expect(await toolConfig(STRICT_TOOLS)).toEqual({ functionCallingConfig: { mode: "VALIDATED" } });
+    expect(await toolConfig(STRICT_TOOLS, "auto")).toEqual({ functionCallingConfig: { mode: "VALIDATED" } });
+  });
+
+  test("an allowed-tools subset in auto mode keeps VALIDATED when the subset is strict", async () => {
+    expect(await toolConfig(STRICT_TOOLS, { allowedTools: ["get_weather"], mode: "auto" }))
+      .toEqual({ functionCallingConfig: { mode: "VALIDATED" } });
+  });
+
+  test("a subset that excludes the strict tool does not claim validation", async () => {
+    expect(await toolConfig(STRICT_TOOLS, { allowedTools: ["shot"], mode: "auto" })).toBeUndefined();
+  });
+
+  test("without a strict declaration the wire is unchanged", async () => {
+    expect(await toolConfig(LOOSE_TOOLS)).toBeUndefined();
+    expect(await toolConfig(LOOSE_TOOLS, "auto")).toBeUndefined();
+    expect(await toolConfig(LOOSE_TOOLS, { allowedTools: ["get_weather"], mode: "auto" })).toBeUndefined();
+  });
+
+  test("a stronger caller-chosen mode is never overwritten by VALIDATED", async () => {
+    expect(await toolConfig(STRICT_TOOLS, "none")).toEqual({ functionCallingConfig: { mode: "NONE" } });
+    expect(await toolConfig(STRICT_TOOLS, "required")).toEqual({ functionCallingConfig: { mode: "ANY" } });
+    expect(await toolConfig(STRICT_TOOLS, { allowedTools: ["get_weather"], mode: "required" }))
+      .toEqual({ functionCallingConfig: { mode: "ANY" } });
+    expect(await toolConfig(STRICT_TOOLS, { name: "get_weather" }))
+      .toEqual({ functionCallingConfig: { mode: "ANY", allowedFunctionNames: ["get_weather"] } });
+  });
+
+  test("a request with no declared tools gains no toolConfig", async () => {
+    expect(await toolConfig([])).toBeUndefined();
+  });
+});
diff --git a/tests/adapters/openai/openai-chat-dangling-toolcalls.test.ts b/tests/adapters/openai/openai-chat-dangling-toolcalls.test.ts
index df5e8afc5b7..408dcacbd1e 100644
--- a/tests/adapters/openai/openai-chat-dangling-toolcalls.test.ts
+++ b/tests/adapters/openai/openai-chat-dangling-toolcalls.test.ts
@@ -12,6 +12,11 @@ const provider: OcxProviderConfig = {
   baseUrl: "https://example.test/v1",
   apiKey: "sk-test",
   authMode: "key",
+  // These cases assert where a developer barrier lands relative to a pending tool call, not
+  // which role carries it. The wire role folds to `system` unless a destination records that
+  // it accepts `developer`, so the destination is declared here and the assertions keep
+  // reading the role they were written against.
+  foldDeveloperRoleToSystem: false,
 };
 
 interface ChatMsg {
@@ -90,7 +95,7 @@ function assertWireInvariants(messages: ChatMsg[]): void {
 }
 
 describe("openai-chat dangling tool_calls hardening", () => {
-  test("T1 incident: developer guidance is hoisted while the real result reattaches to the original call", () => {
+  test("T1 incident: developer guidance lands after the result while the result reattaches to the original call", () => {
     const messages = wire([
       user("hi"),
       assistantWithCalls([{ id: "call_x", name: "request_user_input" }]),
@@ -100,14 +105,14 @@ describe("openai-chat dangling tool_calls hardening", () => {
     ]);
     assertWireInvariants(messages);
     const roles = messages.map(m => m.role);
-    expect(messages[0]).toEqual({ role: "system", content: "[injected guidance]" });
-    // canonical history order: assistant, tool(real), user; no in-history system barrier
+    expect(messages[0]).toEqual({ role: "user", content: "hi" });
+    // canonical history order: assistant, tool(real), then the barrier in its own slot (#5213)
     const aIdx = roles.indexOf("assistant");
     expect(roles[aIdx + 1]).toBe("tool");
     expect(messages[aIdx + 1].tool_call_id).toBe("call_x");
     expect(messages[aIdx + 1].content).toBe('{"answers":{}}');
-    expect(roles[aIdx + 2]).toBe("user");
-    expect(messages.slice(1).some(m => m.role === "system")).toBe(false);
+    expect(messages[aIdx + 2]).toEqual({ role: "developer", content: "[injected guidance]" });
+    expect(roles[aIdx + 3]).toBe("user");
     // no synthetic result fabricated for an answered call
     expect(messages.some(m => typeof m.content === "string" && m.content.includes("no tool result was recorded"))).toBe(false);
   });
@@ -166,9 +171,9 @@ describe("openai-chat dangling tool_calls hardening", () => {
     expect(String(synth?.content)).toContain("no tool result was recorded");
     const real = block.find(m => m.tool_call_id === "call_2");
     expect(real?.content).toBe("img-ok");
-    expect(messages[0]).toEqual({ role: "system", content: "barrier while call_1 pending" });
-    expect(messages[aIdx + 3].role).toBe("assistant");
-    expect(messages.slice(1).some(m => m.role === "system")).toBe(false);
+    expect(messages[0]).toEqual({ role: "user", content: "hi" });
+    expect(messages[aIdx + 3]).toEqual({ role: "developer", content: "barrier while call_1 pending" });
+    expect(messages[aIdx + 4].role).toBe("assistant");
   });
 
   test("T6 mismatched result while calls pending: round closes synthetically, then orphan pair", () => {
@@ -183,9 +188,9 @@ describe("openai-chat dangling tool_calls hardening", () => {
     expect(messages[aIdx + 1].role).toBe("tool");
     expect(messages[aIdx + 1].tool_call_id).toBe("call_p");
     expect(String(messages[aIdx + 1].content)).toContain("no tool result was recorded");
-    expect(messages[0]).toEqual({ role: "system", content: "deferred barrier" });
-    expect(messages[aIdx + 2].role).toBe("assistant");
-    expect(messages.slice(1).some(m => m.role === "system")).toBe(false);
+    expect(messages[0]).toEqual({ role: "user", content: "hi" });
+    expect(messages[aIdx + 2]).toEqual({ role: "developer", content: "deferred barrier" });
+    expect(messages[aIdx + 3].role).toBe("assistant");
     const orphanIdx = messages.findIndex((m, i) => i > aIdx && m.role === "assistant");
     expect(messages[orphanIdx].tool_calls?.[0].id).toBe("call_unknown");
     expect(messages[orphanIdx + 1].tool_call_id).toBe("call_unknown");
diff --git a/tests/adapters/openai/openai-chat-developer-position.test.ts b/tests/adapters/openai/openai-chat-developer-position.test.ts
new file mode 100644
index 00000000000..b3db3f742b8
--- /dev/null
+++ b/tests/adapters/openai/openai-chat-developer-position.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import { createOpenAIChatAdapter } from "../../../src/adapters/openai-chat";
+import type { OcxParsedRequest, OcxProviderConfig } from "../../../src/types";
+
+/**
+ * #5213. A `developer` message used to keep its slot only when the provider base URL host was
+ * exactly `api.openai.com`. Everywhere else its text was appended to the system prompt and the
+ * message itself was skipped, so an instruction written to apply from the second turn onward
+ * arrived ahead of the first one. Both shapes return a normal completion, which is why these
+ * assertions read the serialized request body rather than the response.
+ */
+
+const gateway: OcxProviderConfig = {
+  adapter: "openai-chat",
+  baseUrl: "https://gateway.example.internal/v1",
+  apiKey: "k",
+};
+
+function wireMessages(provider: OcxProviderConfig): Array<Record<string, unknown>> {
+  const parsed = {
+    modelId: "local-model",
+    context: {
+      systemPrompt: ["base instructions"],
+      messages: [
+        { role: "user", content: "First turn.", timestamp: 0 },
+        { role: "developer", content: "Answer in exactly one sentence.", timestamp: 0 },
+        { role: "user", content: "Second turn.", timestamp: 0 },
+      ],
+    },
+    stream: false,
+    options: {},
+  } as unknown as OcxParsedRequest;
+  const request = createOpenAIChatAdapter(provider).buildRequest(parsed);
+  return (JSON.parse(request.body) as { messages: Array<Record<string, unknown>> }).messages;
+}
+
+describe("developer message placement on the Chat wire", () => {
+  test("a non-OpenAI gateway keeps the instruction between the two turns", () => {
+    const messages = wireMessages(gateway);
+    expect(messages[0]).toEqual({ role: "system", content: "base instructions" });
+    expect(messages[1]).toEqual({ role: "user", content: "First turn." });
+    expect(messages[2].content).toBe("Answer in exactly one sentence.");
+    expect(messages[3]).toEqual({ role: "user", content: "Second turn." });
+  });
+
+  test("the leading system block no longer absorbs the instruction", () => {
+    expect(String(wireMessages(gateway)[0].content)).not.toContain("Answer in exactly one sentence.");
+  });
+
+  test("placement does not depend on the destination host", () => {
+    const hosts = [
+      "https://openrouter.ai/api/v1",
+      "http://localhost:1234/v1",
+      "https://api.openai.com/v1",
+    ];
+    // Placement is asserted for both role states, because the role is decided separately and
+    // must never be able to move the message.
+    for (const baseUrl of hosts) {
+      for (const declared of [{}, { foldDeveloperRoleToSystem: false }, { foldDeveloperRoleToSystem: true }]) {
+        const messages = wireMessages({ ...gateway, baseUrl, ...declared });
+        expect(messages).toHaveLength(4);
+        expect(messages[2].content).toBe("Answer in exactly one sentence.");
+        expect(messages[3]).toEqual({ role: "user", content: "Second turn." });
+      }
+    }
+  });
+});
+
+describe("developer role on the Chat wire", () => {
+  test("an undeclared destination folds the role rather than gambling on it", () => {
+    // The reason this is the default: a gateway that rejects the role answers
+    // `400 role 'developer' is not allowed` and the turn never starts. Forwarding by default
+    // put that failure outside the repository, where no test could reach it.
+    for (const baseUrl of ["https://openrouter.ai/api/v1", "http://localhost:1234/v1", "https://api.openai.com/v1"]) {
+      expect(wireMessages({ ...gateway, baseUrl })[2]).toEqual({
+        role: "system",
+        content: "Answer in exactly one sentence.",
+      });
+    }
+  });
+
+  test("the role still never depends on the destination hostname", () => {
+    const declared = { ...gateway, foldDeveloperRoleToSystem: false };
+    for (const baseUrl of ["https://openrouter.ai/api/v1", "https://api.openai.com/v1"]) {
+      expect(wireMessages({ ...declared, baseUrl })[2].role).toBe("developer");
+    }
+    for (const baseUrl of ["https://openrouter.ai/api/v1", "https://api.openai.com/v1"]) {
+      expect(wireMessages({ ...gateway, baseUrl })[2].role).toBe("system");
+    }
+  });
+
+  test("a destination that rejects the role converts it without moving the message", () => {
+    const messages = wireMessages({ ...gateway, foldDeveloperRoleToSystem: true });
+    expect(messages.map(message => message.role)).toEqual(["system", "user", "system", "user"]);
+    expect(messages[2]).toEqual({ role: "system", content: "Answer in exactly one sentence." });
+    expect(String(messages[0].content)).not.toContain("Answer in exactly one sentence.");
+  });
+
+  test("a destination known to accept the role forwards it in the same slot", () => {
+    const messages = wireMessages({ ...gateway, foldDeveloperRoleToSystem: false });
+    expect(messages.map(message => message.role)).toEqual(["system", "user", "developer", "user"]);
+    expect(messages[2]).toEqual({ role: "developer", content: "Answer in exactly one sentence." });
+  });
+});
diff --git a/tests/adapters/openai/openai-chat-reasoning-wire-policy.test.ts b/tests/adapters/openai/openai-chat-reasoning-wire-policy.test.ts
new file mode 100644
index 00000000000..5814291eef6
--- /dev/null
+++ b/tests/adapters/openai/openai-chat-reasoning-wire-policy.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildOpenAIChatPassthroughRequest,
+  createOpenAIChatAdapter,
+} from "../../../src/adapters/openai-chat";
+import { chatCompletionsToResponsesBody } from "../../../src/chat/inbound";
+import { parseRequest } from "../../../src/responses/parser";
+import type { OcxProviderConfig } from "../../../src/types";
+
+const provider: OcxProviderConfig = {
+  adapter: "openai-chat",
+  baseUrl: "https://gateway.example.test/v1",
+  apiKey: "sk-test",
+  authMode: "key",
+  reasoningWireFormat: "gateway-object",
+  omitReasoningEffortWithToolsModels: ["reasoning-policy-model"],
+};
+const modelId = provider.omitReasoningEffortWithToolsModels![0]!;
+
+const input: Record<string, unknown> = {
+  model: modelId,
+  messages: [{ role: "user", content: "What is the weather?" }],
+  reasoning_effort: "none",
+};
+const tool: Record<string, unknown> = {
+  type: "function",
+  function: {
+    name: "get_weather",
+    description: "Get the weather for a city",
+    parameters: {
+      type: "object",
+      properties: { city: { type: "string" } },
+      required: ["city"],
+      additionalProperties: false,
+    },
+  },
+};
+const inputWithTool: Record<string, unknown> = { ...input, tools: [tool] };
+
+function finalBodies(rawInput: Record<string, unknown>): Record<"translated" | "native", Record<string, unknown>> {
+  const parsed = parseRequest(chatCompletionsToResponsesBody(rawInput));
+  const translated = createOpenAIChatAdapter(provider).buildRequest(parsed);
+  const native = buildOpenAIChatPassthroughRequest(provider, rawInput, modelId, false);
+
+  return {
+    translated: JSON.parse(translated.body) as Record<string, unknown>,
+    native: JSON.parse(native.body) as Record<string, unknown>,
+  };
+}
+
+describe("OpenAI Chat reasoning wire policy parity", () => {
+  test("plain reasoning disable uses the gateway object on both final wires", () => {
+    const bodies = finalBodies(input);
+    const projection = Object.fromEntries(Object.entries(bodies).map(([builder, body]) => [
+      builder,
+      {
+        reasoning: body.reasoning,
+        hasReasoningEffort: Object.hasOwn(body, "reasoning_effort"),
+      },
+    ]));
+
+    expect(projection).toEqual({
+      translated: { reasoning: { enabled: false }, hasReasoningEffort: false },
+      native: { reasoning: { enabled: false }, hasReasoningEffort: false },
+    });
+  });
+
+  test("a function tool survives while both final wires omit all reasoning fields", () => {
+    const bodies = finalBodies(inputWithTool);
+    const projection = Object.fromEntries(Object.entries(bodies).map(([builder, body]) => [
+      builder,
+      {
+        tools: body.tools,
+        hasReasoning: Object.hasOwn(body, "reasoning"),
+        hasReasoningEffort: Object.hasOwn(body, "reasoning_effort"),
+      },
+    ]));
+
+    expect(projection).toEqual({
+      translated: { tools: [tool], hasReasoning: false, hasReasoningEffort: false },
+      native: { tools: [tool], hasReasoning: false, hasReasoningEffort: false },
+    });
+  });
+});
diff --git a/tests/adapters/openai/openai-chat-system-order.test.ts b/tests/adapters/openai/openai-chat-system-order.test.ts
index def3179d814..ea2edf915f4 100644
--- a/tests/adapters/openai/openai-chat-system-order.test.ts
+++ b/tests/adapters/openai/openai-chat-system-order.test.ts
@@ -8,6 +8,10 @@ const provider: OcxProviderConfig = {
   adapter: "openai-chat",
   baseUrl: "http://localhost:1234/v1",
   apiKey: "local",
+  // These cases assert where a reminder sits, not which role carries it. The wire role folds
+  // to `system` unless a destination is recorded as accepting `developer`, so the destination
+  // is declared here to keep the ordering assertions reading the role they are about.
+  foldDeveloperRoleToSystem: false,
 };
 
 function buildMessages(context: OcxParsedRequest["context"]): Array<Record<string, unknown>> {
@@ -21,7 +25,7 @@ function buildMessages(context: OcxParsedRequest["context"]): Array<Record<strin
 }
 
 describe("openai-chat system message ordering", () => {
-  test("folds interleaved developer reminders into one leading system message", () => {
+  test("keeps interleaved developer reminders in their original slots", () => {
     const messages = buildMessages({
       systemPrompt: ["base instructions"],
       messages: [
@@ -44,13 +48,15 @@ describe("openai-chat system message ordering", () => {
 
     expect(messages[0]).toEqual({
       role: "system",
-      content: "base instructions\n\nfirst reminder\n\nsecond reminder",
+      content: "base instructions",
     });
-    expect(messages.slice(1).map(message => message.role)).toEqual(["user", "assistant", "user"]);
-    expect(messages.slice(1).some(message => message.role === "system")).toBe(false);
+    expect(messages.map(message => message.role))
+      .toEqual(["system", "user", "developer", "assistant", "developer", "user"]);
+    expect(messages[2]).toEqual({ role: "developer", content: "first reminder" });
+    expect(messages[4]).toEqual({ role: "developer", content: "second reminder" });
   });
 
-  test("keeps tool calls and results adjacent when a developer reminder follows the call", () => {
+  test("defers a reminder past a pending tool result instead of hoisting it", () => {
     const messages = buildMessages({
       messages: [
         { role: "user", content: "inspect", timestamp: 0 },
@@ -72,9 +78,11 @@ describe("openai-chat system message ordering", () => {
       ],
     });
 
-    expect(messages[0]).toEqual({ role: "system", content: "remember the policy" });
-    expect(messages.map(message => message.role)).toEqual(["system", "user", "assistant", "tool"]);
-    expect(messages[3]).toMatchObject({ role: "tool", tool_call_id: "call_1" });
+    // The reminder arrived while call_1 was open. Emitting it there would break tool-call
+    // adjacency, so it is released immediately after the result rather than moved to the front.
+    expect(messages.map(message => message.role)).toEqual(["user", "assistant", "tool", "developer"]);
+    expect(messages[2]).toMatchObject({ role: "tool", tool_call_id: "call_1" });
+    expect(messages[3]).toEqual({ role: "developer", content: "remember the policy" });
   });
 
   test("keeps developer vision content as a user-compatible message in place", () => {
@@ -104,12 +112,13 @@ describe("openai-chat system message ordering", () => {
   });
 });
 
-describe("OpenCode Go DeepSeek chronological system messages", () => {
+describe("chronological in-conversation system messages", () => {
   const model = "deepseek-v4.1-flash";
   const ocg: OcxProviderConfig = {
     adapter: "openai-chat",
     baseUrl: "https://opencode.ai/zen/go/v1",
     preserveReasoningContentModels: [model],
+    foldDeveloperRoleToSystem: false,
   };
   const history = [
     { role: "user", content: "Inspect the synthetic project." },
@@ -141,10 +150,10 @@ describe("OpenCode Go DeepSeek chronological system messages", () => {
       { role: "system", content: "Synthetic reminder B." },
     ], ocg, model, stabilize);
     expect(JSON.stringify(next.messages.slice(0, first.messages.length))).toBe(JSON.stringify(first.messages));
-    expect(first.messages.map((message: { role: string }) => message.role)).toEqual(["system", "user", "assistant", "system"]);
+    expect(first.messages.map((message: { role: string }) => message.role)).toEqual(["system", "user", "assistant", "developer"]);
     expect(first.messages[0].content).not.toContain("Synthetic reminder A.");
-    expect(first.messages.at(-1)).toEqual({ role: "system", content: "Synthetic reminder A." });
-    expect(next.messages.at(-1)).toEqual({ role: "system", content: "Synthetic reminder B." });
+    expect(first.messages.at(-1)).toEqual({ role: "developer", content: "Synthetic reminder A." });
+    expect(next.messages.at(-1)).toEqual({ role: "developer", content: "Synthetic reminder B." });
     expect(next.tools).toEqual(first.tools);
     expect(next.model).toBe(model);
     expect(next.stream).toBe(true);
@@ -161,14 +170,14 @@ describe("OpenCode Go DeepSeek chronological system messages", () => {
     expect(callIndex).toBeGreaterThan(0);
     expect(body.messages[callIndex].reasoning_content).toBe(" ");
     expect(body.messages[callIndex + 1]).toMatchObject({ role: "tool", tool_call_id: "call_fixture", content: "Fixture result." });
-    expect(body.messages[callIndex + 2]).toEqual({ role: "system", content: "Reminder during pending tool." });
+    expect(body.messages[callIndex + 2]).toEqual({ role: "developer", content: "Reminder during pending tool." });
   });
 
   test.each([
     "https://opencode.ai/zen/go/v1/",
     "https://opencode.ai:443/zen/go/v1",
-  ])("matches the canonical destination %s", baseUrl => {
-    expect(build(history, { ...ocg, baseUrl }).messages.at(-1).role).toBe("system");
+  ])("keeps the reminder last on the canonical OpenCode Go destination %s", baseUrl => {
+    expect(build(history, { ...ocg, baseUrl }).messages.at(-1).role).toBe("developer");
   });
 
   test.each([
@@ -177,22 +186,34 @@ describe("OpenCode Go DeepSeek chronological system messages", () => {
     "https://opencode.ai:444/zen/go/v1",
     "http://opencode.ai/zen/go/v1",
     "http://localhost:1234/v1",
-  ])("retains generic hoisting for other destinations: %s", baseUrl => {
+  ])("keeps the same chronological placement on other destinations: %s", baseUrl => {
     const messages = build(history, { ...ocg, baseUrl }).messages;
-    expect(messages[0].content).toContain("Synthetic reminder A.");
-    expect(messages.map((message: { role: string }) => message.role)).toEqual(["system", "user", "assistant"]);
+    expect(messages[0].content).not.toContain("Synthetic reminder A.");
+    expect(messages.map((message: { role: string }) => message.role))
+      .toEqual(["system", "user", "assistant", "developer"]);
+    expect(messages.at(-1)).toEqual({ role: "developer", content: "Synthetic reminder A." });
   });
 
-  test("retains generic hoisting for other OCG models", () => {
-    expect(build(history, ocg, "kimi-k3").messages[0].content).toContain("Synthetic reminder A.");
+  test("placement no longer depends on the model either", () => {
+    const messages = build(history, ocg, "kimi-k3").messages;
+    expect(messages[0].content).not.toContain("Synthetic reminder A.");
+    expect(messages.at(-1)).toEqual({ role: "developer", content: "Synthetic reminder A." });
   });
 
-  test("retains native OpenAI developer roles", () => {
+  test("the native OpenAI wire is unchanged", () => {
     const messages = build(history, { ...ocg, baseUrl: "https://api.openai.com/v1" }).messages;
     expect(messages[0].content).not.toContain("Synthetic reminder A.");
     expect(messages.at(-1)).toEqual({ role: "developer", content: "Synthetic reminder A." });
   });
 
+  test("a destination that rejects the role folds it in place", () => {
+    const messages = build(history, { ...ocg, foldDeveloperRoleToSystem: true }).messages;
+    expect(messages.map((message: { role: string }) => message.role))
+      .toEqual(["system", "user", "assistant", "system"]);
+    expect(messages[0].content).not.toContain("Synthetic reminder A.");
+    expect(messages.at(-1)).toEqual({ role: "system", content: "Synthetic reminder A." });
+  });
+
   test("drops a non-text timeline message instead of emitting an empty system message", () => {
     const context = {
       messages: [
diff --git a/tests/adapters/run-turn-queue.test.ts b/tests/adapters/run-turn-queue.test.ts
index e983ab6a00a..b1f821d4818 100644
--- a/tests/adapters/run-turn-queue.test.ts
+++ b/tests/adapters/run-turn-queue.test.ts
@@ -1,5 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { COALESCE_MAX_CHUNK_LENGTH, createAdapterEventQueue, PREFLIGHT_HEARTBEAT_RETAIN_LIMIT, preflightAdapterEvents } from "../../src/adapters/run-turn-queue";
+import {
+  COALESCE_MAX_CHUNK_LENGTH,
+  createAdapterEventQueue,
+  DEFAULT_MAX_BACKLOG_CODE_UNITS,
+  DEFAULT_MAX_EVENT_CODE_UNITS,
+  PREFLIGHT_HEARTBEAT_RETAIN_LIMIT,
+  preflightAdapterEvents,
+  retainedEventCodeUnits,
+} from "../../src/adapters/run-turn-queue";
 import type { AdapterEvent } from "../../src/types";
 
 const text = (value: string): AdapterEvent => ({ type: "text_delta", text: value });
@@ -340,3 +348,173 @@ describe("run-turn adapter event preflight", () => {
     expect(cancelled).toBe(1);
   });
 });
+
+describe("run-turn adapter event queue retained-payload budgets", () => {
+  const BACKLOG_EXCEEDED = "consumer stalled: adapter event backlog exceeded — turn aborted";
+  const EVENT_TOO_LARGE = "adapter event exceeds the single-event retained-string budget — turn aborted";
+
+  test("a stalled consumer is bounded by retained payload, not by the event count alone", async () => {
+    let backlogExceeded = 0;
+    const queue = createAdapterEventQueue({
+      maxBacklogCodeUnits: 8,
+      maxEventCodeUnits: 8,
+      onBacklogExceeded: () => { backlogExceeded += 1; },
+    });
+
+    // Each event on its own is within the per-event budget, so only the
+    // aggregate can be what refuses the second one.
+    expect(retainedEventCodeUnits(toolStart("0"))).toBeLessThanOrEqual(8);
+    queue.push(toolStart("0"));
+    queue.push(toolStart("1"));
+
+    expect(backlogExceeded).toBe(1);
+    expect(await queue.collect()).toEqual([
+      toolStart("0"),
+      { type: "error", message: BACKLOG_EXCEEDED },
+    ]);
+    expect(queue.retainedCodeUnits()).toBe(0);
+  });
+
+  test("one oversized event is refused with its own cause even into an empty queue", async () => {
+    let backlogExceeded = 0;
+    const queue = createAdapterEventQueue({
+      maxEventCodeUnits: 8,
+      onBacklogExceeded: () => { backlogExceeded += 1; },
+    });
+
+    // The aggregate has its whole default budget free; this refusal is about
+    // the single event, and it has to say so rather than blame the consumer.
+    queue.push(text("x".repeat(9)));
+
+    expect(backlogExceeded).toBe(1);
+    expect(await queue.collect()).toEqual([{ type: "error", message: EVENT_TOO_LARGE }]);
+    expect(queue.retainedCodeUnits()).toBe(0);
+  });
+
+  test("accumulated coalescing is charged by retained growth, not once per merged delta", async () => {
+    let backlogExceeded = 0;
+    const queue = createAdapterEventQueue({
+      maxBacklogCodeUnits: 16,
+      onBacklogExceeded: () => { backlogExceeded += 1; },
+    });
+
+    // Three 2-character deltas sharing one 10-character phase. Retained growth
+    // is 12 then +2 then +2; charging each whole event instead would bill 36
+    // and abort a turn holding sixteen code units.
+    queue.push(phasedText("ab", "commentary"));
+    queue.push(phasedText("cd", "commentary"));
+    queue.push(phasedText("ef", "commentary"));
+
+    expect(backlogExceeded).toBe(0);
+    expect(queue.retainedCodeUnits()).toBe(16);
+    queue.close();
+    expect(await queue.collect()).toEqual([phasedText("abcdef", "commentary")]);
+    expect(queue.retainedCodeUnits()).toBe(0);
+  });
+
+  test("an event handed straight to a waiting consumer is never charged or capped", async () => {
+    let backlogExceeded = 0;
+    const queue = createAdapterEventQueue({
+      maxBacklogCodeUnits: 4,
+      maxEventCodeUnits: 4,
+      onBacklogExceeded: () => { backlogExceeded += 1; },
+    });
+    const iterator = queue.stream()[Symbol.asyncIterator]();
+
+    const pending = iterator.next();
+    queue.push(text("x".repeat(1_000)));
+
+    // The queue never held it, so neither budget has anything to say about it:
+    // both govern retained payload, and refusing this would abort a turn over
+    // memory the queue does not own.
+    expect(await pending).toEqual({ done: false, value: text("x".repeat(1_000)) });
+    expect(backlogExceeded).toBe(0);
+    expect(queue.retainedCodeUnits()).toBe(0);
+    queue.close();
+  });
+
+  test("a long synchronous burst well past one mebibyte still completes", async () => {
+    let backlogExceeded = 0;
+    const queue = createAdapterEventQueue({
+      onBacklogExceeded: () => { backlogExceeded += 1; },
+    });
+
+    // A synchronous producer legally fills the queue before its consumer is
+    // scheduled — the image loop does this with over a million one-character
+    // deltas, which coalesce into more than a mebibyte of retained text. A
+    // retained budget sized near that burst aborts healthy turns, so the
+    // default has to sit well above it.
+    const chunk = "x".repeat(64);
+    for (let i = 0; i < 20_000; i++) queue.push(text(chunk));
+    queue.close();
+
+    const collected = await queue.collect();
+    expect(backlogExceeded).toBe(0);
+    expect(collected.map(event => (event.type === "text_delta" ? event.text.length : 0))
+      .reduce((sum, length) => sum + length, 0)).toBe(20_000 * 64);
+    expect(collected.every(event => event.type === "text_delta")).toBe(true);
+    expect(queue.retainedCodeUnits()).toBe(0);
+  });
+
+  test("draining after an abort releases exactly what was charged", async () => {
+    const queue = createAdapterEventQueue({ maxBacklogCodeUnits: 8, maxEventCodeUnits: 8 });
+
+    queue.push(toolStart("0"));
+    expect(queue.retainedCodeUnits()).toBeGreaterThan(0);
+    queue.push(toolStart("1"));
+
+    // The terminal record is admitted past the budget it reports, and is then
+    // charged and released like any other item, so the counter lands on zero
+    // rather than on the size of an explanation nobody paid for.
+    const iterator = queue.stream()[Symbol.asyncIterator]();
+    expect(await iterator.next()).toEqual({ done: false, value: toolStart("0") });
+    expect(await iterator.next()).toEqual({ done: false, value: { type: "error", message: BACKLOG_EXCEEDED } });
+    expect(await iterator.next()).toEqual({ done: true, value: undefined });
+    expect(queue.retainedCodeUnits()).toBe(0);
+  });
+
+  test("a cancel race leaves nothing charged behind", async () => {
+    const queue = createAdapterEventQueue({ maxBacklogCodeUnits: 64 });
+    const iterator = queue.stream()[Symbol.asyncIterator]();
+
+    queue.push(text("abcd"));
+    queue.push(thinking("wxyz"));
+    expect(await iterator.next()).toEqual({ done: false, value: text("abcd") });
+
+    // The consumer walks away mid-stream and the turn is closed underneath it.
+    await iterator.return?.();
+    queue.close();
+    queue.push(text("after close"));
+
+    // What is still queued is still charged — and nothing more, so a second
+    // drain returns the counter to zero without a phantom balance.
+    expect(queue.retainedCodeUnits()).toBe(4);
+    expect(await queue.collect()).toEqual([thinking("wxyz")]);
+    expect(queue.retainedCodeUnits()).toBe(0);
+  });
+
+  test("the retention measure counts payload strings and skips the discriminant", () => {
+    expect(retainedEventCodeUnits(text("abcd"))).toBe(4);
+    expect(retainedEventCodeUnits(heartbeat)).toBe(0);
+    expect(retainedEventCodeUnits(phasedText("ab", "commentary"))).toBe(12);
+    // A malformed adapter emission has to become a terminal event, not a
+    // TypeError thrown out of push() with the queue half-updated.
+    expect(retainedEventCodeUnits(null as unknown as AdapterEvent)).toBe(0);
+    expect(retainedEventCodeUnits("oops" as unknown as AdapterEvent)).toBe(0);
+    // Nested provider-shaped payload is counted; a cycle terminates.
+    const cyclic: Record<string, unknown> = { owner: "abc" };
+    cyclic.self = cyclic;
+    expect(retainedEventCodeUnits({ type: "done", providerState: cyclic } as unknown as AdapterEvent)).toBe(3);
+  });
+
+  test("both budgets must be positive safe integers", () => {
+    const invalid = [Number.NaN, Number.POSITIVE_INFINITY, 0, -4, 2.5, Number.MAX_SAFE_INTEGER + 1];
+    for (const value of invalid) {
+      expect(() => createAdapterEventQueue({ maxBacklogCodeUnits: value }))
+        .toThrow("maxBacklogCodeUnits must be a positive safe integer");
+      expect(() => createAdapterEventQueue({ maxEventCodeUnits: value }))
+        .toThrow("maxEventCodeUnits must be a positive safe integer");
+    }
+    expect(DEFAULT_MAX_EVENT_CODE_UNITS).toBeLessThan(DEFAULT_MAX_BACKLOG_CODE_UNITS);
+  });
+});
diff --git a/tests/ci-workflows/brand-favicons.test.ts b/tests/ci-workflows/brand-favicons.test.ts
new file mode 100644
index 00000000000..b782975da96
--- /dev/null
+++ b/tests/ci-workflows/brand-favicons.test.ts
@@ -0,0 +1,174 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { inflateSync } from "node:zlib";
+import { join } from "node:path";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * The favicons the dashboard and the documentation site serve are generated from the app icon
+ * vector by scripts/brand-favicons.ts. That script's --check compares byte for byte and needs
+ * rsvg-convert, which CI does not have, so what is asserted here is the shape of the committed
+ * set: the sizes the sites reference, the alpha channel, and the one property the old artwork
+ * failed.
+ *
+ * That property is worth naming. The documentation favicon used to be the dark variant of the
+ * mark — white on transparency — so on a light browser tab strip it was white on white and the
+ * site effectively had no favicon. Nothing about the file looks wrong until it is composited.
+ */
+const GENERATOR = repoPath("scripts/brand-favicons.ts");
+
+function generatorSource(): string {
+  return readFileSync(GENERATOR, "utf8");
+}
+
+function block(source: string, opening: string, closing: string): string {
+  const start = source.indexOf(opening);
+  expect(start, `${opening} is missing from brand-favicons.ts`).toBeGreaterThan(-1);
+  const end = source.indexOf(closing, start + opening.length);
+  expect(end, `${opening} is not terminated in brand-favicons.ts`).toBeGreaterThan(-1);
+  return source.slice(start + opening.length, end);
+}
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/** Truecolour with alpha. */
+const RGBA = 6;
+
+function ihdr(bytes: Buffer): { width: number; height: number; colourType: number } {
+  expect(bytes.subarray(0, 8).equals(PNG_SIGNATURE)).toBe(true);
+  expect(bytes.subarray(12, 16).toString("latin1")).toBe("IHDR");
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20), colourType: bytes[25]! };
+}
+
+/** Decode an 8-bit RGBA PNG into one flat pixel buffer. */
+function decode(bytes: Buffer): { width: number; height: number; pixels: Buffer } {
+  const { width, height, colourType } = ihdr(bytes);
+  expect(colourType).toBe(RGBA);
+  const idat: Buffer[] = [];
+  for (let at = 8; at + 8 <= bytes.length; ) {
+    const length = bytes.readUInt32BE(at);
+    const type = bytes.subarray(at + 4, at + 8).toString("latin1");
+    if (type === "IDAT") idat.push(Buffer.from(bytes.subarray(at + 8, at + 8 + length)));
+    if (type === "IEND") break;
+    at += 12 + length;
+  }
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * 4;
+  const pixels = Buffer.alloc(height * stride);
+  let prior = Buffer.alloc(stride);
+  for (let y = 0; y < height; y += 1) {
+    const start = y * (1 + stride);
+    const filter = raw[start]!;
+    const row = Buffer.from(raw.subarray(start + 1, start + 1 + stride));
+    for (let i = 0; i < stride; i += 1) {
+      const a = i >= 4 ? row[i - 4]! : 0;
+      const b = prior[i]!;
+      const c = i >= 4 ? prior[i - 4]! : 0;
+      let add = 0;
+      if (filter === 1) add = a;
+      else if (filter === 2) add = b;
+      else if (filter === 3) add = (a + b) >> 1;
+      else if (filter === 4) {
+        const guess = a + b - c;
+        const pa = Math.abs(guess - a);
+        const pb = Math.abs(guess - b);
+        const pc = Math.abs(guess - c);
+        add = pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+      }
+      row[i] = (row[i]! + add) & 0xff;
+    }
+    row.copy(pixels, y * stride);
+    prior = row;
+  }
+  return { width, height, pixels };
+}
+
+/** Rec. 709 luminance of the pixel starting at ''at''. */
+function luminance(pixels: Buffer, at: number): number {
+  return 0.2126 * pixels[at]! + 0.7152 * pixels[at + 1]! + 0.0722 * pixels[at + 2]!;
+}
+
+describe("brand favicons", () => {
+  const source = generatorSource();
+  const pngs = new Map<string, number>(
+    [...block(source, "const FAVICON_SIZES: Record<string, number> = {", "};")
+      .matchAll(/"([^"]+)":\s*(\d+)/g)].map(m => [m[1]!, Number(m[2])]),
+  );
+  const icoOutput = /const ICO_OUTPUT = "([^"]+)";/.exec(source)?.[1];
+  const icoSizes = block(source, "const ICO_SIZES = [", "]")
+    .split(",")
+    .map(part => Number(part.trim()))
+    .filter(n => Number.isFinite(n));
+
+  test("the generator still declares the favicons the sites reference", () => {
+    expect(pngs.size).toBeGreaterThan(1);
+    expect(icoOutput).toBeTruthy();
+    expect(icoSizes.length).toBeGreaterThan(2);
+
+    // The sizes are not free choices: these are the numbers the two sites already ask for.
+    expect(readFileSync(repoPath("gui/index.html"), "utf8")).toContain('href="/favicon.png"');
+    const astro = readFileSync(repoPath("docs-site/astro.config.mjs"), "utf8");
+    expect(astro).toContain('favicon: "/favicon.ico"');
+    expect(astro).toContain('sizes: "192x192"');
+    expect(pngs.get("docs-site/public/favicon.png")).toBe(192);
+  });
+
+  test("every declared favicon is committed at its declared size with alpha intact", () => {
+    const wrong: string[] = [];
+    for (const [output, size] of pngs) {
+      const { width, height, colourType } = ihdr(readFileSync(repoPath(output)));
+      if (width !== size || height !== size) wrong.push(`${output}: ${width}x${height} != ${size}`);
+      if (colourType !== RGBA) wrong.push(`${output}: colour type ${colourType}`);
+    }
+    expect(wrong).toEqual([]);
+  });
+
+  test("the documentation .ico carries exactly the declared sizes as PNGs", () => {
+    const ico = readFileSync(repoPath(icoOutput!));
+    expect(ico.readUInt16LE(0)).toBe(0);
+    expect(ico.readUInt16LE(2)).toBe(1);
+    expect(ico.readUInt16LE(4)).toBe(icoSizes.length);
+    const seen: number[] = [];
+    for (let i = 0; i < icoSizes.length; i += 1) {
+      const entry = 6 + i * 16;
+      const length = ico.readUInt32LE(entry + 8);
+      const offset = ico.readUInt32LE(entry + 12);
+      expect(offset + length).toBeLessThanOrEqual(ico.length);
+      const { width, height } = ihdr(ico.subarray(offset, offset + length));
+      expect(width).toBe(height);
+      expect(ico[entry]).toBe(width % 256);
+      seen.push(width);
+    }
+    expect(seen).toEqual(icoSizes);
+  });
+
+  /**
+   * The regression the generator exists for. Both favicons are now drawn on the opaque backdrop
+   * the app icon uses, so they composite against a light tab strip instead of disappearing into
+   * it. The documentation artwork this replaces was white on transparency with a corner alpha of
+   * 3 and no fully opaque pixel anywhere.
+   */
+  test("both favicons show on a light tab instead of vanishing into it", () => {
+    const failures: string[] = [];
+    for (const output of pngs.keys()) {
+      const { width, height, pixels } = decode(readFileSync(repoPath(output)));
+
+      // An opaque light corner is the backdrop rather than transparency.
+      const corner = luminance(pixels, 0);
+      if (pixels[3] !== 255) failures.push(output + ": corner alpha " + pixels[3]);
+      if (corner < 200) failures.push(output + ": corner luminance " + corner.toFixed(0));
+
+      // A backdrop alone is not a favicon. An opaque white square passes the check above and is
+      // still invisible, so the mark has to actually be there: count the pixels that survive
+      // compositing and differ from the backdrop enough to read at tab size.
+      let ink = 0;
+      for (let at = 0; at < pixels.length; at += 4) {
+        if (pixels[at + 3]! < 128) continue;
+        if (Math.abs(luminance(pixels, at) - corner) > 64) ink += 1;
+      }
+      const coverage = ink / (width * height);
+      if (coverage < 0.1) failures.push(output + ": only " + (coverage * 100).toFixed(1) + "% ink");
+    }
+    expect(failures, "these favicons vanish on a light tab strip").toEqual([]);
+  });
+});
diff --git a/tests/ci-workflows/build-desktop-icon-set.test.ts b/tests/ci-workflows/build-desktop-icon-set.test.ts
new file mode 100644
index 00000000000..7af94c1f609
--- /dev/null
+++ b/tests/ci-workflows/build-desktop-icon-set.test.ts
@@ -0,0 +1,251 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * The committed desktop icons are generated from one SVG by `desktop/scripts/generate-icons.ts`.
+ * That script's own `--check` compares byte for byte, which is the strongest statement available
+ * — and it is not available here: it needs `rsvg-convert` and `iconutil`, and the renderer is not
+ * pinned, so two machines with different librsvg builds disagree on bytes without anything being
+ * wrong. Asserting byte identity in CI would mean asserting the runner's renderer version.
+ *
+ * What CI can assert on any platform with no renderer at all is that the committed set still has
+ * the shape the generator declares: every size present, every raster actually that size, both
+ * containers carrying exactly the members the script packs, and nothing hand-added alongside.
+ * Every expectation below is read out of the generator, so adding a size there and forgetting to
+ * regenerate fails here rather than being restated in two places that can drift apart.
+ */
+const GENERATOR = repoPath("desktop/scripts/generate-icons.ts");
+const ICONS_DIR = repoPath("desktop/src-tauri/icons");
+
+function generatorSource(): string {
+  return readFileSync(GENERATOR, "utf8");
+}
+
+function block(source: string, opening: string, closing: string): string {
+  const start = source.indexOf(opening);
+  expect(start, `${opening} is missing from generate-icons.ts`).toBeGreaterThan(-1);
+  const end = source.indexOf(closing, start + opening.length);
+  expect(end, `${opening} is not terminated in generate-icons.ts`).toBeGreaterThan(-1);
+  return source.slice(start + opening.length, end);
+}
+
+function declaredPngs(source: string): Map<string, number> {
+  const body = block(source, "const PNG_SIZES: Record<string, number> = {", "};");
+  const out = new Map<string, number>();
+  for (const m of body.matchAll(/"([^"]+)":\s*(\d+)/g)) out.set(m[1]!, Number(m[2]));
+  return out;
+}
+
+function declaredIcnsMembers(source: string): Array<{ name: string; size: number }> {
+  const body = block(source, "const ICNS_ENTRIES: Array<{ name: string; size: number }> = [", "];");
+  return [...body.matchAll(/name:\s*"([^"]+)",\s*size:\s*(\d+)/g)].map(m => ({ name: m[1]!, size: Number(m[2]) }));
+}
+
+function declaredIcoSizes(source: string): number[] {
+  const body = block(source, "const ICO_SIZES = [", "]");
+  return body.split(",").map(part => Number(part.trim())).filter(n => Number.isFinite(n));
+}
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/** Truecolour with alpha, the only colour type a Tauri window icon is allowed to be. */
+const RGBA = 6;
+
+function isPng(bytes: Buffer): boolean {
+  return bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE);
+}
+
+/** Width and height out of a PNG's IHDR, which is always the first chunk. */
+function pngDimensions(bytes: Buffer): { width: number; height: number } {
+  expect(isPng(bytes)).toBe(true);
+  expect(bytes.subarray(12, 16).toString("latin1")).toBe("IHDR");
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+
+describe("desktop icon set", () => {
+  const source = generatorSource();
+  const pngs = declaredPngs(source);
+  const icnsMembers = declaredIcnsMembers(source);
+  const icoSizes = declaredIcoSizes(source);
+
+  test("the generator still declares a set worth checking", () => {
+    expect(pngs.size).toBeGreaterThan(10);
+    expect(icnsMembers.length).toBeGreaterThan(5);
+    expect(icoSizes.length).toBeGreaterThan(3);
+  });
+
+  test("every declared raster is committed at exactly its declared size", () => {
+    const wrong: string[] = [];
+    for (const [name, size] of pngs) {
+      const bytes = readFileSync(join(ICONS_DIR, name));
+      const { width, height } = pngDimensions(bytes);
+      if (width !== size || height !== size) wrong.push(`${name}: ${width}x${height} != ${size}`);
+    }
+    expect(wrong).toEqual([]);
+  });
+
+  /**
+   * The backdrop is opaque, and librsvg drops the alpha channel when nothing in a render is
+   * transparent. That is a valid PNG and a broken icon: `tauri::generate_context!` refuses a
+   * window icon that is not RGBA, so the desktop app stops compiling with "icon ... is not RGBA"
+   * — a failure that only a real bundle build reaches. The generator re-encodes, and this is what
+   * notices if that ever stops happening.
+   */
+  test("every committed raster keeps the alpha channel Tauri requires", () => {
+    const names = [...pngs.keys(), join("tray", "icon.png")];
+    const flat = names.filter(name => readFileSync(join(ICONS_DIR, name))[25] !== RGBA);
+    expect(flat, "these rasters lost their alpha channel").toEqual([]);
+  });
+
+  test("icon.ico carries exactly the sizes the generator packs, each a real PNG of that size", () => {
+    const ico = readFileSync(join(ICONS_DIR, "icon.ico"));
+    expect(ico.readUInt16LE(0)).toBe(0);
+    expect(ico.readUInt16LE(2)).toBe(1);
+    expect(ico.readUInt16LE(4)).toBe(icoSizes.length);
+
+    const seen: number[] = [];
+    for (let i = 0; i < icoSizes.length; i += 1) {
+      const at = 6 + i * 16;
+      const declared = icoSizes[i]!;
+      // ICO spells 256 as 0 in a single byte, which is the one field width the format never grew.
+      expect(ico.readUInt8(at)).toBe(declared >= 256 ? 0 : declared);
+      expect(ico.readUInt8(at + 1)).toBe(declared >= 256 ? 0 : declared);
+      const length = ico.readUInt32LE(at + 8);
+      const offset = ico.readUInt32LE(at + 12);
+      expect(offset + length).toBeLessThanOrEqual(ico.length);
+      const { width, height } = pngDimensions(ico.subarray(offset, offset + length));
+      expect(width).toBe(declared);
+      expect(height).toBe(declared);
+      seen.push(width);
+    }
+    expect(seen).toEqual(icoSizes);
+  });
+
+  test("icon.icns is well formed and its members are the declared sizes", () => {
+    const icns = readFileSync(join(ICONS_DIR, "icon.icns"));
+    expect(icns.subarray(0, 4).toString("latin1")).toBe("icns");
+    // A truncated or concatenated icns still opens with the magic; the declared length is what
+    // says the file is the one the tool wrote.
+    expect(icns.readUInt32BE(4)).toBe(icns.length);
+
+    const types: string[] = [];
+    const payloads: Buffer[] = [];
+    let at = 8;
+    while (at < icns.length) {
+      const type = icns.subarray(at, at + 4).toString("latin1");
+      const length = icns.readUInt32BE(at + 4);
+      expect(length).toBeGreaterThanOrEqual(8);
+      expect(at + length).toBeLessThanOrEqual(icns.length);
+      types.push(type);
+      payloads.push(icns.subarray(at + 8, at + length));
+      at += length;
+    }
+    // The walk has to land exactly on the end, or some member lied about its length.
+    expect(at).toBe(icns.length);
+    // 'TOC ' and 'info' are bookkeeping the tool adds; the rest are the images.
+    const images = payloads.filter((_, i) => types[i] !== "TOC " && types[i] !== "info");
+    expect(images.length).toBe(icnsMembers.length);
+
+    // Counting members is not enough: ten duplicates of one size would count the same as the ten
+    // the generator declares. The larger members are PNG and carry their dimensions, so read them
+    // and check they are sizes the generator actually asks for. The smallest two are ARGB, which
+    // has no dimension in its payload, so they are counted rather than measured - and that
+    // accounting is what bounds how many declared sizes may be absent from the PNG members.
+    const png = images.filter(isPng);
+    const argb = images.filter(payload => payload.subarray(0, 4).toString("latin1") === "ARGB");
+    expect(png.length + argb.length).toBe(images.length);
+
+    // Consume the declared sizes one member at a time rather than comparing sets. A set would
+    // accept ten copies of one declared size; matching multiplicities is what makes a duplicated
+    // or substituted member fail, which is the realistic way this file goes wrong.
+    const unaccounted = icnsMembers.map(member => member.size);
+    for (const payload of png) {
+      const { width, height } = pngDimensions(payload);
+      expect(width).toBe(height);
+      const at = unaccounted.indexOf(width);
+      expect(at, `icon.icns carries more ${width}px members than the generator declares`).toBeGreaterThan(-1);
+      unaccounted.splice(at, 1);
+    }
+    // Whatever is left has to be exactly the members ARGB carries, which store no dimension.
+    expect(unaccounted.length).toBe(argb.length);
+  });
+
+  test("nothing is hand-added beside the generated set", () => {
+    const generated = new Set([...pngs.keys(), "icon.ico", "icon.icns", "icon.svg"]);
+    const stray = readdirSync(ICONS_DIR)
+      .filter(name => statSync(join(ICONS_DIR, name)).isFile())
+      .filter(name => !generated.has(name))
+      .sort();
+    expect(stray).toEqual([]);
+  });
+
+  test("the menu bar image is the size the generator declares", () => {
+    const source = generatorSource();
+    const output = /const TRAY_OUTPUT = "([^"]+)";/.exec(source)?.[1];
+    const size = Number(/const TRAY_SIZE = (\d+);/.exec(source)?.[1]);
+    expect(output, "TRAY_OUTPUT is missing from generate-icons.ts").toBeTruthy();
+    expect(Number.isFinite(size) && size > 0).toBe(true);
+
+    // Declaring the constants is not the same as rendering them. Without these two the tray could
+    // be dropped from the run and from `--check` while every assertion below still read the stale
+    // committed file and passed.
+    expect(source, "generate-icons.ts declares TRAY_OUTPUT but never renders it")
+      .toContain("render(TRAY_SIZE, join(target, TRAY_OUTPUT), traySource);");
+    expect(source, "the tray output is rendered but never reported, so --check skips it")
+      .toContain("produced.push(TRAY_OUTPUT);");
+
+    const bytes = readFileSync(join(ICONS_DIR, output!));
+    expect(isPng(bytes)).toBe(true);
+    expect(pngDimensions(bytes)).toEqual({ width: size, height: size });
+  });
+
+  /**
+   * The menu bar asset has its own SVG because a template image carries no backdrop, not because
+   * it is a second drawing. Two files holding the same curves is exactly the drift the generator
+   * was written to remove, so the curves in the smaller one have to be characters out of the
+   * larger one — a redrawn brace would stop matching here rather than ship as a second mark.
+   *
+   * Subset alone is too weak to hold the asset up, because every way of breaking it removes
+   * something. Dropping the mask, deleting the underscore, or repeating one brace in place of the
+   * cloud all produce a strict subset, and all three ship a black blob into the menu bar. So the
+   * glyph geometry is compared whole, the mask has to be wired onto the mark, and the mark paths
+   * have to be distinct from each other.
+   */
+  test("the menu bar source is a subset of the app icon source", () => {
+    const icon = readFileSync(join(ICONS_DIR, "icon.svg"), "utf8");
+    const tray = readFileSync(join(ICONS_DIR, "tray", "icon.svg"), "utf8");
+
+    // The glyphs are the whole point of the mark, so they are compared as a block rather than as
+    // a bag of paths: an identical mask carries the chevron, the underscore and the white ground
+    // that turns them into holes.
+    const iconMask = block(icon, '<mask id="prompt"', "</mask>");
+    const trayMask = block(tray, '<mask id="prompt"', "</mask>");
+    expect(trayMask, "the tray mask is not the app icon's mask").toBe(iconMask);
+    expect(trayMask).toContain('stroke-width="22"');
+    expect(trayMask).toContain("<rect ");
+
+    // A mark that does not reference the mask renders as a filled blob with no prompt in it.
+    const iconMark = block(icon, '<g id="mark"', "</g>");
+    const trayMark = block(tray, '<g id="mark"', "</g>");
+    for (const [name, mark] of [["icon.svg", iconMark], ["tray/icon.svg", trayMark]] as const) {
+      expect(mark, `${name} draws the mark without the prompt cut`).toContain('mask="url(#prompt)"');
+    }
+
+    const trayPaths = [...trayMark.matchAll(/ d="([^"]+)"/g)].map(m => m[1]!);
+    const iconPaths = [...iconMark.matchAll(/ d="([^"]+)"/g)].map(m => m[1]!);
+    expect(new Set(trayPaths).size, "tray/icon.svg repeats a curve instead of drawing the mark")
+      .toBe(trayPaths.length);
+    expect(trayPaths.length, "the menu bar mark is the cloud and both braces").toBeGreaterThanOrEqual(3);
+    expect(iconPaths.length).toBeGreaterThan(trayPaths.length);
+    const foreign = trayPaths.filter(d => !iconPaths.includes(d));
+    expect(foreign, "tray/icon.svg draws curves icon.svg does not have").toEqual([]);
+
+    // A status item is tinted from its alpha, so anything but black-and-clear is a mistake, and a
+    // backdrop would paint the whole menu bar slot.
+    expect(tray).not.toContain('id="backdrop"');
+    const fills = new Set([...tray.matchAll(/fill="([^"]+)"/g)].map(m => m[1]!));
+    expect([...fills].sort()).toEqual(["#000000", "#ffffff", "none"]);
+  });
+});
diff --git a/tests/ci-workflows/ci-structure-gate.test.ts b/tests/ci-workflows/ci-structure-gate.test.ts
index b6f21009092..5081034b851 100644
--- a/tests/ci-workflows/ci-structure-gate.test.ts
+++ b/tests/ci-workflows/ci-structure-gate.test.ts
@@ -67,8 +67,18 @@ test("the aggregate gate expects the job instead of ignoring it", () => {
   // job missing from `expected_for` reads as `undeclared`, not as skipped.
   const gate = workflow.jobs?.ci;
   expect(Array.isArray(gate?.needs) ? gate?.needs : []).toContain("structure-gate");
+  expect(Array.isArray(gate?.needs) ? gate?.needs : []).toContain("widget");
   const script = (gate?.steps ?? []).map(step => step.run ?? "").join("\n");
   expect(script).toContain("structure-gate) echo \"$structure\" ;;");
-  expect(script).toContain("GATED_JOBS=\"$GATED_JOBS structure-gate\"");
+  expect(script).toContain("GATED_JOBS=\"$GATED_JOBS structure-gate widget\"");
+  expect(script).toContain("|widget)");
   expect(script).toContain("CHANGES_STRUCTURE");
 });
+
+test("app changes select the macOS widget job", () => {
+  expect(filters.ci).toContain("app/**");
+  expect(filters.ci).toContain("desktop/**");
+  const widget = workflow.jobs?.widget;
+  expect(widget?.if).toContain("needs.changes.outputs.ci == 'true'");
+  expect(Array.isArray(widget?.needs) ? widget?.needs : []).toContain("changes");
+});
diff --git a/tests/ci-workflows/ci-workflows.test.ts b/tests/ci-workflows/ci-workflows.test.ts
index 22b02edb141..fba748aec7d 100644
--- a/tests/ci-workflows/ci-workflows.test.ts
+++ b/tests/ci-workflows/ci-workflows.test.ts
@@ -495,10 +495,12 @@ describe("GitHub Actions hardening", () => {
       "Dockerfile",
       "LICENSE",
       "README.md",
+      "app/**",
       "assets/**",
       "bin/**",
       "bun.lock",
       "compose.yaml",
+      "desktop/**",
       "docker/**",
       "gui/**",
       "package.json",
@@ -826,7 +828,7 @@ describe("GitHub Actions hardening", () => {
         };
         publish?: {
           "runs-on"?: string;
-          needs?: string;
+          needs?: string[];
           permissions?: Record<string, string>;
         };
       };
@@ -841,7 +843,10 @@ describe("GitHub Actions hardening", () => {
       contents: "read",
     });
     
-    expect(release.jobs?.publish?.needs).toBe("validate-dispatch");
+    // Publication is the irreversible public act, so it waits for the pre-publication
+    // verification of everything it will publish; the full ordering contract is in
+    // tests/ci-workflows/release-pipeline-contract.test.ts.
+    expect(release.jobs?.publish?.needs).toEqual(["validate-dispatch", "verify-release"]);
     expect(release.jobs?.publish?.["runs-on"]).toBe("ubuntu-latest");
     expect(release.jobs?.publish?.permissions).toEqual({
       contents: "write",
@@ -916,9 +921,15 @@ describe("GitHub Actions hardening", () => {
 
     // Workflow-dispatch inputs must reach shell code via env, never by direct
     // interpolation into run: source (script-injection hardening).
+    // The split alone does not bound a block: the last step of a job runs on into the next
+    // job's header, so a job-level `if: ${{ inputs.dry-run != true }}` — which is a condition,
+    // not shell — read as an injection in the step above it. Each block is cut at the first
+    // line that dedents to job level, which is where the step's script actually ends.
     const runBlocks = workflow.split(/\n {6,}- name: /).filter(block => block.includes("run: |"));
     for (const block of runBlocks) {
-      const runSource = block.slice(block.indexOf("run: |"));
+      const afterRun = block.slice(block.indexOf("run: |"));
+      const jobBoundary = afterRun.search(/\n {2}\S/);
+      const runSource = jobBoundary === -1 ? afterRun : afterRun.slice(0, jobBoundary);
       expect(runSource).not.toContain("${{ inputs.");
     }
 
@@ -5573,8 +5584,10 @@ test.skipIf(process.platform === "win32")("release shell recovers only unverifie
       const script = prelude + (scenario.mode === "missing-receipt" ? "" : publish) + '\n'
         + (scenario.dry ? "" : `PUBLISHED=$(sed -n 's/^published=//p' "$GITHUB_OUTPUT")\n${smoke}`);
       const child = Bun.spawn(["bash", "--noprofile", "--norc", "-e", "-o", "pipefail", "-c", script], {
+        // RESUME mirrors the workflow, where the env always defines it; the
+        // non-resume branches are what every scenario here exercises.
         env: { ...process.env, SCENARIO: scenario.mode, DRY_RUN: String(scenario.dry),
-          NPM_DIST_TAG: "latest", RELEASE_VERSION: "9.8.7", GITHUB_OUTPUT: output,
+          NPM_DIST_TAG: "latest", RELEASE_VERSION: "9.8.7", RESUME: "false", GITHUB_OUTPUT: output,
           GITHUB_STEP_SUMMARY: summary, CALLS: calls, COUNTER: join(dir, "counter") },
         stdin: "ignore", stdout: "pipe", stderr: "pipe",
       });
diff --git a/tests/ci-workflows/cold-spawn-warmup.test.ts b/tests/ci-workflows/cold-spawn-warmup.test.ts
index 7e969d8cf2a..29e86fdc944 100644
--- a/tests/ci-workflows/cold-spawn-warmup.test.ts
+++ b/tests/ci-workflows/cold-spawn-warmup.test.ts
@@ -78,6 +78,14 @@ const DISPOSITIONS: Readonly<Record<string, Disposition>> = {
     warmed: true,
     why: "the first resetAt iteration loads src/codex/quota.ts and src/codex/main-account-cache.ts",
   },
+  "tests/codex-integration/codex-shim-ensure-failure.test.ts": {
+    warmed: false,
+    why:
+      "Its children are two throwaway /bin/sh scripts standing in for ensure and for the real Codex "
+      + "launcher, so the cold cost is shell and process startup rather than a repository module "
+      + "graph, and an import scan has nothing to warm. The generated shim never loads a repository "
+      + "module in the child: the point of the file is what the shell does with an exit status.",
+  },
   "tests/codex-integration/codex-shim.test.ts": {
     warmed: false,
     why:
diff --git a/tests/ci-workflows/docs-developer-role-policy.test.ts b/tests/ci-workflows/docs-developer-role-policy.test.ts
new file mode 100644
index 00000000000..1ac65bce687
--- /dev/null
+++ b/tests/ci-workflows/docs-developer-role-policy.test.ts
@@ -0,0 +1,152 @@
+/**
+ * INV-CHAT-01. One developer-role policy for the translated Chat wire and the documents about it.
+ *
+ * Three statements were live at once. `structure/providers/chat-compat.md` said `developer` was
+ * forwarded as itself on every destination, the configuration reference said an unset setting
+ * sends `system`, and the adapter implemented only one of them. Each reads as plausible on its
+ * own, so whoever edited this area next could pick any of the three and reintroduce the defect
+ * the setting exists to prevent — which is how the previous regression arrived.
+ *
+ * The sentence under test is built here from the role `createOpenAIChatAdapter` actually
+ * serializes for each of the three states, so it cannot be held correct by review alone: a
+ * changed default fails this file rather than leaving one document behind. The translated pages
+ * are compared against the English source instead of carrying a second copy of the rule, because
+ * that comparison stays meaningful when the English wording is revised.
+ *
+ * Placement — that the message never leaves the slot it arrived in, whichever role it carries —
+ * is a separate property and stays where it is already tested, in
+ * `tests/adapters/openai/openai-chat-developer-position.test.ts`.
+ */
+import { describe, expect, test } from "bun:test";
+import { createOpenAIChatAdapter } from "../../src/adapters/openai-chat";
+import type { OcxParsedRequest, OcxProviderConfig } from "../../src/types";
+import { repoPath } from "../helpers/repo-root";
+
+const INSTRUCTION = "Answer in exactly one sentence.";
+
+/** The role the Chat wire gives a mid-conversation developer message for one setting state. */
+function wireRole(declared: boolean | undefined): string {
+  const provider: OcxProviderConfig = {
+    adapter: "openai-chat",
+    baseUrl: "https://gateway.example.internal/v1",
+    apiKey: "k",
+    ...(declared === undefined ? {} : { foldDeveloperRoleToSystem: declared }),
+  };
+  const parsed = {
+    modelId: "local-model",
+    context: {
+      systemPrompt: ["base instructions"],
+      messages: [
+        { role: "user", content: "First turn.", timestamp: 0 },
+        { role: "developer", content: INSTRUCTION, timestamp: 0 },
+        { role: "user", content: "Second turn.", timestamp: 0 },
+      ],
+    },
+    stream: false,
+    options: {},
+  } as unknown as OcxParsedRequest;
+  const body = JSON.parse(createOpenAIChatAdapter(provider).buildRequest(parsed).body) as {
+    messages: Array<{ role: string; content: unknown }>;
+  };
+  const carried = body.messages.find(message => message.content === INSTRUCTION);
+  expect(carried, "the instruction left the wire; this check has no role to read").toBeDefined();
+  return String(carried!.role);
+}
+
+const UNSET = wireRole(undefined);
+const DECLARED_REJECTS = wireRole(true);
+const DECLARED_ACCEPTS = wireRole(false);
+
+/** The one sentence both English documents must carry, derived rather than transcribed. */
+const POLICY =
+  "`foldDeveloperRoleToSystem` unset sends `" +
+  UNSET +
+  "`, `true` sends `" +
+  DECLARED_REJECTS +
+  "`, and `false` sends `" +
+  DECLARED_ACCEPTS +
+  "`.";
+
+const STRUCTURE_DOC = "structure/providers/chat-compat.md";
+const ENGLISH_REFERENCE = "docs-site/src/content/docs/reference/configuration/providers.md";
+const ENGLISH_GUIDE = "docs-site/src/content/docs/guides/claude-code.md";
+const LOCALES = ["fr", "ja", "ko", "ru", "tr", "zh-cn", "zh-tw"] as const;
+
+const referencePage = (locale: string): string =>
+  "docs-site/src/content/docs/" + locale + "/reference/configuration/providers.md";
+const guidePage = (locale: string): string =>
+  "docs-site/src/content/docs/" + locale + "/guides/claude-code.md";
+
+async function read(path: string): Promise<string> {
+  return await Bun.file(repoPath(path)).text();
+}
+
+/** Line wrapping differs between a prose paragraph and a table cell; the sentence does not. */
+const flatten = (text: string): string => text.replace(/\s+/g, " ");
+
+/** The bare role names a passage carries as code spans, in order. */
+function roleSpans(passage: string): string[] {
+  return [...passage.matchAll(/`([^`]+)`/g)]
+    .map(match => match[1]!)
+    .filter(span => span === "system" || span === "developer");
+}
+
+async function referenceRow(path: string): Promise<string> {
+  const rows = (await read(path))
+    .split("\n")
+    .filter(line => line.includes("`foldDeveloperRoleToSystem?`"));
+  expect(rows.length, path + " has no foldDeveloperRoleToSystem row; re-anchor this check").toBe(1);
+  return rows[0]!;
+}
+
+async function guideParagraph(path: string): Promise<string> {
+  const paragraphs = (await read(path))
+    .split(/\n\s*\n/)
+    .filter(block => block.includes("foldDeveloperRoleToSystem"));
+  expect(paragraphs.length, path + " has no foldDeveloperRoleToSystem paragraph; re-anchor this check").toBe(1);
+  return paragraphs[0]!;
+}
+
+describe("the documented developer-role policy is derived from the Chat wire", () => {
+  test("the three states still describe a real choice", () => {
+    for (const role of [UNSET, DECLARED_REJECTS, DECLARED_ACCEPTS]) {
+      expect(["system", "developer"]).toContain(role);
+    }
+    // All three collapsing to one role would make every assertion below vacuous while the
+    // documents kept explaining a setting that no longer decides anything.
+    expect(new Set([UNSET, DECLARED_REJECTS, DECLARED_ACCEPTS]).size).toBe(2);
+  });
+
+  test("the structure contract states the mapping the adapter implements", async () => {
+    expect(flatten(await read(STRUCTURE_DOC))).toContain(POLICY);
+  });
+
+  test("the configuration reference states the same mapping", async () => {
+    expect(flatten(await referenceRow(ENGLISH_REFERENCE))).toContain(POLICY);
+  });
+
+  test("the Claude Code guide names the same default and the same accepted role", async () => {
+    const paragraph = flatten(await guideParagraph(ENGLISH_GUIDE));
+    expect(paragraph).toContain("sent as `" + UNSET + "` unless");
+    expect(paragraph).toContain("accepts the `" + DECLARED_ACCEPTS + "` role");
+  });
+});
+
+describe("translated pages do not contradict the English source", () => {
+  test("the English pages carry roles worth comparing", async () => {
+    expect(roleSpans(await referenceRow(ENGLISH_REFERENCE)).length).toBeGreaterThan(0);
+    expect(roleSpans(await guideParagraph(ENGLISH_GUIDE)).length).toBeGreaterThan(0);
+  });
+
+  for (const locale of LOCALES) {
+    test(locale + " states the roles in the order the English reference does", async () => {
+      const english = roleSpans(await referenceRow(ENGLISH_REFERENCE));
+      expect(roleSpans(await referenceRow(referencePage(locale)))).toEqual(english);
+    });
+
+    test(locale + " Claude Code guide states the roles the English guide does", async () => {
+      const english = roleSpans(await guideParagraph(ENGLISH_GUIDE));
+      expect(roleSpans(await guideParagraph(guidePage(locale)))).toEqual(english);
+    });
+  }
+});
diff --git a/tests/ci-workflows/docs-provider-discovery-limits.test.ts b/tests/ci-workflows/docs-provider-discovery-limits.test.ts
new file mode 100644
index 00000000000..ab160372431
--- /dev/null
+++ b/tests/ci-workflows/docs-provider-discovery-limits.test.ts
@@ -0,0 +1,134 @@
+/**
+ * The fixed-host discovery limits in the provider guides must be read back from the registry.
+ *
+ * #5198 corrected a preset count that had drifted across sixteen files, and the interesting part
+ * was how long it survived: nothing compared any copy to the registry, so CI stayed green the
+ * whole time. The per-provider discovery limits are the same shape one layer down -- a byte
+ * ceiling and a row ceiling, restated by hand in eight pages, checked by nobody (#5215).
+ *
+ * Every number here is derived from PROVIDER_REGISTRY, so lowering a ceiling fails in every
+ * locale at once instead of leaving seven translations describing the old one.
+ *
+ * Sections are located by the brand name and the presence of a unit token, not by a translated
+ * sentence. A restated anchor phrase is the same hand-copied value this test exists to remove,
+ * and the brand names are Latin in all eight published locales. A page where the section is
+ * missing or appears twice fails by name and asks to be re-anchored; that is how the Korean
+ * guide's absent Featherless section was found.
+ */
+import { describe, expect, test } from "bun:test";
+import { PROVIDER_REGISTRY } from "../../src/providers/registry";
+import { repoPath } from "../helpers/repo-root";
+
+/** English plus every translated guide that ships, matching docs-site/astro.config.mjs. */
+const GUIDES = [
+  { locale: "en", path: "docs-site/src/content/docs/guides/providers.md" },
+  { locale: "fr", path: "docs-site/src/content/docs/fr/guides/providers.md" },
+  { locale: "ja", path: "docs-site/src/content/docs/ja/guides/providers.md" },
+  { locale: "ko", path: "docs-site/src/content/docs/ko/guides/providers.md" },
+  { locale: "ru", path: "docs-site/src/content/docs/ru/guides/providers.md" },
+  { locale: "tr", path: "docs-site/src/content/docs/tr/guides/providers.md" },
+  { locale: "zh-cn", path: "docs-site/src/content/docs/zh-cn/guides/providers.md" },
+  { locale: "zh-tw", path: "docs-site/src/content/docs/zh-tw/guides/providers.md" },
+] as const;
+
+/**
+ * One documented section per entry. `ids` holds every registry preset the section speaks for;
+ * a grouped section must agree in the registry before one sentence can describe both.
+ */
+const SECTIONS = [
+  { brand: "Chutes", ids: ["chutes"] },
+  { brand: "DeepInfra", ids: ["deepinfra"] },
+  { brand: "Hyperbolic", ids: ["hyperbolic"] },
+  { brand: "Nscale", ids: ["nscale", "vultr"] },
+  { brand: "Command Code", ids: ["command-code", "commandcode"] },
+  { brand: "SambaNova", ids: ["sambanova"] },
+  { brand: "Nebius", ids: ["nebius"] },
+  { brand: "Crusoe", ids: ["crusoe"] },
+  { brand: "DigitalOcean", ids: ["digitalocean"] },
+  { brand: "Scaleway", ids: ["scaleway"] },
+  { brand: "Featherless", ids: ["featherless"] },
+  { brand: "Novita", ids: ["novita"] },
+  { brand: "Baseten", ids: ["baseten"] },
+] as const;
+
+const UNIT_TOKEN = /(\d+(?:[.,]\d+)?)\s*(KiB|MiB)/g;
+
+interface Limits { bytes: number; rows: number }
+
+function registryLimits(id: string): Limits {
+  const entry = PROVIDER_REGISTRY.find(row => row.id === id);
+  expect(entry, `no registry preset with id "${id}"; re-anchor this check`).toBeDefined();
+  const discovery = entry!.modelDiscovery;
+  expect(discovery, `preset "${id}" declares no modelDiscovery`).toBeDefined();
+  const { maxResponseBytes, maxModels } = discovery!;
+  expect(typeof maxResponseBytes, `preset "${id}" declares no maxResponseBytes`).toBe("number");
+  expect(typeof maxModels, `preset "${id}" declares no maxModels`).toBe("number");
+  return { bytes: maxResponseBytes!, rows: maxModels! };
+}
+
+/** The documented spelling of a byte ceiling: whole MiB where it divides, otherwise KiB. */
+function unitLabel(bytes: number): string {
+  const MIB = 1024 * 1024;
+  return bytes % MIB === 0 ? `${bytes / MIB} MiB` : `${bytes / 1024} KiB`;
+}
+
+/** The paragraph that states this section's limits, located by brand plus a unit token. */
+async function limitParagraph(path: string, brand: string): Promise<string> {
+  const source = await Bun.file(repoPath(path)).text();
+  const paragraphs = source.split(/\n\s*\n/).filter(block => {
+    UNIT_TOKEN.lastIndex = 0;
+    return block.includes(brand) && UNIT_TOKEN.test(block);
+  });
+  expect(
+    paragraphs.length,
+    `${path} should state the ${brand} discovery limits in exactly one paragraph; found ${paragraphs.length}`,
+  ).toBe(1);
+  return paragraphs[0]!;
+}
+
+function unitTokens(paragraph: string): string[] {
+  UNIT_TOKEN.lastIndex = 0;
+  return [...paragraph.matchAll(UNIT_TOKEN)].map(match => `${match[1]} ${match[2]}`);
+}
+
+/** Every standalone integer left once the byte ceilings are removed. */
+function rowNumbers(paragraph: string): number[] {
+  UNIT_TOKEN.lastIndex = 0;
+  const withoutUnits = paragraph.replace(UNIT_TOKEN, " ");
+  return [...withoutUnits.matchAll(/(?<![\d.,])(\d+)(?![\d.,])/g)].map(match => Number(match[1]));
+}
+
+describe("documented provider discovery limits match the registry", () => {
+  test("the registry is the only source of the numbers under test", () => {
+    expect(SECTIONS.length).toBeGreaterThan(0);
+    for (const section of SECTIONS) {
+      const limits = section.ids.map(registryLimits);
+      expect(limits[0]!.bytes, `${section.brand} byte ceiling`).toBeGreaterThan(0);
+      expect(limits[0]!.rows, `${section.brand} row ceiling`).toBeGreaterThan(0);
+      // A grouped section states one pair for several presets. If they ever diverge, the
+      // sentence is wrong for one of them and the group has to be split, not re-measured.
+      for (const other of limits.slice(1)) {
+        expect(other, `${section.ids.join(" and ")} must declare the same discovery limits`)
+          .toEqual(limits[0]!);
+      }
+    }
+  });
+
+  for (const guide of GUIDES) {
+    for (const section of SECTIONS) {
+      const { bytes, rows } = registryLimits(section.ids[0]!);
+      test(`${guide.locale} guide states ${unitLabel(bytes)} and ${rows} rows for ${section.brand}`, async () => {
+        const paragraph = await limitParagraph(guide.path, section.brand);
+        // An exact token set, not a substring: a stale ceiling left beside the current one
+        // would otherwise pass while still telling the reader the wrong number.
+        expect(unitTokens(paragraph), `${guide.path} ${section.brand} byte ceiling`)
+          .toEqual([unitLabel(bytes)]);
+        // Read the row ceiling from the prose with the unit tokens removed. Left in, the byte
+        // ceiling's own digits satisfy the check: a Hyperbolic paragraph saying "256 KiB and
+        // 128 raw rows" would pass an expected 256 rows on the strength of the byte number.
+        expect(rowNumbers(paragraph), `${guide.path} ${section.brand} row ceiling`)
+          .toContain(rows);
+      });
+    }
+  }
+});
diff --git a/tests/ci-workflows/installed-gate-drivers.test.ts b/tests/ci-workflows/installed-gate-drivers.test.ts
new file mode 100644
index 00000000000..21c7039caf9
--- /dev/null
+++ b/tests/ci-workflows/installed-gate-drivers.test.ts
@@ -0,0 +1,552 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import {
+  compareSemver,
+  describeGatePhases,
+  evaluateOwnership,
+  npmPackageSpec,
+  observeOwnership,
+  parseGateArguments,
+  parsePidList,
+  readOwnPackageName,
+  runGate,
+  summarizeReport,
+  type GateDeps,
+  type GateOptions,
+  type GateReport,
+} from "../../desktop/scripts/installed-gate";
+import {
+  linuxAdapter,
+  macosAdapter,
+  windowsAdapter,
+  type ProcessEvidence,
+} from "../../desktop/scripts/installed-gate-platforms";
+import { repoPath } from "../helpers/repo-root";
+
+const okRunner = {
+  run: async (): Promise<ProcessEvidence> => ({ ok: true, exitCode: 0, stdout: "", stderr: "" }),
+  mkdir: () => {},
+  fileExists: () => false,
+  homeDir: () => "/fake-home",
+};
+
+function baseArgv(): string[] {
+  return [
+    "--platform", "macos",
+    "--format", "dmg",
+    "--artifact", "gate/OpenCodex-2.62.0-macos.dmg",
+    "--work-dir", "gate/work",
+    "--to-version", "2.62.0",
+    "--report", "gate/report.json",
+  ];
+}
+
+describe("installed-gate argument parsing", () => {
+  test("accepts a complete macOS invocation", () => {
+    const parsed = parseGateArguments(baseArgv());
+    expect(parsed.error).toBeUndefined();
+    expect(parsed.options?.platform).toBe("macos");
+    expect(parsed.options?.takeoverTimeoutMs).toBe(180_000);
+  });
+
+  test("lists every missing required argument", () => {
+    const parsed = parseGateArguments([]);
+    expect(parsed.error).toContain("--platform");
+    expect(parsed.error).toContain("--report");
+  });
+
+  test("rejects a format that does not belong to the platform", () => {
+    const parsed = parseGateArguments(baseArgv().map(a => a === "dmg" ? "deb" : a));
+    expect(parsed.error).toContain("not a macos artifact format");
+  });
+
+  test("rejects an unknown platform", () => {
+    const parsed = parseGateArguments(baseArgv().map(a => a === "macos" ? "freebsd" : a));
+    expect(parsed.error).toContain("--platform must be");
+  });
+
+  test("R3: linux runs without an older artifact are rejected, update verification is not optional", () => {
+    const linux = baseArgv().map(a => (a === "macos" ? "linux" : a === "dmg" ? "deb" : a));
+    expect(parseGateArguments(linux).error).toContain("--older-artifact");
+    const linuxWithArtifact = [...linux, "--older-artifact", "gate/older.deb"];
+    expect(parseGateArguments(linuxWithArtifact).error).toContain("--from-version");
+    expect(parseGateArguments([...linuxWithArtifact, "--from-version", "2.61.0"]).options).toBeDefined();
+  });
+
+  test("the older artifact must actually be older", () => {
+    const linux = [
+      ...baseArgv().map(a => (a === "macos" ? "linux" : a === "dmg" ? "deb" : a)),
+      "--older-artifact", "gate/older.deb",
+    ];
+    expect(parseGateArguments([...linux, "--from-version", "2.62.0"]).error).toContain("differ");
+    expect(parseGateArguments([...linux, "--from-version", "2.63.0"]).error).toContain("strictly older");
+    expect(parseGateArguments([...linux, "--from-version", "2.62.0-rc.1"]).options).toBeDefined();
+  });
+
+  test("compareSemver orders numeric triples and prerelease suffixes", () => {
+    expect(compareSemver("2.61.0", "2.62.0")).toBeLessThan(0);
+    expect(compareSemver("2.62.0", "2.61.0")).toBeGreaterThan(0);
+    expect(compareSemver("2.62.0-rc.1", "2.62.0")).toBeLessThan(0);
+    expect(compareSemver("2.62.0", "2.62.0")).toBe(0);
+  });
+
+  test("rejects a non-positive takeover timeout", () => {
+    expect(parseGateArguments([...baseArgv(), "--takeover-timeout", "0"]).error).toContain("--takeover-timeout");
+    expect(parseGateArguments([...baseArgv(), "--takeover-timeout", "45"]).options?.takeoverTimeoutMs).toBe(45_000);
+  });
+
+  test("hooks are file names inside --hooks-dir, never command text or paths", () => {
+    expect(parseGateArguments([...baseArgv(), "--consent-hook", "answer-consent"]).error)
+      .toContain("--hooks-dir");
+    const withDir = [...baseArgv(), "--hooks-dir", "gate/hooks"];
+    expect(parseGateArguments([...withDir, "--consent-hook", "answer-consent"]).options?.consentHook).toBe("answer-consent");
+    expect(parseGateArguments([...withDir, "--consent-hook", "../escape"]).error).toContain("plain file name");
+    expect(parseGateArguments([...withDir, "--tray-quit-hook", "a/b"]).error).toContain("plain file name");
+    expect(parseGateArguments([...withDir, "--tray-quit-hook", "rm -rf /"]).error).toContain("plain file name");
+  });
+
+  test("the npm package spec is derived from the repository, never taken as an argument", () => {
+    expect(npmPackageSpec("@example/opencodex", "2.61.0")).toBe("@example/opencodex@2.61.0");
+    expect(readOwnPackageName('{"name":"@bitkyc08/opencodex"}')).toBe("@bitkyc08/opencodex");
+    expect(readOwnPackageName("not json")).toBeUndefined();
+  });
+
+  test("version inputs are strict semver, never npm package grammar", () => {
+    // `opencodex@${input}` with an alias payload would install an arbitrary package.
+    expect(parseGateArguments(baseArgv().map(a => a === "2.62.0" ? "npm:evil@latest" : a)).error).toContain("strict semver");
+    const linux = baseArgv().map(a => (a === "macos" ? "linux" : a === "dmg" ? "deb" : a));
+    const linuxBase = [...linux, "--older-artifact", "gate/older.deb"];
+    expect(parseGateArguments(linuxBase).error).toContain("--from-version");
+    expect(parseGateArguments([...linuxBase, "--from-version", "2.62.0"]).error).toContain("differ");
+    expect(parseGateArguments([...linuxBase, "--from-version", "2.61.0"]).options?.fromVersion).toBe("2.61.0");
+  });
+});
+
+describe("installed-gate pid parsing", () => {
+  test("empty probe output is no pids, never pid 0", () => {
+    expect(parsePidList("")).toEqual([]);
+    expect(parsePidList("\n\n")).toEqual([]);
+  });
+
+  test("only positive safe integers survive", () => {
+    expect(parsePidList("123\n456\n")).toEqual([123, 456]);
+    expect(parsePidList(" 42 \n0\n-7\nabc\n")).toEqual([42]);
+  });
+});
+
+describe("installed-gate ownership contract", () => {
+  test("reads the lane C schema: record root carries an ownership object", () => {
+    const observed = observeOwnership({ ownership: { installId: "install-1", consentGeneration: 3 } });
+    expect(observed.ownerInstallId).toBe("install-1");
+    expect(observed.consentGeneration).toBe(3);
+  });
+
+  test("does not guess at other shapes — an unknown schema is no observation", () => {
+    expect(observeOwnership({ owner: { installId: "x" } }).ownerInstallId).toBeUndefined();
+    expect(observeOwnership({ installId: "x", consentGeneration: 1 }).consentGeneration).toBeUndefined();
+    expect(observeOwnership("not-an-object").ownerInstallId).toBeUndefined();
+  });
+
+  test("accepts exactly one consent-generation increment with a recorded owner", () => {
+    // The takeover precondition is an UNOWNED staged runtime: a pre-existing owner
+    // means the observation is not the takeover this gate exists to prove.
+    const before = observeOwnership({});
+    const after = observeOwnership({ ownership: { installId: "install-1", consentGeneration: 1 } });
+    expect(evaluateOwnership(before, after).ok).toBe(true);
+  });
+
+  test("rejects a takeover from an already-owned runtime", () => {
+    const before = observeOwnership({ ownership: { installId: "other", consentGeneration: 0 } });
+    const after = observeOwnership({ ownership: { installId: "install-1", consentGeneration: 1 } });
+    const verdict = evaluateOwnership(before, after);
+    expect(verdict.ok).toBe(false);
+    expect(verdict.detail).toContain("unowned");
+  });
+
+  test("rejects a takeover that recorded no owner", () => {
+    const before = observeOwnership({});
+    const after = observeOwnership({ ownership: { consentGeneration: 1 } });
+    const verdict = evaluateOwnership(before, after);
+    expect(verdict.ok).toBe(false);
+    expect(verdict.detail).toContain("install id");
+  });
+
+  test("rejects more than one consent-generation increment", () => {
+    const before = observeOwnership({ ownership: { consentGeneration: 0 } });
+    const after = observeOwnership({ ownership: { installId: "i", consentGeneration: 2 } });
+    expect(evaluateOwnership(before, after).ok).toBe(false);
+  });
+
+  test("treats a missing generation after consent as a failure, never as zero", () => {
+    const before = observeOwnership({ ownership: { consentGeneration: 0 } });
+    const after = observeOwnership({ ownership: { installId: "i" } });
+    expect(evaluateOwnership(before, after).ok).toBe(false);
+  });
+});
+
+describe("installed-gate phase plan and report", () => {
+  const optionsFor = (platform: GateOptions["platform"]): GateOptions => ({
+    platform,
+    format: platform === "linux" ? "deb" : platform === "windows" ? "msi" : "dmg",
+    artifact: "a",
+    olderArtifact: "b",
+    workDir: "w",
+    toVersion: "2.62.0",
+    fromVersion: "2.61.0",
+    reportPath: "r.json",
+    takeoverTimeoutMs: 1000,
+  });
+
+  test("linux gates carry the update phase before cleanup", () => {
+    const phases = describeGatePhases(optionsFor("linux"));
+    expect(phases).toContain("update-verify");
+    expect(phases.indexOf("update-verify")).toBe(phases.length - 2);
+    expect(phases.at(-1)).toBe("cleanup");
+  });
+
+  test("macOS and Windows gates stop after the drain contract", () => {
+    expect(describeGatePhases(optionsFor("macos"))).not.toContain("update-verify");
+    expect(describeGatePhases(optionsFor("windows"))).not.toContain("update-verify");
+  });
+
+  test("every gate opens with the isolation preflight", () => {
+    for (const platform of ["macos", "windows", "linux"] as const) {
+      expect(describeGatePhases(optionsFor(platform))[0]).toBe("preflight-isolation");
+      expect(describeGatePhases(optionsFor(platform))[1]).toBe("runner-readiness");
+    }
+  });
+
+  test("a full quit and cold relaunch replaces the single-instance observation", () => {
+    for (const platform of ["macos", "windows", "linux"] as const) {
+      const phases = describeGatePhases(optionsFor(platform));
+      expect(phases).toContain("relaunch-consent");
+      expect(phases).not.toContain("second-launch-consent");
+    }
+  });
+
+  test("the report is red when any phase fails, and summarizes in report order", () => {
+    const report: GateReport = {
+      platform: "macos",
+      format: "dmg",
+      toVersion: "2.62.0",
+      startedAt: "2026-09-21T00:00:00.000Z",
+      phases: [
+        { phase: "stage-npm-runtime", status: "pass", detail: "ok", evidence: {} },
+        { phase: "install-artifact", status: "fail", detail: "broken", evidence: {} },
+      ],
+    };
+    const summary = summarizeReport(report);
+    expect(summary).toContain("FAIL  install-artifact — broken");
+    expect(summary.startsWith("installed-artifact gate:")).toBe(true);
+  });
+});
+
+describe("the refusal path is mutation-free (P0)", () => {
+  const optionsFor = (platform: GateOptions["platform"]): GateOptions => ({
+    platform,
+    format: platform === "linux" ? "deb" : platform === "windows" ? "msi" : "dmg",
+    artifact: "a",
+    olderArtifact: "b",
+    workDir: "w",
+    toVersion: "2.62.0",
+    fromVersion: "2.61.0",
+    reportPath: "r.json",
+    takeoverTimeoutMs: 1000,
+  });
+
+  test("a run refused for existing state makes zero mutating calls, cleanup included", async () => {
+    const calls: string[] = [];
+    const killed: number[] = [];
+    const written: string[] = [];
+    const directories: string[] = [];
+    const deps: GateDeps = {
+      // Every command answers "absent" except the default-home state file, which
+      // fileExists reports as present — the refusal trigger.
+      run: async spec => {
+        calls.push([spec.file, ...spec.args].join(" "));
+        return { ok: false, exitCode: 1, stdout: "", stderr: "" };
+      },
+      pidAlive: () => false,
+      killProcess: pid => killed.push(pid),
+      fileExists: path => path.endsWith(".opencodex/service-state.json"),
+      readJsonFile: () => undefined,
+      writeTextFile: path => { written.push(path); },
+      makeDir: path => { directories.push(path); },
+      fetchJson: async () => ({ ok: false, status: 0, body: undefined }),
+      spawnLogged: () => { throw new Error("refusal must never spawn"); },
+      serveMockProvider: () => { throw new Error("refusal must never serve the mock"); },
+      digestFile: () => null,
+      homeDir: () => "/fake-home",
+      sleep: () => Promise.resolve(),
+      readTextFile: () => "{}",
+    };
+
+    const report = await runGate(optionsFor("macos"), deps);
+
+    expect(report.ok).toBe(false);
+    expect(report.phases[0]?.phase).toBe("preflight-isolation");
+    expect(report.phases[0]?.status).toBe("fail");
+    // Only read-only probes may have run: the registration probes, the default-state
+    // file check and the app process probe. Nothing that installs, uninstalls, kills,
+    // writes outside the report, or registers a service.
+    const allowedProbeBinaries = new Set(["launchctl", "pgrep"]);
+    for (const call of calls) {
+      const binary = call.split(" ")[0]!;
+      expect(allowedProbeBinaries.has(binary), `mutating call reached on refusal: ${call}`).toBe(true);
+    }
+    expect(killed).toEqual([]);
+    expect(written).toEqual(["r.json"]);
+    // Even the gate's own scratch dirs are created only after the preflight passes.
+    expect(directories).toEqual([]);
+    // And the refusal was the reason: no other phase ran.
+    expect(report.phases.map(phase => phase.phase)).toEqual(["preflight-isolation", "cleanup"]);
+  });
+});
+
+describe("installed-gate platform adapters", () => {
+  test("every adapter declares its external commands", () => {
+    for (const adapter of [macosAdapter(okRunner), windowsAdapter(okRunner), linuxAdapter(okRunner)]) {
+      expect(adapter.dependencies().length).toBeGreaterThan(0);
+      for (const dependency of adapter.dependencies()) {
+        // Command names resolve through PATH; a few system tools are invoked by their
+        // absolute path (PlistBuddy) and are declared that way.
+        expect(dependency).toMatch(/^([a-z0-9.-]+|\/[a-zA-Z0-9._/-]+)$/);
+      }
+    }
+  });
+
+  test("dependency lists enumerate exactly what the adapters shell out to", () => {
+    expect(new Set(macosAdapter(okRunner).dependencies())).toEqual(
+      new Set(["hdiutil", "osascript", "pgrep", "launchctl", "cp", "rm", "/usr/libexec/PlistBuddy"]),
+    );
+    expect(new Set(windowsAdapter(okRunner).dependencies())).toEqual(
+      new Set(["msiexec", "powershell", "schtasks", "sc"]),
+    );
+    expect(new Set(linuxAdapter(okRunner).dependencies())).toEqual(
+      new Set(["dpkg", "dpkg-deb", "dpkg-query", "xdotool", "pgrep", "systemctl", "sudo", "cp", "chmod", "kill", "rm"]),
+    );
+  });
+
+  test("registration evidence covers the manager AND the on-disk artifact", () => {
+    expect(macosAdapter(okRunner).registrationFiles()).toEqual(["Library/LaunchAgents/com.opencodex.proxy.plist"]);
+    expect(linuxAdapter(okRunner).registrationFiles()).toEqual([".config/systemd/user/opencodex-proxy.service"]);
+  });
+
+  test("the npm launcher is resolved inside the staged prefix, never PATH", () => {
+    expect(macosAdapter(okRunner).npmLauncher("/prefix")).toBe("/prefix/node_modules/.bin/ocx");
+    expect(linuxAdapter(okRunner).npmLauncher("/prefix")).toBe("/prefix/node_modules/.bin/ocx");
+    expect(windowsAdapter(okRunner).npmLauncher("C:\\prefix")).toBe("C:\\prefix\\node_modules\\.bin\\ocx.cmd");
+  });
+
+  test("registration state is tri-state: present, absent, and unknown refuse differently", async () => {
+    const scriptRunner = (responses: Array<{ ok: boolean; stdout?: string; stderr?: string }>) => {
+      const queue = [...responses];
+      return {
+        run: async (): Promise<ProcessEvidence> => {
+          const next = queue.shift() ?? { ok: false };
+          return { ok: next.ok, exitCode: next.ok ? 0 : 1, stdout: next.stdout ?? "", stderr: next.stderr ?? "" };
+        },
+        mkdir: () => {},
+        fileExists: () => false,
+        homeDir: () => "/fake-home",
+      };
+    };
+    // A clean "could not find" is absence...
+    expect(await macosAdapter(scriptRunner([{ ok: false, stderr: "Could not find service \"com.opencodex.proxy\"" }])).registrationState()).toBe("absent");
+    // ...a manager error is unknown, and unknown must never authorize mutation.
+    expect(await macosAdapter(scriptRunner([{ ok: false, stderr: "Bootstrap failed: 5: Input/output error" }])).registrationState()).toBe("unknown");
+    // A disabled systemd unit EXISTS — is-enabled exits 1 with "disabled".
+    expect(await linuxAdapter(scriptRunner([{ ok: false, stdout: "disabled" }])).registrationState()).toBe("present");
+    expect(await linuxAdapter(scriptRunner([{ ok: false, stderr: "Failed to get unit file state: No such file or directory" }, { ok: false, stderr: "could not be found" }])).registrationState()).toBe("absent");
+    // Windows probes both the task and the native WinSW service.
+    const windowsCalls: string[] = [];
+    const windowsRunner = {
+      run: async (spec: { file: string; args: string[] }): Promise<ProcessEvidence> => {
+        windowsCalls.push([spec.file, ...spec.args].join(" "));
+        // Each manager reports absence in its own words.
+        const stderr = spec.file === "sc.exe"
+          ? "[SC] OpenService FAILED 1060: The specified service does not exist as an installed service."
+          : "ERROR: The system cannot find the file specified.";
+        return { ok: false, exitCode: 1, stdout: "", stderr };
+      },
+      mkdir: () => {},
+      fileExists: () => false,
+      homeDir: () => "/fake-home",
+    };
+    expect(await windowsAdapter(windowsRunner).registrationState()).toBe("absent");
+    expect(windowsCalls.some(call => call.includes("opencodex-proxy-native"))).toBe(true);
+    expect(windowsCalls.some(call => call.includes("opencodex-proxy"))).toBe(true);
+  });
+
+  test("Windows and Linux tray automation is operator-supplied, never guessed", () => {
+    expect(windowsAdapter(okRunner).trayQuit()).toBeNull();
+    expect(linuxAdapter(okRunner).trayQuit()).toBeNull();
+    expect(macosAdapter(okRunner).trayQuit()).not.toBeNull();
+  });
+
+  test("macOS tray actions are scoped to the OpenCodex process, not a global index", () => {
+    const quit = macosAdapter(okRunner).trayQuit();
+    expect(quit?.args.join(" ")).toContain('process "OpenCodex"');
+  });
+
+  test("every adapter can probe window visibility after a gesture", () => {
+    expect(macosAdapter(okRunner).windowVisible().file).toBe("osascript");
+    expect(windowsAdapter(okRunner).windowVisible().file).toBe("powershell");
+    expect(linuxAdapter(okRunner).windowVisible().file).toBe("xdotool");
+  });
+
+  test("elevation cancellation is scoped to sighted pids", () => {
+    expect(linuxAdapter(okRunner).cancelElevation([])).toBeNull();
+    const cancel = linuxAdapter(okRunner).cancelElevation([111, 222]);
+    expect(cancel?.file).toBe("kill");
+    expect(cancel?.args).toEqual(["111", "222"]);
+  });
+
+  test("elevation monitoring watches pkexec AND the plugin's zenity/kdialog fallbacks", () => {
+    // The pinned updater falls back pkexec -> zenity/kdialog -> sudo after a cancel;
+    // a gate that watches only pkexec would call a retry "cancelled".
+    const probe = linuxAdapter(okRunner).elevationProbe();
+    expect(probe?.args.join(" ")).toContain("pkexec");
+    expect(probe?.args.join(" ")).toContain("zenity");
+    expect(probe?.args.join(" ")).toContain("kdialog");
+    expect(macosAdapter(okRunner).elevationProbe()).toBeNull();
+  });
+
+  test("the deb version probe exists; AppImage updates are proven by digest instead", () => {
+    expect(linuxAdapter(okRunner).installedVersion("deb", "opencodex-desktop")?.file).toBe("dpkg-query");
+    expect(linuxAdapter(okRunner).installedVersion("appimage")).toBeNull();
+  });
+
+  test("process probes come from the adapter, so the engine stays platform-neutral", () => {
+    expect(macosAdapter(okRunner).appNameProbe().file).toBe("pgrep");
+    expect(windowsAdapter(okRunner).appNameProbe().file).toBe("powershell");
+    // Scoped probes bind to THIS install's path, so cleanup can never match a process
+    // from a different installation.
+    expect(linuxAdapter(okRunner).appProcessProbe("/gate/work/apps").args).toContain("/gate/work/apps");
+    expect(linuxAdapter(okRunner).childPids(42).args).toContain("42");
+  });
+});
+
+describe("installed-gate sources carry no operator detail", () => {
+  const sources = [
+    readFileSync(repoPath("desktop", "scripts", "installed-gate.ts"), "utf8"),
+    readFileSync(repoPath("desktop", "scripts", "installed-gate-platforms.ts"), "utf8"),
+  ];
+
+  test("no absolute user paths, host names or addresses appear in the drivers", () => {
+    for (const source of sources) {
+      expect(source).not.toMatch(/\/Users\/\w/);
+      expect(source).not.toMatch(/C:\\Users/);
+      // Loopback is the proxy's own listener, not operator detail; everything else is.
+      expect(source).not.toMatch(/\b(?!127\.)\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/);
+      expect(source).not.toMatch(/\b\w+\.local\b/);
+    }
+  });
+});
+
+describe("installed-artifact gate workflow", () => {
+  const text = readFileSync(repoPath(".github", "workflows", "desktop-installed-gate.yml"), "utf8");
+  const workflow = Bun.YAML.parse(text) as {
+    on?: Record<string, unknown> | string[];
+    permissions?: Record<string, string>;
+    jobs?: Record<string, {
+      "runs-on"?: string | string[];
+      "timeout-minutes"?: number;
+      steps?: Array<{ name?: string; uses?: string; run?: string; if?: string }>;
+    }>;
+  };
+  const jobs = workflow.jobs ?? {};
+  type Job = NonNullable<typeof jobs>[string] & {
+    environment?: string;
+    steps?: Array<{ name?: string; uses?: string; run?: string; if?: string; with?: Record<string, unknown> }>;
+  };
+
+  test("it is dispatch-only: a stateful GUI machine must never run because a push happened", () => {
+    const triggers = Array.isArray(workflow.on) ? workflow.on : Object.keys(workflow.on ?? {});
+    expect(triggers).toEqual(["workflow_dispatch"]);
+  });
+
+  test("least privilege: read-only contents and nothing else", () => {
+    expect(workflow.permissions).toEqual({ contents: "read" });
+  });
+
+  test("every platform job targets a self-hosted gate runner with a bounded timeout", () => {
+    const gateJobs = Object.entries(jobs).filter(([name]) => name !== "report");
+    expect(gateJobs.map(([name]) => name)).toEqual(["macos", "windows", "linux"]);
+    for (const [, job] of gateJobs) {
+      const runsOn = Array.isArray(job["runs-on"]) ? job["runs-on"] : [job["runs-on"]];
+      expect(runsOn).toContain("self-hosted");
+      expect(runsOn?.some(label => typeof label === "string" && label.startsWith("opencodex-gate-"))).toBe(true);
+      expect(job["timeout-minutes"]).toBeGreaterThanOrEqual(30);
+      expect(job["timeout-minutes"]).toBeLessThanOrEqual(120);
+    }
+  });
+
+  test("the gate report is uploaded even when the gate failed", () => {
+    for (const [name, job] of Object.entries(jobs)) {
+      const uploads = (job.steps ?? []).filter(step => step.uses?.startsWith("actions/upload-artifact@"));
+      expect(uploads.length, `${name} must upload its report`).toBe(1);
+      expect(uploads[0]?.if).toContain("always()");
+    }
+  });
+
+  test("all actions are pinned to full commit SHAs", () => {
+    // Parse every uses: value rather than pattern-matching a few known-bad refs:
+    // a short SHA or an arbitrary branch name is not an immutable pin either.
+    const usesValues: string[] = [];
+    for (const job of Object.values(jobs)) {
+      for (const step of job.steps ?? []) {
+        if (step.uses) usesValues.push(step.uses);
+      }
+    }
+    expect(usesValues.length).toBeGreaterThan(0);
+    for (const uses of usesValues) {
+      const isLocal = uses.startsWith("./");
+      const pinnedSha = /^[^@]+@([0-9a-f]{40})$/.exec(uses);
+      expect(isLocal || pinnedSha !== null, `${uses} must be a local action or a full-SHA pin`).toBe(true);
+    }
+  });
+
+  test("GUI automation inputs are hook names, never command text", () => {
+    const dispatch = (workflow.on as Record<string, { inputs?: Record<string, unknown> }>).workflow_dispatch;
+    const inputNames = Object.keys(dispatch?.inputs ?? {});
+    expect(inputNames).toContain("consent-hook");
+    expect(inputNames).toContain("tray-quit-hook");
+    expect(inputNames).toContain("elevate-accept-hook");
+    for (const name of inputNames) {
+      expect(name).not.toMatch(/command$/);
+    }
+  });
+
+  test("the npm package is never constructed from raw input", () => {
+    // The driver derives the spec from the repository's own package.json; a workflow
+    // that interpolates a package name would reopen npm alias injection.
+    expect(text).not.toContain("--npm-package");
+  });
+
+  test("every gate job sits behind a required-review environment and checks out protected dev", () => {
+    // The runners install software and hold sudo; the workflow must never execute a
+    // dispatcher-selected ref on them.
+    for (const [name, job] of Object.entries(jobs) as Array<[string, Job]>) {
+      expect(job.environment, `${name} must declare the gated environment`).toBe("opencodex-desktop-gate");
+      const checkout = (job.steps ?? []).find(step => step.uses?.startsWith("actions/checkout@"));
+      expect(checkout?.with?.ref, `${name} must check out the protected integration branch`).toBe("dev");
+    }
+  });
+
+  test("dispatch inputs reach shell code through env, never by interpolation", () => {
+    for (const job of Object.values(jobs)) {
+      for (const step of job.steps ?? []) {
+        if (typeof step.run === "string") {
+          expect(step.run).not.toContain("${{ inputs.");
+          expect(step.run).not.toContain("${{ github.event.inputs.");
+        }
+      }
+    }
+  });
+
+  test("linux runs both update formats through the gate", () => {
+    const linux = jobs.linux as { strategy?: { matrix?: { format?: string[] } } } | undefined;
+    expect(linux?.strategy?.matrix?.format).toEqual(["deb", "appimage"]);
+  });
+});
diff --git a/tests/ci-workflows/privacy-scan-asset-names.test.ts b/tests/ci-workflows/privacy-scan-asset-names.test.ts
new file mode 100644
index 00000000000..3dc98fd40b3
--- /dev/null
+++ b/tests/ci-workflows/privacy-scan-asset-names.test.ts
@@ -0,0 +1,45 @@
+/**
+ * The scanner's address pattern reads a Retina asset name as an email.
+ *
+ * `128x128@2x.png` is local part `128x128`, domain `2x`, and the deliberately loose TLD rule
+ * accepts `png`, so listing the desktop icon set failed the gate. The exemption that fixes it is
+ * one character away from a hole: a person's name in front of the same `@2x.png` suffix has the
+ * identical shape and is a mailbox, so the rule is written against the asset-name grammar — a
+ * pixel dimension, optionally prefixed the way an iconset member is — rather than against the
+ * shape.
+ *
+ * This exercises the real `scanText`. A test that restated the regex would keep passing after the
+ * exemption was widened, which is the only way this can go wrong.
+ */
+import { describe, expect, test } from "bun:test";
+import { scanText } from "../../scripts/privacy-scan";
+
+/** Assembled at runtime so this file carries no bare address of its own. */
+const mailbox = (local: string, domain: string): string => [local, domain].join("@");
+
+describe("privacy scan: Retina asset names", () => {
+  test("the icon set the generator declares does not read as addresses", () => {
+    for (const name of ["128x128@2x.png", "icon_16x16@2x.png", "icon_512x512@2x.png"]) {
+      expect(scanText("desktop/scripts/generate-icons.ts", `"${name}": 256,`)
+        .filter(finding => finding.kind === "email")).toEqual([]);
+    }
+  });
+
+  test("a mailbox wearing the same suffix is still a finding", () => {
+    for (const local of ["alice", "j.doe", "support"]) {
+      const line = `contact ${mailbox(local, "2x.png")}`;
+      expect(scanText("src/example.ts", line).some(finding => finding.kind === "email")).toBe(true);
+    }
+  });
+
+  test("the exemption does not extend past the scale suffix and a raster extension", () => {
+    const cases = [
+      mailbox("128x128", "2x.com"),
+      mailbox("128x128", "4x.png"),
+      mailbox("128x128", "2x.example.com"),
+    ];
+    for (const line of cases) {
+      expect(scanText("src/example.ts", line).some(finding => finding.kind === "email")).toBe(true);
+    }
+  });
+});
diff --git a/tests/ci-workflows/release-desktop-scripts.test.ts b/tests/ci-workflows/release-desktop-scripts.test.ts
new file mode 100644
index 00000000000..60c51e2cd30
--- /dev/null
+++ b/tests/ci-workflows/release-desktop-scripts.test.ts
@@ -0,0 +1,684 @@
+import { describe, expect, test } from "bun:test";
+import { createHash, generateKeyPairSync, sign as ed25519Sign } from "node:crypto";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { bundlesByTarget, collectReleaseAssets } from "../../desktop/scripts/collect-release-assets";
+import {
+  runBuildLocal,
+  summarizeAttempts,
+  type ArtifactEntry,
+  type BuildLocalDeps,
+} from "../../desktop/scripts/build-local";
+import { buildUpdaterManifest, platformFiles, writeUpdaterManifest } from "../../desktop/scripts/updater-manifest";
+import { standaloneArchiveName, standaloneTargets } from "../../scripts/standalone-targets";
+import {
+  expectedReleaseAssets,
+  parseMinisignPublicKey,
+  releaseMatrixTargets,
+  verifyChecksums,
+  verifyReleaseAssets,
+  verifyUpdaterSignature,
+} from "../../desktop/scripts/verify-release-assets";
+import { repoPath } from "../helpers/repo-root";
+
+function temporaryDirectory(): string {
+  return mkdtempSync(join(tmpdir(), "opencodex-release-"));
+}
+
+describe("desktop release scripts", () => {
+  test("renames macOS DMG and updater archive and copies signatures", () => {
+    const root = temporaryDirectory();
+    try {
+      const bundleRoot = join(
+        root,
+        "desktop",
+        "src-tauri",
+        "target",
+        "aarch64-apple-darwin",
+        "release",
+        "bundle",
+      );
+      const dmg = join(bundleRoot, "dmg");
+      const macos = join(bundleRoot, "macos");
+      mkdirSync(dmg, { recursive: true });
+      mkdirSync(macos, { recursive: true });
+      writeFileSync(join(dmg, "OpenCodex_2.61.0_aarch64.dmg"), "dmg");
+      writeFileSync(join(macos, "OpenCodex.app.tar.gz"), "archive");
+      writeFileSync(join(macos, "OpenCodex.app.tar.gz.sig"), "archive-signature");
+
+      const out = join(root, "release");
+      const files = collectReleaseAssets({
+        version: "2.61.0",
+        target: "aarch64-apple-darwin",
+        out,
+        repoRoot: root,
+      });
+
+      // The paths come back from `join`, so on Windows they are separated by backslashes and a
+      // "/" split returns the whole path. Asking the platform for the last segment keeps this
+      // assertion about the asset names it is written to check.
+      expect(files.map(path => basename(path))).toEqual([
+        "OpenCodex-2.61.0-macos.dmg",
+        "OpenCodex-2.61.0-macos.dmg.sha256",
+        "OpenCodex-2.61.0-macos.app.tar.gz",
+        "OpenCodex-2.61.0-macos.app.tar.gz.sig",
+        "OpenCodex-2.61.0-macos.app.tar.gz.sha256",
+      ]);
+      expect(readFileSync(join(out, "OpenCodex-2.61.0-macos.app.tar.gz.sha256"), "utf8")).toMatch(
+        /^[0-9a-f]{64}  OpenCodex-2\.61\.0-macos\.app\.tar\.gz\n$/,
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("renames desktop bundles and writes checksums", () => {
+    const root = temporaryDirectory();
+    try {
+      const bundle = join(
+        root,
+        "desktop",
+        "src-tauri",
+        "target",
+        "x86_64-pc-windows-msvc",
+        "release",
+        "bundle",
+        "msi",
+      );
+      mkdirSync(bundle, { recursive: true });
+      writeFileSync(join(bundle, "OpenCodex_2.61.0_x64_en-US.msi"), "bundle");
+      writeFileSync(join(bundle, "OpenCodex_2.61.0_x64_en-US.msi.sig"), "signed");
+
+      const out = join(root, "release");
+      const files = collectReleaseAssets({
+        version: "2.61.0",
+        target: "x86_64-pc-windows-msvc",
+        out,
+        repoRoot: root,
+      });
+
+      expect(files.map(path => basename(path))).toEqual([
+        "OpenCodex-2.61.0-windows-x64.msi",
+        "OpenCodex-2.61.0-windows-x64.msi.sig",
+        "OpenCodex-2.61.0-windows-x64.msi.sha256",
+      ]);
+      expect(readFileSync(join(out, "OpenCodex-2.61.0-windows-x64.msi.sha256"), "utf8")).toMatch(
+        /^[0-9a-f]{64}  OpenCodex-2\.61\.0-windows-x64\.msi\n$/,
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects ambiguous bundle matches", () => {
+    const root = temporaryDirectory();
+    try {
+      const bundleRoot = join(
+        root,
+        "desktop",
+        "src-tauri",
+        "target",
+        "aarch64-apple-darwin",
+        "release",
+        "bundle",
+      );
+      const dmg = join(bundleRoot, "dmg");
+      const macos = join(bundleRoot, "macos");
+      mkdirSync(dmg, { recursive: true });
+      mkdirSync(macos, { recursive: true });
+      writeFileSync(join(dmg, "OpenCodex_2.61.0_aarch64.dmg"), "dmg");
+      writeFileSync(join(dmg, "OpenCodex_2.61.0_universal.dmg"), "dmg");
+      writeFileSync(join(macos, "OpenCodex.app.tar.gz"), "archive");
+
+      expect(() =>
+        collectReleaseAssets({
+          version: "2.61.0",
+          target: "aarch64-apple-darwin",
+          out: join(root, "release"),
+          repoRoot: root,
+        }),
+      ).toThrow(/Multiple dmg bundles found/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("generates signed updater platforms and skips missing signatures", () => {
+    const root = temporaryDirectory();
+    try {
+      writeFileSync(join(root, "OpenCodex-2.61.0-macos.app.tar.gz.sig"), "mac-signature\n");
+      writeFileSync(join(root, "OpenCodex-2.61.0-windows-x64.msi.sig"), "win-signature\n");
+      writeFileSync(join(root, "OpenCodex-2.61.0-linux-x86_64.AppImage.sig"), "appimage-signature\n");
+      const warnings: string[] = [];
+      const manifest = buildUpdaterManifest({
+        version: "2.61.0",
+        dir: root,
+        repo: "lidge-jun/opencodex",
+        out: join(root, "latest.json"),
+        warn: message => warnings.push(message),
+      });
+
+      expect(manifest.platforms).toEqual({
+        "darwin-aarch64": {
+          signature: "mac-signature",
+          url: "https://github.com/lidge-jun/opencodex/releases/download/v2.61.0/OpenCodex-2.61.0-macos.app.tar.gz",
+        },
+        "darwin-x86_64": {
+          signature: "mac-signature",
+          url: "https://github.com/lidge-jun/opencodex/releases/download/v2.61.0/OpenCodex-2.61.0-macos.app.tar.gz",
+        },
+        "windows-x86_64": {
+          signature: "win-signature",
+          url: "https://github.com/lidge-jun/opencodex/releases/download/v2.61.0/OpenCodex-2.61.0-windows-x64.msi",
+        },
+        // The AppImage keeps the plugin's default Linux key so already-released AppImage
+        // installs keep resolving their updates; deb installs select the explicit key.
+        "linux-x86_64": {
+          signature: "appimage-signature",
+          url: "https://github.com/lidge-jun/opencodex/releases/download/v2.61.0/OpenCodex-2.61.0-linux-x86_64.AppImage",
+        },
+      });
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0]).toContain("linux-x86_64-deb");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("does not write a manifest when no signed updater platforms remain", () => {
+    const root = temporaryDirectory();
+    try {
+      const out = join(root, "latest.json");
+      expect(() =>
+        writeUpdaterManifest({
+          version: "2.61.0",
+          dir: root,
+          repo: "lidge-jun/opencodex",
+          out,
+        }),
+      ).toThrow("No signed updater platforms");
+      expect(existsSync(out)).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("requires every updater platform signature when requested", () => {
+    const root = temporaryDirectory();
+    try {
+      writeFileSync(join(root, "OpenCodex-2.61.0-macos.app.tar.gz.sig"), "mac-signature\n");
+      writeFileSync(join(root, "OpenCodex-2.61.0-windows-x64.msi.sig"), "win-signature\n");
+      writeFileSync(join(root, "OpenCodex-2.61.0-linux-x86_64.AppImage.sig"), "appimage-signature\n");
+
+      expect(() =>
+        buildUpdaterManifest({
+          version: "2.61.0",
+          dir: root,
+          repo: "lidge-jun/opencodex",
+          out: join(root, "latest.json"),
+          requireAll: true,
+        }),
+      ).toThrow("Missing signed updater platforms: linux-x86_64-deb");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+/**
+ * The widget extension is the one piece of the macOS app that the Tauri bundler copies but
+ * never signs: `copy_custom_files_to_bundle` places `macOS.files` into the bundle and does not
+ * add them to `sign_paths`, so whatever signature `build-widget.sh` leaves is the signature
+ * that ships. That signature was ad-hoc, because the release step that builds the widget
+ * carried no signing environment at all while the very next step did. macOS does not register
+ * an extension signed that way, so the app would have installed with no widget and nothing in
+ * the build would have said so.
+ */
+describe("local bundle builds", () => {
+  type Script = Record<string, number | null>;
+  const depsFor = (
+    scripted: Script,
+    opts: { platform?: string; initialArtifacts?: ArtifactEntry[]; argv?: string[] } = {},
+  ) => {
+    const calls: string[][] = [];
+    const logs: string[] = [];
+    const errors: string[] = [];
+    const artifacts = (opts.initialArtifacts ?? []).map(entry => ({ ...entry }));
+    const deps: BuildLocalDeps = {
+      spawn: args => {
+        calls.push(args);
+        const format = args[args.indexOf("--bundles") + 1]!;
+        const verbose = args.includes("--verbose");
+        const key = verbose ? `${format}#v` : format;
+        const status = Object.hasOwn(scripted, key) ? scripted[key]! : 0;
+        // A successful non-verbose build refreshes the artifact, like the real bundler.
+        if (status === 0 && !verbose) {
+          const existing = artifacts.find(entry => entry.path.includes(format));
+          if (existing) existing.mtimeMs += 1;
+          else artifacts.push({ path: `/out/OpenCodex-test_${format}`, mtimeMs: 200 });
+        }
+        return { status };
+      },
+      log: line => { logs.push(line); },
+      error: line => { errors.push(line); },
+      listArtifacts: () => artifacts.map(entry => ({ ...entry })),
+      argv: opts.argv ?? [],
+      platform: opts.platform ?? "linux",
+    };
+    return { calls, logs, errors, deps };
+  };
+
+  test("a failing format does not destroy the formats that build", () => {
+    // Observed on a real GNOME desktop (120_install_verification.md): one shared
+    // invocation died on the AppImage and the deb was never attempted.
+    const { calls, logs, deps } = depsFor({ appimage: 1, deb: 0 });
+    expect(runBuildLocal(deps)).toBe(1);
+    const formats = calls.map(args => args[args.indexOf("--bundles") + 1]);
+    expect(formats).toContain("appimage");
+    expect(formats).toContain("deb");
+    expect(logs.some(line => line.includes("appimage: FAILED"))).toBe(true);
+    expect(logs.some(line => line.includes("deb: ok"))).toBe(true);
+    expect(logs.some(line => line.includes("/out/OpenCodex-test_deb"))).toBe(true);
+    expect(logs.some(line => line.includes("updater artifacts skipped"))).toBe(false);
+  });
+
+  test("a failing format is retried verbosely so the bundler's own stderr surfaces", () => {
+    const { calls, errors, deps } = depsFor({ appimage: 1, deb: 0 });
+    runBuildLocal(deps);
+    expect(errors.some(line => line.includes("rerunning with --verbose"))).toBe(true);
+    const verboseCalls = calls.filter(args => args.includes("--verbose"));
+    expect(verboseCalls).toHaveLength(1);
+    expect(verboseCalls[0]?.slice(0, 3)).toEqual(["tauri", "--verbose", "build"]);
+    expect(verboseCalls[0]).toContain("appimage");
+    expect(verboseCalls.some(args => args.includes("deb"))).toBe(false);
+  });
+
+  test("a verbose retry that succeeds does not change the recorded failure", () => {
+    const { logs, deps } = depsFor({ appimage: 1, "appimage#v": 0, deb: 0 });
+    expect(runBuildLocal(deps)).toBe(1);
+    expect(logs.some(line => line.includes("appimage: FAILED"))).toBe(true);
+  });
+
+  test("stale bundle output is not reported as this run's artifact", () => {
+    const { logs, deps } = depsFor(
+      { appimage: 1, deb: 0 },
+      { initialArtifacts: [{ path: "/out/OpenCodex-test_appimage", mtimeMs: 100 }] },
+    );
+    runBuildLocal(deps);
+    expect(logs.some(line => line.includes("/out/OpenCodex-test_appimage"))).toBe(false);
+    expect(logs.some(line => line.includes("/out/OpenCodex-test_deb"))).toBe(true);
+  });
+
+  test("a spawn that never started counts as a failure", () => {
+    const { logs, deps } = depsFor({ appimage: null, deb: 0 });
+    expect(runBuildLocal(deps)).toBe(1);
+    expect(logs.some(line => line.includes("appimage: FAILED"))).toBe(true);
+  });
+
+  test("a spawn error reports the launch failure", () => {
+    const errors: string[] = [];
+    const deps = depsFor({ deb: 0 }).deps;
+    const originalSpawn = deps.spawn;
+    deps.error = line => { errors.push(line); };
+    deps.spawn = args => (args.includes("appimage") ? { status: null, error: new Error("spawn bunx ENOENT") } : originalSpawn(args));
+    expect(runBuildLocal(deps)).toBe(1);
+    expect(errors.some(line => line.includes("could not start tauri"))).toBe(true);
+  });
+
+  test("the invocation shape is one tauri build per format, extra argv forwarded everywhere", () => {
+    const { calls, deps } = depsFor({ appimage: 1, deb: 0 }, { argv: ["--target", "x86_64-unknown-linux-gnu"] });
+    runBuildLocal(deps);
+    expect(calls[0]?.slice(0, 5)).toEqual(["tauri", "build", "--ci", "--bundles", "appimage"]);
+    expect(calls[1]?.slice(0, 5)).toEqual(["tauri", "--verbose", "build", "--ci", "--bundles"]);
+    for (const call of calls) {
+      expect(call.slice(-2)).toEqual(["--target", "x86_64-unknown-linux-gnu"]);
+    }
+  });
+
+  test("a fully successful build exits zero and keeps the updater note", () => {
+    const { logs, deps } = depsFor({});
+    expect(runBuildLocal(deps)).toBe(0);
+    expect(logs.some(line => line.includes("updater artifacts skipped"))).toBe(true);
+  });
+
+  test("macOS hosts build app and dmg", () => {
+    const { calls, deps } = depsFor({}, { platform: "darwin" });
+    expect(runBuildLocal(deps)).toBe(0);
+    const formats = calls.map(args => args[args.indexOf("--bundles") + 1]);
+    expect(formats).toEqual(["app", "dmg"]);
+  });
+
+  test("summarizeAttempts decides the exit code from the per-format outcomes", () => {
+    expect(summarizeAttempts([{ format: "appimage", status: 0 }, { format: "deb", status: 0 }]).exitCode).toBe(0);
+    expect(summarizeAttempts([{ format: "appimage", status: 1 }, { format: "deb", status: 0 }]).exitCode).toBe(1);
+    expect(summarizeAttempts([{ format: "appimage", status: 1 }, { format: "deb", status: 1 }]).lines[0]).toContain("FAILED");
+  });
+});
+
+describe("the desktop build toolchain carries the bundle-type marker", () => {
+  // updater.rs selects the deb updater target from tauri_utils::platform::bundle_type(),
+  // which reads a marker the tauri-bundler patches into the binary at packaging time.
+  // Bundlers before 2.5.0 (tauri-cli < 2.7.0) never patch: every packaged artifact then
+  // reports "unknown" and a deb install would resolve the AppImage payload it cannot
+  // apply. Verified statically at tag tauri-cli-v2.11.1: crates/tauri-bundler/src/
+  // bundle.rs maps Deb and AppImage to their marker values, patches per package type,
+  // signs after patching, and restores the unpatched binary between formats.
+  const minimumCliWithBundlePatch = { major: 2, minor: 7 };
+
+  test("the pinned Tauri CLI is new enough to patch the bundle type into each Linux artifact", () => {
+    const manifest = JSON.parse(readFileSync(repoPath("desktop", "package.json"), "utf8")) as {
+      devDependencies?: Record<string, string>;
+    };
+    const version = manifest.devDependencies?.["@tauri-apps/cli"];
+    expect(version).toBeDefined();
+    const [major, minor] = version!.split(".").map(Number);
+    expect(
+      major! > minimumCliWithBundlePatch.major
+        || (major === minimumCliWithBundlePatch.major && minor! >= minimumCliWithBundlePatch.minor),
+    ).toBe(true);
+  });
+});
+
+describe("widget extension signing", () => {
+  const script = readFileSync(repoPath("desktop", "scripts", "build-widget.sh"), "utf8");
+  const workflow = Bun.YAML.parse(
+    readFileSync(repoPath(".github", "workflows", "release.yml"), "utf8"),
+  ) as {
+    jobs?: Record<string, {
+      env?: Record<string, string>;
+      steps?: Array<{ name?: string; if?: string; run?: string; env?: Record<string, string> }>;
+    }>;
+  };
+  const steps = workflow.jobs?.["package-desktop"]?.steps ?? [];
+  const indexOfStep = (name: string) => steps.findIndex(step => step.name === name);
+  // Located by what a step does, not by what it is called. The first version of this file keyed
+  // on step names, and #5339 renamed the certificate import while this branch was open: the
+  // rename survived the merge, the assertion did not, and `dev` went red on a test whose subject
+  // was still correct.
+  const indexOfStepRunning = (fragment: string) =>
+    steps.findIndex(step => typeof step.run === "string" && step.run.includes(fragment));
+
+  test("the release build hands the widget a signing identity and forbids an ad-hoc fallback", () => {
+    const build = steps.find(step => step.name === "Build WidgetKit extension");
+    expect(build).toBeDefined();
+    expect(build?.env?.MACOS_SIGN_IDENTITY).toContain("APPLE_SIGNING_IDENTITY");
+    expect(build?.env?.WIDGET_SIGN_REQUIRED).toContain("DESKTOP_SIGNING_CONFIGURED");
+    expect(workflow.jobs?.["package-desktop"]?.env?.DESKTOP_SIGNING_CONFIGURED)
+      .toContain("APPLE_CERTIFICATE");
+  });
+
+  test("the certificate is importable before the widget is signed and is removed afterwards", () => {
+    // codesign resolves an identity through the keychain search list, and Tauri does not build
+    // its own keychain until the bundling step, which is after this one.
+    const importStep = indexOfStepRunning("security create-keychain");
+    const buildStep = indexOfStep("Build WidgetKit extension");
+    expect(importStep).toBeGreaterThanOrEqual(0);
+    expect(buildStep).toBeGreaterThan(importStep);
+
+    const cleanup = steps[indexOfStepRunning("security delete-keychain")];
+    expect(cleanup?.if).toContain("always()");
+    // The decoded p12 must not outlive the import, including when a later command fails.
+    expect(steps[importStep]?.run).toContain("trap ");
+    expect(steps[importStep]?.run).toContain("$certificate");
+  });
+
+  test("the script selects binaries by Mach-O magic bytes rather than by name", () => {
+    // A suffix filter is what let an unsigned helper through on a sibling project: neither
+    // `spawn-helper` nor `macos-trash` has an extension to match, and the submission came back
+    // rejected with the containing bundle looking correctly signed.
+    expect(script).toContain('file -b "$candidate"');
+    expect(script).toContain('*"Mach-O"*');
+    expect(script).not.toMatch(/-name\s+['"]\*\.(dylib|node|so)['"]/);
+  });
+
+  test("every signature carries the hardened runtime and the build proves it afterwards", () => {
+    // Notarization rejects any Mach-O in the bundle without it, and the widget's was omitted.
+    expect(script).toContain("--options runtime");
+    expect(script).toContain("codesign --verify --deep --strict");
+    expect(script).toContain('*"flags="*"runtime"*)');
+    // Captured, not piped: under `pipefail` a matcher that exits on its first hit kills codesign
+    // with SIGPIPE, and the assertion then fails on the signatures it was written to accept.
+    expect(script).toContain('signature_display="$(codesign --display');
+  });
+
+  test("a run holding Developer ID material refuses to fall back to an ad-hoc widget", () => {
+    expect(script).toContain('elif [[ "${WIDGET_SIGN_REQUIRED:-0}" == "1" ]]; then');
+    expect(script).toContain("refusing to ad-hoc sign a release widget");
+    // The refusal is resolved before the Swift build so a misconfigured release fails fast.
+    expect(script.indexOf("refusing to ad-hoc sign a release widget"))
+      .toBeLessThan(script.indexOf("swift build"));
+  });
+});
+
+/**
+ * The pre-publication verifier is the authority the verify-release job runs before
+ * anything may publish. Its expected set is derived from the real release matrices
+ * and the producer tables, its signatures are real Ed25519 fixtures in minisign
+ * shape, and the receipt it writes is the one attach-release requires.
+ */
+describe("release asset verification", () => {
+  const VERSION = "2.61.0";
+
+  function writeAsset(dir: string, name: string, payload: Buffer): void {
+    const digest = createHash("sha256").update(payload).digest("hex");
+    writeFileSync(join(dir, name), payload);
+    writeFileSync(join(dir, `${name}.sha256`), `${digest}  ${name}\n`);
+  }
+
+  function makeMinisignKeypair(keyIdHex: string): {
+    pubkeyText: string;
+    keyId: Buffer;
+    signPayload: (payload: Buffer) => string;
+  } {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const raw = Buffer.from(publicKey.export({ format: "der", type: "spki" })).subarray(-32);
+    const keyId = Buffer.from(keyIdHex, "hex");
+    const pubkeyText = `untrusted comment: test public key\n${Buffer.concat([Buffer.from("Ed"), keyId, raw]).toString("base64")}\n`;
+    const signPayload = (payload: Buffer): string =>
+      `untrusted comment: test signature\n${Buffer.concat([Buffer.from("Ed"), keyId, ed25519Sign(null, payload, privateKey)]).toString("base64")}\n`;
+    return { pubkeyText, keyId, signPayload };
+  }
+
+  test("derives the expected set from the real release matrices and producer tables", () => {
+    const workflow = readFileSync(repoPath(".github", "workflows", "release.yml"), "utf8");
+    const { standaloneTargets: workflowStandalone, desktopTargets } = releaseMatrixTargets(workflow);
+    // The workflow matrix and the builder's shared target set must agree exactly.
+    expect([...workflowStandalone].sort()).toEqual([...standaloneTargets].sort());
+    expect(desktopTargets).toHaveLength(3);
+
+    const expected = expectedReleaseAssets({
+      version: VERSION,
+      desktopTargets,
+      requireSignatures: true,
+    });
+    for (const name of [
+      `ocx-${VERSION}-bun-windows-x64.zip`,
+      `ocx-${VERSION}-bun-linux-x64.tar.gz`,
+      `ocx-${VERSION}-bun-darwin-arm64.tar.gz.sha256`,
+      `OpenCodex-${VERSION}-macos.dmg`,
+      `OpenCodex-${VERSION}-macos.app.tar.gz.sig`,
+      `OpenCodex-${VERSION}-windows-x64.msi`,
+      `OpenCodex-${VERSION}-linux-x86_64.AppImage`,
+      `OpenCodex-${VERSION}-linux-amd64.deb`,
+    ]) {
+      expect(expected).toContain(name);
+    }
+    // Signature presence follows the updater table exactly: a bundle is signed
+    // precisely when platformFiles names it as an updater target, so a new updater
+    // target changes this contract by itself rather than needing a hand edit here.
+    const updaterSuffixes = new Set(Object.values(platformFiles));
+    for (const bundle of desktopTargets.flatMap(target => bundlesByTarget[target]!)) {
+      expect(expected).toContain(`OpenCodex-${VERSION}-${bundle.name}`);
+      expect(expected.includes(`OpenCodex-${VERSION}-${bundle.name}.sig`))
+        .toBe(updaterSuffixes.has(bundle.name));
+    }
+    expect(expected.some(name => name.includes("/"))).toBe(false);
+  });
+
+  test("verifies every recorded checksum and refuses a directory-prefixed record", () => {
+    const dir = temporaryDirectory();
+    try {
+      writeAsset(dir, "ocx-1.0.0-bun-linux-x64.tar.gz", Buffer.from("payload"));
+      expect(verifyChecksums(dir)).toBe(1);
+
+      const digest = createHash("sha256").update(Buffer.from("payload")).digest("hex");
+      writeFileSync(join(dir, "bad.sha256"), `${digest}  ocx-1.0.0-bun-linux-x64.tar.gz\n`);
+      expect(() => verifyChecksums(dir)).toThrow(/must record its own payload/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects a tampered payload and a missing payload", () => {
+    const dir = temporaryDirectory();
+    try {
+      writeAsset(dir, "ocx-1.0.0-bun-linux-x64.tar.gz", Buffer.from("payload"));
+      writeFileSync(join(dir, "ocx-1.0.0-bun-linux-x64.tar.gz"), Buffer.from("tampered"));
+      expect(() => verifyChecksums(dir)).toThrow(/Checksum mismatch/);
+
+      rmSync(join(dir, "ocx-1.0.0-bun-linux-x64.tar.gz"));
+      expect(() => verifyChecksums(dir)).toThrow(/which is missing/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("verifies updater signatures against the pinned key and refuses lookalikes", () => {
+    const dir = temporaryDirectory();
+    try {
+      const { pubkeyText, signPayload } = makeMinisignKeypair("0123456789abcdef");
+      const key = parseMinisignPublicKey(pubkeyText);
+      const payload = Buffer.from("signed payload bytes");
+      const asset = join(dir, "OpenCodex-1.0.0-macos.app.tar.gz");
+      writeFileSync(asset, payload);
+      writeFileSync(`${asset}.sig`, signPayload(payload));
+      expect(() => verifyUpdaterSignature(asset, key)).not.toThrow();
+
+      writeFileSync(asset, Buffer.from("tampered payload"));
+      expect(() => verifyUpdaterSignature(asset, key)).toThrow(/Signature verification failed/);
+      writeFileSync(asset, payload);
+
+      const other = makeMinisignKeypair("fedcba9876543210");
+      writeFileSync(`${asset}.sig`, other.signPayload(payload));
+      expect(() => verifyUpdaterSignature(asset, key)).toThrow(/not the pinned updater key/);
+
+      const hashed = `untrusted comment: test\n${Buffer.concat([Buffer.from("ED"), other.keyId, Buffer.alloc(64)]).toString("base64")}\n`;
+      writeFileSync(`${asset}.sig`, hashed);
+      expect(() => verifyUpdaterSignature(asset, key)).toThrow(/Unsupported signature algorithm/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("runs the full pre-publication verification and writes the receipt", () => {
+    const root = temporaryDirectory();
+    try {
+      const { pubkeyText, signPayload } = makeMinisignKeypair("0123456789abcdef");
+      // The verifier reads the matrices and the pinned key from the repo root, so the
+      // scratch root gets the real workflow and a conf carrying the fixture key.
+      mkdirSync(join(root, ".github", "workflows"), { recursive: true });
+      writeFileSync(
+        join(root, ".github", "workflows", "release.yml"),
+        readFileSync(repoPath(".github", "workflows", "release.yml"), "utf8"),
+      );
+      mkdirSync(join(root, "desktop", "src-tauri"), { recursive: true });
+      writeFileSync(
+        join(root, "desktop", "src-tauri", "tauri.conf.json"),
+        JSON.stringify({ plugins: { updater: { pubkey: Buffer.from(pubkeyText, "utf8").toString("base64") } } }),
+      );
+
+      const dir = join(root, "dist", "release");
+      mkdirSync(dir, { recursive: true });
+      // The fixture derives from the producer tables — the standalone target module,
+      // the bundle table, and the updater platform table — assembled independently
+      // of the function under test. Building it with expectedReleaseAssets would
+      // hide an omission in the expected set; hand-writing it would go stale the
+      // next time a target is added (which is exactly the union failure this test
+      // once carried: the deb became an updater target and this oracle missed its
+      // signature).
+      const desktopTargets = releaseMatrixTargets(
+        readFileSync(join(root, ".github", "workflows", "release.yml"), "utf8"),
+      ).desktopTargets;
+      const produced = [
+        ...standaloneTargets.map(target => standaloneArchiveName(VERSION, target)),
+        ...desktopTargets.flatMap(target =>
+          bundlesByTarget[target]!.map(bundle => `OpenCodex-${VERSION}-${bundle.name}`)),
+      ];
+      const updaterSuffixes = new Set(Object.values(platformFiles));
+      const signed = new Set(
+        produced.filter(name => updaterSuffixes.has(name.slice(`OpenCodex-${VERSION}-`.length))),
+      );
+      for (const name of produced) {
+        writeAsset(dir, name, Buffer.from(`payload:${name}`));
+        if (signed.has(name)) {
+          writeFileSync(join(dir, `${name}.sig`), signPayload(readFileSync(join(dir, name))));
+        }
+      }
+
+      // The derivation is checked against the oracle, not trusted: the expected set
+      // must be exactly the produced payloads plus their companions.
+      const expected = expectedReleaseAssets({
+        version: VERSION,
+        desktopTargets,
+        requireSignatures: true,
+      });
+      const oracle = produced.flatMap(name =>
+        signed.has(name) ? [name, `${name}.sha256`, `${name}.sig`] : [name, `${name}.sha256`]);
+      expect([...expected].sort()).toEqual([...oracle].sort());
+
+      const receiptPath = join(root, "verification", "receipt.json");
+      const manifestPath = join(dir, "latest.json");
+      const receipt = verifyReleaseAssets({
+        version: VERSION,
+        dir,
+        repo: "lidge-jun/opencodex",
+        sha: "0123456789abcdef0123456789abcdef01234567",
+        repoRoot: root,
+        manifestOut: manifestPath,
+        receiptOut: receiptPath,
+        requireSignatures: true,
+      });
+
+      expect(receipt.expectedFiles).toBe(expected.length);
+      expect(receipt.checksumsVerified)
+        .toBe(produced.length);
+      expect(receipt.signaturesVerified).toBe(signed.size);
+      // Same rule as the signed set: the platform list is the updater table's keys,
+      // not a copy of them.
+      expect(receipt.manifestPlatforms).toEqual(Object.keys(platformFiles).sort());
+      expect(JSON.parse(readFileSync(receiptPath, "utf8"))).toEqual(receipt);
+
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+        platforms: Record<string, { url: string }>;
+      };
+      expect(manifest.platforms["linux-x86_64"]!.url)
+        .toBe(`https://github.com/lidge-jun/opencodex/releases/download/v${VERSION}/OpenCodex-${VERSION}-linux-x86_64.AppImage`);
+
+      // Anything beyond the expected set is refused rather than published.
+      writeFileSync(join(dir, "stray.txt"), "stray");
+      expect(() => verifyReleaseAssets({
+        version: VERSION,
+        dir,
+        repo: "lidge-jun/opencodex",
+        sha: "0123456789abcdef0123456789abcdef01234567",
+        repoRoot: root,
+        manifestOut: manifestPath,
+        requireSignatures: true,
+      })).toThrow(/Unexpected files/);
+      rmSync(join(dir, "stray.txt"));
+
+      rmSync(join(dir, `OpenCodex-${VERSION}-windows-x64.msi`));
+      expect(() => verifyReleaseAssets({
+        version: VERSION,
+        dir,
+        repo: "lidge-jun/opencodex",
+        sha: "0123456789abcdef0123456789abcdef01234567",
+        repoRoot: root,
+        requireSignatures: true,
+      })).toThrow(/Missing expected release assets/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/tests/ci-workflows/release-pipeline-contract.test.ts b/tests/ci-workflows/release-pipeline-contract.test.ts
new file mode 100644
index 00000000000..208b1d962c0
--- /dev/null
+++ b/tests/ci-workflows/release-pipeline-contract.test.ts
@@ -0,0 +1,229 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+
+type WorkflowStep = {
+  name?: string;
+  if?: string;
+  uses?: string;
+  with?: Record<string, unknown>;
+  env?: Record<string, string>;
+  run?: string;
+  shell?: string;
+};
+
+type WorkflowJob = {
+  if?: string;
+  needs?: string[];
+  strategy?: { matrix?: { include?: Array<{ os?: string }> } };
+  steps?: WorkflowStep[];
+};
+
+type Workflow = { jobs?: Record<string, WorkflowJob | undefined> };
+
+function needsOf(job: WorkflowJob | undefined): string[] {
+  if (job?.needs === undefined) return [];
+  return typeof job.needs === "string" ? [job.needs] : job.needs;
+}
+
+function readWorkflow(...segments: string[]): Workflow {
+  return Bun.YAML.parse(readFileSync(repoPath(...segments), "utf8")) as Workflow;
+}
+
+function triggerPaths(workflowText: string, trigger: string, until: string): string[] {
+  const afterTrigger = workflowText.split(`${trigger}:`)[1]?.split(`${until}:`)[0];
+  expect(afterTrigger).toBeDefined();
+  return afterTrigger!
+    .split("\n")
+    .map(line => line.trim())
+    .filter(line => line.startsWith('- "'))
+    .map(line => line.slice(3, -1));
+}
+
+/**
+ * Contracts for the release pipeline itself. Each assertion encodes a defect that a green
+ * workflow can still carry: a bash script silently reinterpreted by PowerShell on a Windows
+ * runner, a checksum that records a path its verifier cannot resolve, publication that outruns
+ * packaging, and a service gate that names one file while the implementation is a directory.
+ */
+describe("release pipeline contract", () => {
+  const release = readWorkflow(".github", "workflows", "release.yml");
+
+  test("every multi-line script on a Windows runner declares an explicit shell", () => {
+    for (const jobId of ["package-standalone", "package-desktop"]) {
+      const job = release.jobs?.[jobId];
+      expect(job, jobId).toBeDefined();
+      const runsOnWindows = job!.strategy?.matrix?.include?.some(entry => entry.os === "windows-latest");
+      expect(runsOnWindows, `${jobId} exercises Windows`).toBe(true);
+      for (const step of job!.steps ?? []) {
+        // A single command line is shell-neutral; a script block implies shell-specific
+        // syntax and must not fall back to the runner's default shell on Windows.
+        if (typeof step.run !== "string" || !step.run.includes("\n")) continue;
+        // Steps fenced away from Windows never meet PowerShell.
+        if (/runner\.os\s*==\s*'(Linux|macOS)'/.test(step.if ?? "")) continue;
+        expect(step.shell, `${jobId} / ${step.name}`).toBeDefined();
+      }
+    }
+  });
+
+  test("the release asset rename runs under bash", () => {
+    const step = release.jobs?.["package-desktop"]?.steps
+      ?.find(candidate => candidate.run?.includes("collect-release-assets.ts"));
+    expect(step).toBeDefined();
+    // The script uses backslash continuations and "$VAR" expansion, which PowerShell does
+    // not read the way bash does; on the Windows matrix this step is only correct under bash.
+    expect(step!.shell).toBe("bash");
+  });
+
+  test("standalone checksums record bare names that resolve where the verifier runs", () => {
+    const archive = release.jobs?.["package-standalone"]?.steps
+      ?.find(candidate => candidate.run?.includes("sha256sum"));
+    expect(archive).toBeDefined();
+    const checksumLines = archive!.run!.split("\n")
+      .filter(line => line.includes("sha256sum") && !line.trim().startsWith("#"));
+    expect(checksumLines.length).toBeGreaterThanOrEqual(2);
+    for (const line of checksumLines) {
+      const argument = /sha256sum\s+"([^"]+)"/.exec(line)?.[1];
+      expect(argument, line).toBeDefined();
+      // shasum -c resolves the recorded path relative to the verifier's working directory,
+      // which is dist/release; any directory prefix names a file that cannot exist there.
+      expect(argument!).not.toContain("/");
+      // The redirect target gets the same treatment: a bare output name is what makes the
+      // checksum file land in the directory the upload glob scans.
+      const output = />\s+"([^"]+)"/.exec(line)?.[1];
+      expect(output, line).toBeDefined();
+      expect(output!).not.toContain("/");
+    }
+
+    // The bare names above only resolve end to end if the step checksums from the directory
+    // the artifact lives in (it leaves the per-target build directory first), if the upload
+    // glob picks the checksum file up, and if the pre-publication verifier downloads every
+    // artifact flattened beside them. Locking only the final line would leave those joints
+    // unguarded. YAML block scalars are dedented on parse, so the script's own lines carry
+    // no indentation here.
+    expect(archive!.run).toMatch(/^ *cd \.\.\/\.\.$/m);
+    const upload = release.jobs?.["package-standalone"]?.steps
+      ?.find(candidate => candidate.uses?.startsWith("actions/upload-artifact@"));
+    expect(String(upload?.with?.path)).toContain("dist/ocx-*.sha256");
+
+    const download = release.jobs?.["verify-release"]?.steps
+      ?.find(candidate => candidate.uses?.startsWith("actions/download-artifact@")
+        && candidate.with?.pattern === "standalone-*");
+    expect(download?.with?.["merge-multiple"]).toBe(true);
+    expect(download?.with?.path).toBe("dist/release");
+  });
+
+  test("publication consumes the verified packaging result", () => {
+    const verify = release.jobs?.["verify-release"];
+    expect(verify).toBeDefined();
+    expect(needsOf(verify).sort())
+      .toEqual(["package-desktop", "package-standalone", "validate-dispatch"]);
+    // Verification is not a publication-mode step: a dry run must prove the same chain
+    // a real release relies on, so the job carries no dry-run exemption.
+    expect(verify!.if).toBeUndefined();
+    expect(verify!.steps?.some(candidate => candidate.run?.includes("verify-release-assets.ts")))
+      .toBe(true);
+
+    const publish = release.jobs?.publish;
+    expect(publish).toBeDefined();
+    expect(needsOf(publish).sort()).toEqual(["validate-dispatch", "verify-release"]);
+
+    const attach = release.jobs?.["attach-release"];
+    expect(attach).toBeDefined();
+    expect(needsOf(attach).sort()).toEqual(["publish", "verify-release"]);
+  });
+
+  test("attach uploads only the verified bundle, and only after requiring its receipt", () => {
+    const steps = release.jobs?.["attach-release"]?.steps ?? [];
+    // Verification happens exactly once, before publication: attach must not re-verify
+    // checksums or regenerate the manifest from unverified parts.
+    expect(steps.some(candidate => candidate.run?.includes("shasum"))).toBe(false);
+    expect(steps.some(candidate => candidate.run?.includes("updater-manifest.ts"))).toBe(false);
+
+    const bundle = steps.find(candidate => candidate.uses?.startsWith("actions/download-artifact@")
+      && candidate.with?.name === "verified-release");
+    expect(bundle?.with?.path).toBe("dist/release");
+
+    const receiptCheck = steps.findIndex(candidate => candidate.run?.includes("verification/receipt.json"));
+    const upload = steps.findIndex(candidate => candidate.run?.includes("gh release upload"));
+    expect(receiptCheck).toBeGreaterThanOrEqual(0);
+    expect(upload).toBeGreaterThan(receiptCheck);
+  });
+
+  test("a partial publication has a recorded, explicit recovery path", () => {
+    const releaseText = readFileSync(repoPath(".github", "workflows", "release.yml"), "utf8");
+    // The only way npm publish is ever skipped: an explicit recovery input, requiring
+    // the version to already be acknowledged on npm, refusing combination with dry-run.
+    expect(releaseText).toContain("resume-after-npm-publish:");
+
+    const publishSteps = release.jobs?.publish?.steps ?? [];
+    const preflight = publishSteps.find(candidate => candidate.name === "Preflight release metadata");
+    expect(preflight?.run).toContain("no acknowledged publication to resume from");
+    expect(preflight?.run).toContain("cannot combine with dry-run");
+
+    const publication = publishSteps.find(candidate => candidate.id === "publication");
+    // The summary line references RELEASE_VERSION under set -u; the env must carry it.
+    expect(publication?.env?.RELEASE_VERSION).toBe("${{ inputs.version }}");
+    expect(publication?.run).toContain('if [ "$RESUME" = "true" ]');
+    expect(publication?.run).toContain('echo "published=true" >> "$GITHUB_OUTPUT"');
+    // A successful publish records the recovery path at the moment it matters.
+    expect(publication?.run).toContain("never republish this version");
+
+    // The version-line gate must let the resume path past a tag it created itself.
+    const versionLine = publishSteps.find(candidate => candidate.run?.includes("assert-releasable"));
+    expect(versionLine?.env?.RESUME).toBe("${{ inputs.resume-after-npm-publish }}");
+    expect(versionLine?.run).toContain('$RESUME');
+
+    // A run that failed after the release was created must be able to complete the
+    // attachment on resume; outside resume, an existing release stays a hard failure.
+    const create = publishSteps.find(candidate => candidate.name === "Create GitHub release");
+    expect(create?.env?.RESUME).toBe("${{ inputs.resume-after-npm-publish }}");
+    expect(create?.run).toContain('gh release view "$release_tag"');
+    expect(create?.run).toContain("already exists; reusing it for attachment");
+    expect(create?.run).toContain("refusing to reuse it outside the resume path");
+  });
+});
+
+describe("service lifecycle trigger coverage", () => {
+  const lifecycleText = readFileSync(repoPath(".github", "workflows", "service-lifecycle.yml"), "utf8");
+  const releaseText = readFileSync(repoPath(".github", "workflows", "release.yml"), "utf8");
+
+  test("both triggers cover the service directory and the desktop shell", () => {
+    const pushPaths = triggerPaths(lifecycleText, "push", "workflow_dispatch");
+    const prPaths = triggerPaths(lifecycleText, "pull_request", "push");
+    for (const paths of [prPaths, pushPaths]) {
+      expect(paths).toContain("src/service.ts");
+      expect(paths).toContain("src/service/**");
+      expect(paths).toContain("desktop/**");
+    }
+    expect([...prPaths].sort()).toEqual([...pushPaths].sort());
+  });
+
+  test("the release service gate matches every implemented service module and desktop file", () => {
+    const gateSource = releaseText.match(/grep -Eq '(\^\([^']+\)\$)'/)?.[1];
+    expect(gateSource).toBeDefined();
+    const gate = new RegExp(gateSource!);
+
+    // Derived from the tree, not restated: the service implementation is a directory, so
+    // every module in it must satisfy the gate that demands lifecycle evidence.
+    const serviceModules = readdirSync(repoPath("src", "service"))
+      .filter(entry => entry.endsWith(".ts"));
+    expect(serviceModules.length).toBeGreaterThanOrEqual(10);
+    for (const module of serviceModules) {
+      expect(gate.test(`src/service/${module}`), `src/service/${module}`).toBe(true);
+    }
+    expect(gate.test("src/service.ts")).toBe(true);
+
+    const desktopSurfaces = [
+      ...readdirSync(repoPath("desktop", "scripts")).map(entry => `desktop/scripts/${entry}`),
+      ...readdirSync(repoPath("desktop", "src-tauri", "src")).map(entry => `desktop/src-tauri/src/${entry}`),
+    ];
+    expect(desktopSurfaces.length).toBeGreaterThanOrEqual(10);
+    for (const path of desktopSurfaces) {
+      expect(gate.test(path), path).toBe(true);
+    }
+
+    expect(gate.test("src/router.ts")).toBe(false);
+    expect(gate.test("docs-site/src/pages/index.astro")).toBe(false);
+  });
+});
diff --git a/tests/claude-integration/claude-desktop-first-party.test.ts b/tests/claude-integration/claude-desktop-first-party.test.ts
new file mode 100644
index 00000000000..7b391f98dae
--- /dev/null
+++ b/tests/claude-integration/claude-desktop-first-party.test.ts
@@ -0,0 +1,268 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  applyDesktopFirstParty,
+  inspectDesktopFirstParty,
+  removeDesktopFirstParty,
+  resolveClaudeDesktopApplyMode,
+  resolveClaudeDesktopMode,
+} from "../../src/claude/desktop-first-party";
+import { parseDesktopApplyArgs } from "../../src/cli/claude-desktop";
+import { ensureClaudeDesktopMatchesDesired } from "../../src/cli/ensure-desired-integrations";
+import { handleManagementAPI } from "../../src/server/management-api";
+import { setIntegrationEnabled } from "../../src/codex/desired-state";
+import type { OcxConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+let root = "";
+let library = "";
+let claudeDir = "";
+const previous: Record<string, string | undefined> = {};
+const ENV_KEYS = ["OPENCODEX_HOME", "OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR", "CLAUDE_CONFIG_DIR"] as const;
+
+function config(extra: Partial<OcxConfig> = {}): OcxConfig {
+  return { port: 10100, providers: {}, defaultProvider: "openai", ...extra } as OcxConfig;
+}
+
+function settings(): { env?: Record<string, string>; [key: string]: unknown } {
+  return JSON.parse(readFileSync(join(claudeDir, "settings.json"), "utf8")) as { env?: Record<string, string> };
+}
+
+async function dispatch(path: string, init?: RequestInit, inputConfig: OcxConfig = config()) {
+  const url = new URL(`http://127.0.0.1:10100${path}`);
+  const response = await handleManagementAPI(new Request(url, {
+    ...init,
+    headers: { Host: url.host, "Content-Type": "application/json", ...(init?.headers ?? {}) },
+  }), url, inputConfig, {});
+  return { status: response!.status, body: await response!.json() as Record<string, any> };
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "ocx-desktop-1p-"));
+  library = join(root, "desktop-library");
+  claudeDir = join(root, "claude");
+  for (const key of ENV_KEYS) previous[key] = process.env[key];
+  process.env.OPENCODEX_HOME = root;
+  process.env.OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR = library;
+  process.env.CLAUDE_CONFIG_DIR = claudeDir;
+  writeFileSync(join(root, "config.json"), JSON.stringify(config()));
+});
+
+afterEach(() => {
+  for (const key of ENV_KEYS) {
+    if (previous[key] === undefined) delete process.env[key];
+    else process.env[key] = previous[key];
+  }
+  removeTreeWithRetry(root);
+});
+
+test("mode resolution: explicit wins, applied gateway fingerprint keeps gateway, otherwise first-party", () => {
+  expect(resolveClaudeDesktopMode(config())).toBe("first-party");
+  expect(resolveClaudeDesktopMode(config({ claudeCode: { desktopMode: "gateway" } }))).toBe("gateway");
+  expect(resolveClaudeDesktopMode(config({
+    claudeCode: { desktopProfile: { version: 1, assignments: {}, defaults: { opus: null, fable: null, sonnet: null, haiku: null }, appliedFingerprint: "abc" } },
+  }))).toBe("gateway");
+  expect(resolveClaudeDesktopMode(config({
+    claudeCode: {
+      desktopMode: "first-party",
+      desktopProfile: { version: 1, assignments: {}, defaults: { opus: null, fable: null, sonnet: null, haiku: null }, appliedFingerprint: "abc" },
+    },
+  }))).toBe("first-party");
+});
+
+test("implied apply mode falls back to gateway where the intercept proxy cannot run", () => {
+  expect(resolveClaudeDesktopApplyMode(config())).toBe("first-party");
+  expect(resolveClaudeDesktopApplyMode(config({ runtimeRole: "client" }))).toBe("gateway");
+  expect(resolveClaudeDesktopApplyMode(config({ claudeCode: { intercept: { enabled: false } } }))).toBe("gateway");
+  // An explicit choice is never silently rewritten.
+  expect(resolveClaudeDesktopApplyMode(config({ runtimeRole: "client", claudeCode: { desktopMode: "first-party" } }))).toBe("first-party");
+});
+
+test("CLI apply flags: default first-party, legacy shape flags imply gateway, conflicts rejected", () => {
+  expect(parseDesktopApplyArgs([], config())).toEqual({ target: { kind: "first-party" } });
+  expect(parseDesktopApplyArgs(["--first-party"], config())).toEqual({ target: { kind: "first-party" } });
+  expect(parseDesktopApplyArgs(["--gateway"], config())).toEqual({ target: { kind: "gateway", mode: "static" } });
+  expect(parseDesktopApplyArgs(["--hybrid"], config())).toEqual({ target: { kind: "gateway", mode: "hybrid" } });
+  expect(parseDesktopApplyArgs(["--gateway", "--discovery-only"], config())).toEqual({ target: { kind: "gateway", mode: "discovery" } });
+  expect(parseDesktopApplyArgs([], config({ claudeCode: { desktopMode: "gateway" } }))).toEqual({ target: { kind: "gateway", mode: "static" } });
+  expect("error" in parseDesktopApplyArgs(["--first-party", "--gateway"], config())).toBe(true);
+  expect("error" in parseDesktopApplyArgs(["--first-party", "--static"], config())).toBe(true);
+  expect("error" in parseDesktopApplyArgs(["--bogus"], config())).toBe(true);
+});
+
+test("first-party apply writes only the proxy env, creates the CA, and removes cleanly", () => {
+  mkdirSync(claudeDir, { recursive: true });
+  writeFileSync(join(claudeDir, "settings.json"), JSON.stringify({ theme: "dark", env: { FOO: "bar" } }));
+  const applied = applyDesktopFirstParty(config());
+  expect(applied.ok).toBe(true);
+  if (!applied.ok) return;
+  expect(applied.proxyPort).toBe(10200);
+  expect(existsSync(applied.env.NODE_EXTRA_CA_CERTS)).toBe(true);
+  expect(applied.env.NODE_EXTRA_CA_CERTS.startsWith(root)).toBe(true);
+  const written = settings();
+  expect(written.theme).toBe("dark");
+  expect(written.env).toEqual({
+    FOO: "bar",
+    HTTPS_PROXY: "http://127.0.0.1:10200",
+    NODE_EXTRA_CA_CERTS: applied.env.NODE_EXTRA_CA_CERTS,
+  });
+  expect(inspectDesktopFirstParty(config()).applied).toBe(true);
+  // Desktop's own library is untouched: first-party never installs a gateway profile.
+  expect(existsSync(library)).toBe(false);
+
+  // A port change makes the env stale; re-apply refreshes it.
+  expect(inspectDesktopFirstParty(config({ port: 10300 })).stale).toBe(true);
+  const refreshed = applyDesktopFirstParty(config({ port: 10300 }));
+  expect(refreshed.ok && refreshed.changed).toBe(true);
+  expect(settings().env?.HTTPS_PROXY).toBe("http://127.0.0.1:10400");
+
+  const removed = removeDesktopFirstParty();
+  expect(removed).toMatchObject({ ok: true, changed: true });
+  expect(settings()).toEqual({ theme: "dark", env: { FOO: "bar" } });
+});
+
+test("first-party apply refuses foreign proxy env and disabled intercept", () => {
+  mkdirSync(claudeDir, { recursive: true });
+  writeFileSync(join(claudeDir, "settings.json"), JSON.stringify({ env: { HTTPS_PROXY: "http://corp-proxy:3128" } }));
+  expect(applyDesktopFirstParty(config())).toMatchObject({ ok: false, reason: "foreign_env" });
+  expect(settings().env).toEqual({ HTTPS_PROXY: "http://corp-proxy:3128" });
+  expect(removeDesktopFirstParty()).toMatchObject({ ok: true, changed: false });
+  expect(applyDesktopFirstParty(config({ runtimeRole: "client" }))).toMatchObject({ ok: false, reason: "intercept_disabled" });
+});
+
+test("POST /api/claude-desktop/apply defaults to first-party and gateway mode replaces it", async () => {
+  const first = await dispatch("/api/claude-desktop/apply", { method: "POST" });
+  expect(first.status).toBe(200);
+  expect(first.body).toMatchObject({ ok: true, mode: "first-party", applied: true, changed: true, proxyPort: 10200 });
+  expect(settings().env?.HTTPS_PROXY).toBe("http://127.0.0.1:10200");
+  const saved = JSON.parse(readFileSync(join(root, "config.json"), "utf8")) as OcxConfig;
+  expect(saved.claudeCode?.desktopMode).toBe("first-party");
+  expect(saved.clientIntegrations?.["claude-desktop"]).not.toBe(false);
+
+  const status = await dispatch("/api/claude-desktop/status");
+  expect(status.body).toMatchObject({
+    mode: "first-party",
+    applied: true,
+    stale: false,
+    drift: false,
+    firstParty: { applied: true, interceptEnabled: true, proxyPort: 10200 },
+  });
+  expect(status.body.health.ok).toBe(true);
+
+  const gateway = await dispatch("/api/claude-desktop/apply", { method: "POST", body: JSON.stringify({ mode: "gateway" }) });
+  expect(gateway.status).toBe(200);
+  expect(settings().env?.HTTPS_PROXY).toBeUndefined();
+  expect(settings().env?.NODE_EXTRA_CA_CERTS).toBeUndefined();
+  const afterGateway = JSON.parse(readFileSync(join(root, "config.json"), "utf8")) as OcxConfig;
+  expect(afterGateway.claudeCode?.desktopMode).toBe("gateway");
+  expect(afterGateway.claudeCode?.desktopProfile?.appliedFingerprint).toBeTruthy();
+
+  // Switching back replaces the gateway profile with the first-party env in one apply.
+  const back = await dispatch("/api/claude-desktop/apply", { method: "POST", body: JSON.stringify({ mode: "first-party" }) }, afterGateway);
+  expect(back.status).toBe(200);
+  expect(back.body).toMatchObject({ ok: true, mode: "first-party", applied: true, gatewayRemoved: true });
+  expect(settings().env?.HTTPS_PROXY).toBe("http://127.0.0.1:10200");
+  const afterBack = await dispatch("/api/claude-desktop/status", {}, afterGateway);
+  expect(afterBack.body).toMatchObject({ mode: "first-party", applied: true, stale: false, drift: false, desiredEnabled: true });
+  expect(["not_installed", "no_owned_state", "standard"]).toContain(afterBack.body.observedKind);
+  // The gateway apply marker goes with the profile: without the explicit mode field the
+  // saved config must still resolve to first-party, not to the gateway it just replaced.
+  const savedBack = JSON.parse(readFileSync(join(root, "config.json"), "utf8")) as OcxConfig;
+  expect(savedBack.claudeCode?.desktopProfile?.appliedFingerprint).toBeUndefined();
+  expect(savedBack.claudeCode?.desktopProfile?.appliedAt).toBeUndefined();
+  expect(savedBack.claudeCode?.desktopProfile?.assignments).toBeDefined();
+  expect(resolveClaudeDesktopMode({ claudeCode: { ...savedBack.claudeCode, desktopMode: undefined } })).toBe("first-party");
+});
+
+test("native toggle: enable applies first-party by default and disable removes the env", async () => {
+  const enabled = await dispatch("/api/native-integrations/claude-desktop", { method: "PUT", body: JSON.stringify({ enabled: true }) });
+  expect(enabled.status).toBe(200);
+  expect(enabled.body).toMatchObject({ ok: true, changed: true, state: "current", desiredEnabled: true });
+  expect(settings().env?.HTTPS_PROXY).toBe("http://127.0.0.1:10200");
+
+  const list = await dispatch("/api/native-integrations");
+  const desktop = (list.body.clients as Array<{ clientId: string; state: string }>).find(client => client.clientId === "claude-desktop");
+  expect(desktop?.state).toBe("current");
+
+  const disabled = await dispatch("/api/native-integrations/claude-desktop", { method: "PUT", body: JSON.stringify({ enabled: false }) });
+  expect(disabled.status).toBe(200);
+  expect(disabled.body).toMatchObject({ ok: true, changed: true, state: "absent", desiredEnabled: false });
+  expect(settings().env?.HTTPS_PROXY).toBeUndefined();
+});
+
+test("native toggle: enabling into explicit first-party pivots an applied gateway profile and saves the mode marker", async () => {
+  const gateway = await dispatch("/api/claude-desktop/apply", { method: "POST", body: JSON.stringify({ mode: "gateway" }) });
+  expect(gateway.status).toBe(200);
+  const afterGateway = JSON.parse(readFileSync(join(root, "config.json"), "utf8")) as OcxConfig;
+  expect(afterGateway.claudeCode?.desktopProfile?.appliedFingerprint).toBeTruthy();
+  // The operator chose first-party in config while the gateway profile is still on disk.
+  const chosen = { ...afterGateway, claudeCode: { ...afterGateway.claudeCode, desktopMode: "first-party" as const } };
+  writeFileSync(join(root, "config.json"), JSON.stringify(chosen));
+
+  const enabled = await dispatch("/api/native-integrations/claude-desktop", { method: "PUT", body: JSON.stringify({ enabled: true }) }, chosen);
+  expect(enabled.status).toBe(200);
+  expect(enabled.body).toMatchObject({ ok: true, changed: true, state: "current", desiredEnabled: true });
+  expect(settings().env?.HTTPS_PROXY).toBe("http://127.0.0.1:10200");
+  const saved = JSON.parse(readFileSync(join(root, "config.json"), "utf8")) as OcxConfig;
+  expect(saved.claudeCode?.desktopMode).toBe("first-party");
+  expect(saved.claudeCode?.desktopProfile?.appliedFingerprint).toBeUndefined();
+  const status = await dispatch("/api/claude-desktop/status", {}, chosen);
+  expect(status.body).toMatchObject({ mode: "first-party", applied: true, drift: false });
+  expect(["not_installed", "no_owned_state", "standard"]).toContain(status.body.observedKind);
+});
+
+test("native toggle: enabling into gateway saves the gateway mode marker like the apply route", async () => {
+  // No explicit mode: the disabled intercept is what implies gateway, so the saved marker
+  // can only come from the toggle itself.
+  const chosen = config({ claudeCode: { intercept: { enabled: false } } });
+  writeFileSync(join(root, "config.json"), JSON.stringify(chosen));
+  const enabled = await dispatch("/api/native-integrations/claude-desktop", { method: "PUT", body: JSON.stringify({ enabled: true }) }, chosen);
+  expect(enabled.status).toBe(200);
+  expect(enabled.body).toMatchObject({ ok: true, state: "current", message: "Claude Desktop integration enabled." });
+  expect(existsSync(join(claudeDir, "settings.json"))).toBe(false);
+  const saved = JSON.parse(readFileSync(join(root, "config.json"), "utf8")) as OcxConfig;
+  expect(saved.claudeCode?.desktopMode).toBe("gateway");
+  expect(resolveClaudeDesktopMode(saved)).toBe("gateway");
+});
+
+test("ensure warns instead of touching a gateway profile that contradicts an explicit first-party marker", () => {
+  const logs: string[] = [];
+  const deps = {
+    loadConfig: () => config({ claudeCode: { desktopMode: "first-party" } }),
+    stripGrokConfig: () => ({ ok: true, changed: false, message: "" }),
+    syncGrokConfig: async () => ({ ok: true, changed: false, message: "" }),
+    removeDesktop3pStandardPivot: () => { throw new Error("must not pivot from ensure"); },
+    inspectDesktop3pConfigLibrary: () => ({ kind: "gateway_ours" as const, libraryPath: library, activeProfilePath: null, ownedFiles: [] }),
+    applyDesktopFirstParty: () => { throw new Error("must not apply over a live gateway"); },
+    log: (message: string) => { logs.push(message); },
+    error: (message: string) => { logs.push(message); },
+  };
+  ensureClaudeDesktopMatchesDesired(deps as unknown as Parameters<typeof ensureClaudeDesktopMatchesDesired>[0]);
+  expect(logs.some(line => line.includes("gateway profile is still applied"))).toBe(true);
+});
+
+test("ensure reconciles first-party env: refreshes when ON and stale, removes when OFF", () => {
+  const applied = applyDesktopFirstParty(config({ port: 10300 }));
+  expect(applied.ok).toBe(true);
+  expect(settings().env?.HTTPS_PROXY).toBe("http://127.0.0.1:10400");
+
+  const logs: string[] = [];
+  const deps = {
+    loadConfig: () => config(),
+    stripGrokConfig: () => ({ ok: true, changed: false, message: "" }),
+    syncGrokConfig: async () => ({ ok: true, changed: false, message: "" }),
+    removeDesktop3pStandardPivot: () => ({ ok: true as const, changed: false, kind: "noop" as const, libraryPath: library }),
+    log: (message: string) => { logs.push(message); },
+    error: (message: string) => { logs.push(message); },
+  };
+  ensureClaudeDesktopMatchesDesired(deps);
+  expect(settings().env?.HTTPS_PROXY).toBe("http://127.0.0.1:10200");
+  expect(logs.some(line => line.includes("first-party env refreshed"))).toBe(true);
+
+  expect(setIntegrationEnabled("claude-desktop", false).ok).toBe(true);
+  ensureClaudeDesktopMatchesDesired({ ...deps, loadConfig: () => config({ clientIntegrations: { "claude-desktop": false } }) });
+  expect(settings().env?.HTTPS_PROXY).toBeUndefined();
+  expect(settings().env?.NODE_EXTRA_CA_CERTS).toBeUndefined();
+});
diff --git a/tests/claude-integration/claude-desktop-mode-explanation.test.ts b/tests/claude-integration/claude-desktop-mode-explanation.test.ts
new file mode 100644
index 00000000000..a2b6e80529e
--- /dev/null
+++ b/tests/claude-integration/claude-desktop-mode-explanation.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { gatewayModeExplanation } from "../../src/cli/claude-desktop";
+import type { ClientConnectionState } from "../../src/client/state";
+
+const disconnected = { kind: "disconnected" } as ClientConnectionState;
+const connected = { kind: "connected" } as unknown as ClientConnectionState;
+
+describe("gateway apply explains the first-party alternative", () => {
+  test("a stored gateway marker is named as the reason, with the command that switches", () => {
+    const lines = gatewayModeExplanation({
+      requestedExplicitly: false,
+      config: { claudeCode: { desktopProfile: { appliedFingerprint: "abc123" } } },
+      connection: disconnected,
+    });
+
+    expect(lines.join("\n")).toContain("previous gateway apply");
+    expect(lines.join("\n")).toContain("ocx claude desktop apply --first-party");
+  });
+
+  test("an explicit saved desktopMode is named as itself, not as a leftover marker", () => {
+    const lines = gatewayModeExplanation({
+      requestedExplicitly: false,
+      config: { claudeCode: { desktopMode: "gateway" } },
+      connection: disconnected,
+    });
+
+    expect(lines.join("\n")).toContain("desktopMode saved as gateway");
+  });
+
+  test("asking for gateway explicitly says nothing, because the user already chose", () => {
+    expect(gatewayModeExplanation({
+      requestedExplicitly: true,
+      config: { claudeCode: { desktopProfile: { appliedFingerprint: "abc123" } } },
+      connection: disconnected,
+    })).toEqual([]);
+  });
+
+  test("a connected client says nothing, because first-party cannot run there", () => {
+    expect(gatewayModeExplanation({
+      requestedExplicitly: false,
+      config: { claudeCode: { desktopProfile: { appliedFingerprint: "abc123" } } },
+      connection: connected,
+    })).toEqual([]);
+  });
+
+  test("a fresh machine that fell back to gateway is not told to switch to something unavailable", () => {
+    expect(gatewayModeExplanation({
+      requestedExplicitly: false,
+      config: {},
+      connection: disconnected,
+    })).toEqual([]);
+  });
+});
diff --git a/tests/claude-integration/claude-inbound.test.ts b/tests/claude-integration/claude-inbound.test.ts
index 3db1a4a6275..5631ec1271a 100644
--- a/tests/claude-integration/claude-inbound.test.ts
+++ b/tests/claude-integration/claude-inbound.test.ts
@@ -4,6 +4,7 @@ import { AnthropicRequestError as LeafAnthropicRequestError } from "../../src/cl
 import { repoPath } from "../helpers/repo-root";
 import { AnthropicRequestError, anthropicToResponsesBody, anthropicToResponsesTranslation, effortForThinkingBudget, extractOcxEffortDirective, resolveInboundModel } from "../../src/claude/inbound";
 import { parseRequest } from "../../src/responses/parser";
+import { inlineDocumentMarker } from "../../src/responses/inline-document";
 import { responsesRequestSchema } from "../../src/responses/schema";
 import { createResponsesPassthroughAdapter } from "../../src/adapters/openai-responses";
 import { withTestTranslatorBudget } from "../helpers/translator-budget";
@@ -180,7 +181,7 @@ describe("claude inbound translation", () => {
             { role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content }] },
           ],
       });
-      const marker = [{ type: "input_text", text: "[document: report.pdf]" }];
+      const marker = [{ type: "input_text", text: inlineDocumentMarker("report.pdf") }];
       expect(body.input).toEqual(carrier === "user"
         ? [{ type: "message", role: "user", content: marker }]
         : [
@@ -437,11 +438,11 @@ describe("claude inbound translation", () => {
     }) as any;
     expect(body.input[1].output).toEqual([
       { type: "input_text", text: "3 pages" },
-      { type: "input_text", text: "[document: report.pdf]" },
+      { type: "input_text", text: inlineDocumentMarker("report.pdf") },
     ]);
     // An untitled document still leaves a marker rather than the empty output that
     // read as "the tool returned nothing".
-    expect(body.input[3].output).toEqual([{ type: "input_text", text: "[document]" }]);
+    expect(body.input[3].output).toEqual([{ type: "input_text", text: inlineDocumentMarker(undefined) }]);
     expect(() => parseRequest(body)).not.toThrow();
   });
 
diff --git a/tests/claude-integration/claude-intercept-local-ca.test.ts b/tests/claude-integration/claude-intercept-local-ca.test.ts
new file mode 100644
index 00000000000..474b25a1f7e
--- /dev/null
+++ b/tests/claude-integration/claude-intercept-local-ca.test.ts
@@ -0,0 +1,75 @@
+import { expect, test } from "bun:test";
+import { X509Certificate } from "node:crypto";
+import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  CLAUDE_INTERCEPT_CA_COMMON_NAME,
+  claudeInterceptCaCertPath,
+  claudeInterceptStateDir,
+  createLocalInterceptCa,
+  ensureLocalInterceptCa,
+  issueLocalInterceptLeaf,
+} from "../../src/claude/intercept/local-ca";
+
+function tmpConfigDir(): string {
+  return mkdtempSync(join(tmpdir(), "ocx-intercept-ca-"));
+}
+
+test("CA certificate is a self-signed X.509 v3 authority", () => {
+  const ca = createLocalInterceptCa();
+  const cert = new X509Certificate(ca.certPem);
+  expect(cert.ca).toBe(true);
+  expect(cert.subject).toContain(`CN=${CLAUDE_INTERCEPT_CA_COMMON_NAME}`);
+  expect(cert.issuer).toBe(cert.subject);
+  expect(cert.verify(ca.publicKey)).toBe(true);
+  expect(cert.checkIssued(cert)).toBe(true);
+  expect(new Date(cert.validFrom).getTime()).toBeLessThan(Date.now());
+  expect(new Date(cert.validTo).getTime()).toBeGreaterThan(Date.now() + 365 * 24 * 3600 * 1000);
+});
+
+test("leaf is issued by the CA and names every requested host in SAN", () => {
+  const ca = createLocalInterceptCa();
+  const leaf = issueLocalInterceptLeaf(ca, ["api.anthropic.com", "example.test"]);
+  const cert = new X509Certificate(leaf.certPem);
+  const caCert = new X509Certificate(ca.certPem);
+  expect(cert.ca).toBe(false);
+  expect(cert.checkIssued(caCert)).toBe(true);
+  expect(cert.verify(ca.publicKey)).toBe(true);
+  expect(cert.checkHost("api.anthropic.com")).toBe("api.anthropic.com");
+  expect(cert.checkHost("example.test")).toBe("example.test");
+  expect(cert.checkHost("other.example")).toBeUndefined();
+  expect(cert.keyUsage).toContain("1.3.6.1.5.5.7.3.1");
+  expect(leaf.keyPem).toContain("PRIVATE KEY");
+});
+
+test("two CAs never share a serial or key", () => {
+  const a = createLocalInterceptCa();
+  const b = createLocalInterceptCa();
+  expect(new X509Certificate(a.certPem).serialNumber).not.toBe(new X509Certificate(b.certPem).serialNumber);
+  expect(a.keyPem).not.toBe(b.keyPem);
+});
+
+test("ensureLocalInterceptCa persists once and reloads the same authority", () => {
+  const configDir = tmpConfigDir();
+  const first = ensureLocalInterceptCa(configDir);
+  const second = ensureLocalInterceptCa(configDir);
+  expect(second.certPem).toBe(first.certPem);
+  expect(second.keyPem).toBe(first.keyPem);
+  expect(readFileSync(claudeInterceptCaCertPath(configDir), "utf8")).toBe(first.certPem);
+  if (process.platform !== "win32") {
+    expect(statSync(join(claudeInterceptStateDir(configDir), "ca.key")).mode & 0o777).toBe(0o600);
+    expect(statSync(claudeInterceptCaCertPath(configDir)).mode & 0o777).toBe(0o644);
+    expect(statSync(claudeInterceptStateDir(configDir)).mode & 0o777).toBe(0o700);
+  }
+});
+
+test("a corrupt private key regenerates the authority instead of throwing", () => {
+  const configDir = tmpConfigDir();
+  const first = ensureLocalInterceptCa(configDir);
+  writeFileSync(join(claudeInterceptStateDir(configDir), "ca.key"), "not a key\n");
+  const regenerated = ensureLocalInterceptCa(configDir);
+  expect(regenerated.certPem).not.toBe(first.certPem);
+  expect(new X509Certificate(regenerated.certPem).ca).toBe(true);
+  expect(readFileSync(claudeInterceptCaCertPath(configDir), "utf8")).toBe(regenerated.certPem);
+});
diff --git a/tests/claude-integration/claude-intercept-proxy.test.ts b/tests/claude-integration/claude-intercept-proxy.test.ts
new file mode 100644
index 00000000000..c9b6db3fb33
--- /dev/null
+++ b/tests/claude-integration/claude-intercept-proxy.test.ts
@@ -0,0 +1,184 @@
+import { afterAll, expect, test } from "bun:test";
+import { connect, createServer } from "node:net";
+import { CLAUDE_INTERCEPT_HOSTS, isLoopbackTarget, parseConnectRequestLine, startConnectProxy, type ConnectProxyHandle } from "../../src/claude/intercept/connect-proxy";
+import { startClaudeInterceptListener, rewriteInterceptedRequest } from "../../src/claude/intercept/listener";
+import { createLocalInterceptCa, issueLocalInterceptLeaf } from "../../src/claude/intercept/local-ca";
+
+/**
+ * End-to-end shape of the intercept pair: a client that only knows `HTTPS_PROXY` and trusts the
+ * local CA reaches the router's Messages handler for `api.anthropic.com`, while every other
+ * CONNECT target is relayed blind. No real network: the "upstream" for blind tunnels is a local
+ * echo socket and the relay target for non-Messages paths is a local Bun server.
+ */
+
+const cleanups: Array<() => Promise<void> | void> = [];
+afterAll(async () => {
+  for (const cleanup of cleanups.reverse()) await cleanup();
+});
+
+test("parseConnectRequestLine accepts host:port and bracketed IPv6, rejects the rest", () => {
+  expect(parseConnectRequestLine("CONNECT api.anthropic.com:443 HTTP/1.1\r\nHost: x")).toEqual({ host: "api.anthropic.com", port: 443 });
+  expect(parseConnectRequestLine("CONNECT API.Anthropic.COM.:443 HTTP/1.0")).toEqual({ host: "api.anthropic.com", port: 443 });
+  expect(parseConnectRequestLine("CONNECT [::1]:8443 HTTP/1.1")).toEqual({ host: "::1", port: 8443 });
+  expect(parseConnectRequestLine("GET http://example.com/ HTTP/1.1")).toBeNull();
+  expect(parseConnectRequestLine("CONNECT example.com HTTP/1.1")).toBeNull();
+  expect(parseConnectRequestLine("CONNECT example.com:99999 HTTP/1.1")).toBeNull();
+});
+
+function rawRequest(port: number, payload: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const socket = connect({ host: "127.0.0.1", port }, () => socket.write(payload));
+    let out = "";
+    socket.on("data", chunk => { out += chunk.toString("latin1"); });
+    socket.on("end", () => resolve(out));
+    socket.on("close", () => resolve(out));
+    socket.on("error", reject);
+  });
+}
+
+async function startEchoUpstream(): Promise<{ port: number; close(): Promise<void> }> {
+  const server = createServer(socket => socket.on("data", chunk => socket.write(`echo:${chunk.toString()}`)));
+  await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  const port = address && typeof address === "object" ? address.port : 0;
+  return { port, close: () => new Promise(resolve => server.close(() => resolve())) };
+}
+
+async function startPair(): Promise<{ proxy: ConnectProxyHandle; ca: ReturnType<typeof createLocalInterceptCa>; seen: Request[]; relayHits: string[] }> {
+  const ca = createLocalInterceptCa();
+  const leaf = issueLocalInterceptLeaf(ca, CLAUDE_INTERCEPT_HOSTS);
+  const seen: Request[] = [];
+  const relayHits: string[] = [];
+  const fakeUpstream = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    fetch(req) {
+      relayHits.push(`${req.method} ${new URL(req.url).pathname} host=${req.headers.get("host")}`);
+      return new Response(JSON.stringify({ relayed: true }), { headers: { "content-type": "application/json", "x-upstream": "fake" } });
+    },
+  });
+  cleanups.push(() => fakeUpstream.stop(true));
+  const listener = startClaudeInterceptListener({
+    leaf,
+    upstreamBase: `http://127.0.0.1:${fakeUpstream.port}`,
+    dispatch: async req => {
+      seen.push(req);
+      const body = await req.text();
+      return Response.json({ dispatched: true, url: req.url, host: req.headers.get("host"), body });
+    },
+  });
+  cleanups.push(() => listener.stop(true));
+  const echo = await startEchoUpstream();
+  cleanups.push(echo.close);
+  const proxy = await startConnectProxy(0, {
+    interceptPort: listener.port!,
+    dialUpstream: (host, port) => {
+      expect(host).toBe("telemetry.example");
+      expect(port).toBe(443);
+      return connect({ host: "127.0.0.1", port: echo.port });
+    },
+  });
+  cleanups.push(proxy.close);
+  return { proxy, ca, seen, relayHits };
+}
+
+/** Speak HTTPS to `api.anthropic.com` through the CONNECT proxy, trusting only the local CA. */
+async function viaProxy(proxyPort: number, caPem: string, method: string, path: string, body?: string): Promise<{ status: number; headers: Headers; body: string }> {
+  const res = await fetch(`https://api.anthropic.com${path}`, {
+    method,
+    headers: { "content-type": "application/json", "x-api-key": "sk-ant-test" },
+    body,
+    proxy: `http://127.0.0.1:${proxyPort}`,
+    tls: { ca: caPem },
+  });
+  return { status: res.status, headers: res.headers, body: await res.text() };
+}
+
+test("CONNECT api.anthropic.com terminates TLS locally and dispatches Messages to the router", async () => {
+  const { proxy, ca, seen } = await startPair();
+  const res = await viaProxy(proxy.port, ca.certPem, "POST", "/v1/messages?beta=true", JSON.stringify({ model: "claude-x" }));
+  expect(res.status).toBe(200);
+  const json = JSON.parse(res.body) as { dispatched: boolean; url: string; host: string; body: string };
+  expect(json.dispatched).toBe(true);
+  expect(json.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/v1\/messages\?beta=true$/);
+  expect(json.host).toMatch(/^127\.0\.0\.1:\d+$/);
+  expect(json.body).toBe(JSON.stringify({ model: "claude-x" }));
+  expect(seen).toHaveLength(1);
+  expect(seen[0]!.headers.get("x-api-key")).toBe("sk-ant-test");
+});
+
+test("non-Messages paths on the intercepted host are relayed to upstream, not dispatched", async () => {
+  const { proxy, ca, seen, relayHits } = await startPair();
+  const res = await viaProxy(proxy.port, ca.certPem, "GET", "/v1/models?limit=1");
+  expect(res.status).toBe(200);
+  expect(JSON.parse(res.body)).toEqual({ relayed: true });
+  expect(res.headers.get("x-upstream")).toBe("fake");
+  expect(relayHits).toEqual(["GET /v1/models host=127.0.0.1:" + relayHits[0]!.split(":").pop()]);
+  expect(seen).toHaveLength(0);
+});
+
+test("GET on /v1/messages is relayed rather than dispatched", async () => {
+  const { proxy, ca, seen, relayHits } = await startPair();
+  await viaProxy(proxy.port, ca.certPem, "GET", "/v1/messages");
+  expect(seen).toHaveLength(0);
+  expect(relayHits[0]).toStartWith("GET /v1/messages ");
+});
+
+test("other CONNECT targets are relayed blind, including pipelined bytes after the head", async () => {
+  const { proxy } = await startPair();
+  const out = await new Promise<string>((resolve, reject) => {
+    const socket = connect({ host: "127.0.0.1", port: proxy.port }, () => {
+      socket.write("CONNECT telemetry.example:443 HTTP/1.1\r\nHost: telemetry.example:443\r\n\r\nhello");
+    });
+    let buf = "";
+    socket.on("data", chunk => {
+      buf += chunk.toString("latin1");
+      if (buf.includes("echo:hello")) { socket.end(); resolve(buf); }
+    });
+    socket.on("error", reject);
+  });
+  expect(out.startsWith("HTTP/1.1 200 Connection Established\r\n\r\n")).toBe(true);
+  expect(out).toContain("echo:hello");
+});
+
+test("plain proxied HTTP, loopback targets and oversized heads are refused", async () => {
+  const { proxy } = await startPair();
+  expect(await rawRequest(proxy.port, "GET http://example.com/ HTTP/1.1\r\nHost: example.com\r\n\r\n")).toStartWith("HTTP/1.1 405");
+  expect(await rawRequest(proxy.port, "CONNECT 127.0.0.1:22 HTTP/1.1\r\n\r\n")).toStartWith("HTTP/1.1 403");
+  expect(await rawRequest(proxy.port, "CONNECT localhost:443 HTTP/1.1\r\n\r\n")).toStartWith("HTTP/1.1 403");
+  expect(await rawRequest(proxy.port, "CONNECT [::ffff:127.0.0.1]:22 HTTP/1.1\r\n\r\n")).toStartWith("HTTP/1.1 403");
+  expect(await rawRequest(proxy.port, `CONNECT a:443 HTTP/1.1\r\nX: ${"y".repeat(9000)}`)).toStartWith("HTTP/1.1 431");
+});
+
+test("isLoopbackTarget covers mapped, unspecified and shorthand loopback literals", () => {
+  for (const host of ["localhost", "foo.localhost", "127.0.0.1", "127.255.0.9", "::1", "::ffff:127.0.0.1", "::ffff:7f00:1", "0.0.0.0", "::", "127.1", "0x7f000001", "2130706433"]) {
+    expect(isLoopbackTarget(host)).toBe(true);
+  }
+  for (const host of ["api.anthropic.com", "10.0.0.1", "::ffff:10.0.0.1", "2606:4700::1", "1.example"]) {
+    expect(isLoopbackTarget(host)).toBe(false);
+  }
+});
+
+test("a dead upstream yields 502 instead of a hung tunnel", async () => {
+  const dead = await startEchoUpstream();
+  await dead.close();
+  const proxy = await startConnectProxy(0, {
+    interceptPort: 1,
+    dialUpstream: () => connect({ host: "127.0.0.1", port: dead.port }),
+  });
+  cleanups.push(proxy.close);
+  expect(await rawRequest(proxy.port, "CONNECT gone.example:443 HTTP/1.1\r\n\r\n")).toStartWith("HTTP/1.1 502");
+});
+
+test("rewriteInterceptedRequest moves the request onto the loopback origin and keeps path, query and headers", () => {
+  const original = new Request("https://api.anthropic.com/v1/messages?x=1", {
+    method: "POST",
+    headers: { "anthropic-version": "2023-06-01", host: "api.anthropic.com" },
+    body: "{}",
+  });
+  const rewritten = rewriteInterceptedRequest(original, "http://127.0.0.1:4567");
+  expect(rewritten.url).toBe("http://127.0.0.1:4567/v1/messages?x=1");
+  expect(rewritten.headers.get("host")).toBe("127.0.0.1:4567");
+  expect(rewritten.headers.get("anthropic-version")).toBe("2023-06-01");
+  expect(rewritten.method).toBe("POST");
+});
diff --git a/tests/claude-integration/claude-intercept-settings.test.ts b/tests/claude-integration/claude-intercept-settings.test.ts
new file mode 100644
index 00000000000..81ad3cb6b9a
--- /dev/null
+++ b/tests/claude-integration/claude-intercept-settings.test.ts
@@ -0,0 +1,112 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  applyClaudeInterceptSettings,
+  buildClaudeInterceptEnv,
+  inspectClaudeInterceptSettings,
+  removeClaudeInterceptSettings,
+} from "../../src/claude/intercept/settings";
+import { claudeInterceptEnabled, claudeInterceptProxyPort } from "../../src/claude/intercept/runtime";
+import { configSchema } from "../../src/config/schema/config-schema";
+
+const CA = "/home/u/.opencodex/claude-intercept/ca.pem";
+const env = buildClaudeInterceptEnv(8846, CA);
+
+function dir(): string {
+  return mkdtempSync(join(tmpdir(), "ocx-intercept-settings-"));
+}
+
+function readSettings(configDir: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(configDir, "settings.json"), "utf8")) as Record<string, unknown>;
+}
+
+test("env block shape", () => {
+  expect(env).toEqual({ HTTPS_PROXY: "http://127.0.0.1:8846", NODE_EXTRA_CA_CERTS: CA });
+});
+
+test("apply creates settings.json when absent and is idempotent", () => {
+  const configDir = dir();
+  expect(inspectClaudeInterceptSettings(env, configDir)).toEqual({ kind: "absent" });
+  expect(applyClaudeInterceptSettings(env, configDir)).toMatchObject({ ok: true, changed: true });
+  expect(readSettings(configDir)).toEqual({ env });
+  expect(applyClaudeInterceptSettings(env, configDir)).toMatchObject({ ok: true, changed: false });
+  expect(inspectClaudeInterceptSettings(env, configDir)).toEqual({ kind: "applied", env });
+});
+
+test("apply preserves unrelated settings and env keys", () => {
+  const configDir = dir();
+  writeFileSync(join(configDir, "settings.json"), JSON.stringify({ model: "opus", env: { ANTHROPIC_MODEL: "gpt-x", FOO: "1" }, permissions: { allow: [] } }));
+  applyClaudeInterceptSettings(env, configDir);
+  expect(readSettings(configDir)).toEqual({
+    model: "opus",
+    env: { ANTHROPIC_MODEL: "gpt-x", FOO: "1", ...env },
+    permissions: { allow: [] },
+  });
+});
+
+test("a previous port is stale and gets rewritten; a foreign proxy is left alone", () => {
+  const configDir = dir();
+  writeFileSync(join(configDir, "settings.json"), JSON.stringify({ env: { HTTPS_PROXY: "http://127.0.0.1:9000", NODE_EXTRA_CA_CERTS: CA } }));
+  expect(inspectClaudeInterceptSettings(env, configDir)).toEqual({ kind: "stale", env: { HTTPS_PROXY: "http://127.0.0.1:9000", NODE_EXTRA_CA_CERTS: CA } });
+  expect(applyClaudeInterceptSettings(env, configDir)).toMatchObject({ ok: true, changed: true });
+  expect(readSettings(configDir)).toEqual({ env });
+
+  const foreign = dir();
+  writeFileSync(join(foreign, "settings.json"), JSON.stringify({ env: { HTTPS_PROXY: "http://corp-proxy:3128" } }));
+  expect(inspectClaudeInterceptSettings(env, foreign).kind).toBe("foreign");
+  expect(applyClaudeInterceptSettings(env, foreign)).toMatchObject({ ok: false, reason: "foreign_env" });
+  expect(readSettings(foreign)).toEqual({ env: { HTTPS_PROXY: "http://corp-proxy:3128" } });
+
+  // A loopback proxy with someone else's CA is not ours either.
+  const otherCa = dir();
+  writeFileSync(join(otherCa, "settings.json"), JSON.stringify({ env: { HTTPS_PROXY: "http://127.0.0.1:8080", NODE_EXTRA_CA_CERTS: "/etc/mitm/ca.pem" } }));
+  expect(inspectClaudeInterceptSettings(env, otherCa).kind).toBe("foreign");
+});
+
+test("remove deletes only owned values and drops an emptied env block", () => {
+  const configDir = dir();
+  writeFileSync(join(configDir, "settings.json"), JSON.stringify({ model: "opus", env: { ...env } }));
+  expect(removeClaudeInterceptSettings(CA, configDir)).toMatchObject({ ok: true, changed: true });
+  expect(readSettings(configDir)).toEqual({ model: "opus" });
+  expect(removeClaudeInterceptSettings(CA, configDir)).toMatchObject({ ok: true, changed: false });
+
+  const foreign = dir();
+  writeFileSync(join(foreign, "settings.json"), JSON.stringify({ env: { HTTPS_PROXY: "http://127.0.0.1:8080", NODE_EXTRA_CA_CERTS: "/etc/mitm/ca.pem" } }));
+  expect(removeClaudeInterceptSettings(CA, foreign)).toMatchObject({ ok: true, changed: false });
+  expect(readSettings(foreign)).toEqual({ env: { HTTPS_PROXY: "http://127.0.0.1:8080", NODE_EXTRA_CA_CERTS: "/etc/mitm/ca.pem" } });
+
+  const missing = dir();
+  expect(removeClaudeInterceptSettings(CA, missing)).toMatchObject({ ok: true, changed: false });
+});
+
+test("corrupt settings.json is reported, never overwritten", () => {
+  const configDir = dir();
+  writeFileSync(join(configDir, "settings.json"), "{ not json");
+  expect(inspectClaudeInterceptSettings(env, configDir).kind).toBe("unreadable");
+  expect(applyClaudeInterceptSettings(env, configDir)).toMatchObject({ ok: false, reason: "unreadable" });
+  expect(removeClaudeInterceptSettings(CA, configDir)).toMatchObject({ ok: false, reason: "unreadable" });
+  expect(readFileSync(join(configDir, "settings.json"), "utf8")).toBe("{ not json");
+});
+
+test("intercept is on by default for a hub, off for clients and when Claude Code is disabled", () => {
+  expect(claudeInterceptEnabled({})).toBe(true);
+  expect(claudeInterceptEnabled({ claudeCode: { intercept: { enabled: false } } })).toBe(false);
+  expect(claudeInterceptEnabled({ claudeCode: { enabled: false } })).toBe(false);
+  expect(claudeInterceptEnabled({ runtimeRole: "client" })).toBe(false);
+  expect(claudeInterceptProxyPort({}, 8746)).toBe(8846);
+  expect(claudeInterceptProxyPort({ claudeCode: { intercept: { port: 9100 } } }, 8746)).toBe(9100);
+  expect(claudeInterceptProxyPort({ claudeCode: { intercept: { port: 0 } } }, 8746)).toBe(8846);
+});
+
+test("claudeCode.intercept is validated by the config schema", () => {
+  const base = {
+    port: 0, defaultProvider: "openai",
+    providers: { openai: { adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex", authMode: "forward", codexAccountMode: "direct" } },
+  };
+  expect(configSchema.safeParse({ ...base, claudeCode: { intercept: { enabled: false, port: 9100 } } }).success).toBe(true);
+  expect(configSchema.safeParse({ ...base, claudeCode: { intercept: "off" } }).success).toBe(false);
+  expect(configSchema.safeParse({ ...base, claudeCode: { intercept: { enabled: "no" } } }).success).toBe(false);
+  expect(configSchema.safeParse({ ...base, claudeCode: { intercept: { port: 70000 } } }).success).toBe(false);
+});
diff --git a/tests/claude-integration/claude-management-api.test.ts b/tests/claude-integration/claude-management-api.test.ts
index 60bc012fa25..751b838ee99 100644
--- a/tests/claude-integration/claude-management-api.test.ts
+++ b/tests/claude-integration/claude-management-api.test.ts
@@ -707,7 +707,11 @@ test("Claude Desktop profile GET, PUT and apply round-trip four-family assignmen
     const discovery = await fetch(new URL("/v1/models?flavor=anthropic", server.url)).then(r => r.json()) as { data: Array<{ id: string }> };
     expect(discovery.data.some(model => model.id === alias)).toBe(true);
 
-    const apply = await fetch(new URL("/api/claude-desktop/apply", server.url), { method: "POST" });
+    const apply = await fetch(new URL("/api/claude-desktop/apply", server.url), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ mode: "gateway" }),
+    });
     expect(apply.status).toBe(200);
     const result = await apply.json() as { path: string; applied: boolean };
     expect(result.applied).toBe(true);
@@ -815,6 +819,14 @@ test("Claude Desktop apply validates the mode body", async () => {
     expect(badProfile.status).toBe(400);
     expect(loadConfig()).toEqual(beforeBadProfile);
 
+    const badGatewayProfile = await fetch(new URL("/api/claude-desktop/apply", server.url), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ mode: "gateway", profile: { version: 2 } }),
+    });
+    expect(badGatewayProfile.status).toBe(400);
+    expect(loadConfig()).toEqual(beforeBadProfile);
+
     const hybrid = await fetch(new URL("/api/claude-desktop/apply", server.url), {
       method: "POST",
       headers: { "Content-Type": "application/json" },
diff --git a/tests/claude-integration/claude-source-envelope.test.ts b/tests/claude-integration/claude-source-envelope.test.ts
index a78c9f1a152..a08b8f5e826 100644
--- a/tests/claude-integration/claude-source-envelope.test.ts
+++ b/tests/claude-integration/claude-source-envelope.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { anthropicToResponsesBody } from "../../src/claude/inbound";
+import { inlineDocumentMarker } from "../../src/responses/inline-document";
 
 describe("Claude source envelope boundaries", () => {
   test("nested tool results retain only bounded structured content", () => {
@@ -17,7 +18,7 @@ describe("Claude source envelope boundaries", () => {
     expect(body.input.map((item: any) => item.type)).toEqual(["function_call", "function_call_output"]);
     expect(body.input[1].output).toEqual([
       { type: "input_text", text: "ok" },
-      { type: "input_text", text: "[document: report]" },
+      { type: "input_text", text: inlineDocumentMarker("report") },
     ]);
     expect(JSON.stringify(body)).not.toContain("secret-payload");
   });
diff --git a/tests/cli/cli-catalog-prewarm.test.ts b/tests/cli/cli-catalog-prewarm.test.ts
index e2c1af3e1fa..2c9cdd3aa67 100644
--- a/tests/cli/cli-catalog-prewarm.test.ts
+++ b/tests/cli/cli-catalog-prewarm.test.ts
@@ -53,18 +53,18 @@ describe("catalog prewarm on handleStart bind", () => {
     }
   });
 
-  test("handleStart schedules catalog prewarm immediately after a successful bind", async () => {
+  test("handleStart schedules catalog prewarm after ownership publication", async () => {
     const cli = (await readText("src/cli/index.ts")).replace(/\r\n/g, "\n");
-    const bindIdx = cli.indexOf("server = startServer(port");
+    const transactionIdx = cli.indexOf("boundStart = await bindAndPublishStartOwnership({");
+    const publishedIdx = cli.indexOf("const { server, serverModule, port, readinessGate, config } = boundStart", transactionIdx);
     const prewarmIdx = cli.indexOf("scheduleCatalogPrewarm()");
-    const breakIdx = cli.indexOf("\n      break;", bindIdx);
+    const guardianIdx = cli.indexOf("const guardian = startTokenGuardian()", prewarmIdx);
 
     expect(cli).toContain('from "./catalog-prewarm"');
-    expect(bindIdx).toBeGreaterThan(-1);
-    expect(prewarmIdx).toBeGreaterThan(bindIdx);
-    expect(breakIdx).toBeGreaterThan(prewarmIdx);
-    // Must stay inside the successful-bind try path, not only on a later sync.
-    expect(cli.slice(bindIdx, breakIdx)).toContain("scheduleCatalogPrewarm()");
+    expect(transactionIdx).toBeGreaterThan(-1);
+    expect(publishedIdx).toBeGreaterThan(transactionIdx);
+    expect(prewarmIdx).toBeGreaterThan(publishedIdx);
+    expect(guardianIdx).toBeGreaterThan(prewarmIdx);
     expect(cli).not.toContain('void import("../codex/catalog").then(({ gatherRoutedModels })');
   });
 });
diff --git a/tests/cli/cli-companion.test.ts b/tests/cli/cli-companion.test.ts
new file mode 100644
index 00000000000..2f3d361bacb
--- /dev/null
+++ b/tests/cli/cli-companion.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { handleCompanionCommand } from "../../src/cli/companion";
+
+describe("ocx companion", () => {
+  test("set parses JSON values and reset sends the matching management payload", async () => {
+    const requests: Array<{ path: string; method: string; body: unknown }> = [];
+    const deps = {
+      baseUrl: "http://proxy.test",
+      fetchImpl: async (input: RequestInfo | URL, init?: RequestInit) => {
+        const body = init?.body ? JSON.parse(String(init.body)) : null;
+        requests.push({ path: new URL(String(input)).pathname, method: init?.method ?? "GET", body });
+        return Response.json({ settings: {}, defaults: {}, updatedAt: null });
+      },
+    };
+    expect(await handleCompanionCommand(["set", "showChart=false", "chartHours=6", "menuBarTemplate=null", "--json"], deps)).toBe(0);
+    expect(requests[0]).toEqual({
+      path: "/api/companion/settings",
+      method: "PUT",
+      body: { settings: { showChart: false, chartHours: 6, menuBarTemplate: null } },
+    });
+    expect(await handleCompanionCommand(["reset"], deps)).toBe(0);
+    expect(requests[1]).toEqual({
+      path: "/api/companion/settings",
+      method: "PUT",
+      body: { reset: true },
+    });
+  });
+});
diff --git a/tests/cli/cli-dispatch.test.ts b/tests/cli/cli-dispatch.test.ts
index 7cf4877feae..83502242139 100644
--- a/tests/cli/cli-dispatch.test.ts
+++ b/tests/cli/cli-dispatch.test.ts
@@ -407,13 +407,12 @@ describe("a busy preferred port never becomes a second proxy (#5004)", () => {
     // One 750ms probe is what produced the duplicate; the guard spends the larger budget.
     expect(fn).toContain("START_OWNERSHIP_LIVENESS");
 
-    // Both refusals end the process, and the refusal a user sees is the one they already
-    // know from the owner path.
-    expect(fn).toMatch(/decision === "refuse-live-proxy"[\s\S]{0,400}?process\.exit\(1\)/);
+    // Both refusals preserve the exit code through the caller's lease-cleanup boundary.
+    expect(fn).toMatch(/decision === "refuse-live-proxy"[\s\S]{0,400}?StartCommandExit\(1\)/);
     expect(fn).toContain("Use 'ocx stop' first.");
-    expect(fn).toMatch(/decision === "refuse-unidentified-holder"[\s\S]{0,700}?process\.exit\(1\)/);
+    expect(fn).toMatch(/decision === "refuse-unidentified-holder"[\s\S]{0,700}?StartCommandExit\(1\)/);
     // The wrapper's `if %ERRORLEVEL% NEQ 0` loop still terminates on a served port.
-    expect(fn).toMatch(/decision === "service-stay-out"[\s\S]{0,500}?process\.exit\(0\)/);
+    expect(fn).toMatch(/decision === "service-stay-out"[\s\S]{0,500}?StartCommandExit\(0\)/);
   });
 
   test("the pre-bind owner probe spends the same budget before it deletes state", () => {
diff --git a/tests/cli/cli-effort.test.ts b/tests/cli/cli-effort.test.ts
index b80028fd027..c846442c9ac 100644
--- a/tests/cli/cli-effort.test.ts
+++ b/tests/cli/cli-effort.test.ts
@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { handleEffortCommand } from "../../src/cli/effort";
 import { dispatchCommand } from "../../src/cli/dispatch";
 import type { CliDispatchDeps } from "../../src/cli/dispatch";
+import { summarizeStopRun } from "../../src/cli/stop-report";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
 import type { OcxConfig } from "../../src/types";
 
@@ -77,8 +78,17 @@ function fakeDeps(args: string[] = []): {
     startArgv: () => [],
     spawnDetached: () => {},
     handleStart: async () => {},
-    handleStop: async () => true,
+    // The effort runner never reaches stop; the fake only has to satisfy the typed
+    // interface, so reuse the real summarizer rather than restating the shape.
+    handleStop: async () => ({
+      ok: true,
+      summary: summarizeStopRun(
+        { service: "absent", proxy: "not-running", sharedTeardown: "skipped", inheritedTeardownBlocks: false, receiptClearFailed: false },
+        { failed: false, historyOnly: false, historyDeferred: false, exitCode: 0 },
+      ),
+    }),
     handleEnsure: async () => true,
+    handleResolve: async () => 0,
     handleTrayProxyStart: async () => true,
     handleTrayProxyRestart: async () => {},
     handleRestartStartWhenStopped: async () => true,
diff --git a/tests/cli/cli-headless-parity.test.ts b/tests/cli/cli-headless-parity.test.ts
index c8b7257a8d0..27e9f657ff8 100644
--- a/tests/cli/cli-headless-parity.test.ts
+++ b/tests/cli/cli-headless-parity.test.ts
@@ -404,6 +404,7 @@ describe("headless GUI parity CLI", () => {
       ["/api/logs", "ocx observe"],
       ["/api/lab", "ocx lab"],
       ["/api/config", "ocx config"],
+      ["/api/companion", "ocx companion"],
       // The client machine plane. These are served by the connected client's own loopback
       // listener rather than the hub, and each one mirrors a connect-family command:
       // status/clients -> `ocx connect status`, sync -> `ocx sync`, shim -> the client
diff --git a/tests/cli/cli-ready.test.ts b/tests/cli/cli-ready.test.ts
index 197c0ae276f..c214ecde156 100644
--- a/tests/cli/cli-ready.test.ts
+++ b/tests/cli/cli-ready.test.ts
@@ -850,19 +850,19 @@ describe("runReady production findLiveProxy deadline wiring (source-level)", ()
 describe("handleStart OCX_SERVICE exit guard (source-level)", () => {
   const cliSource = readFileSync(repoPath("src/cli/index.ts"), "utf8");
 
-  test("an already-live proxy exits 0 in OCX_SERVICE context", () => {
+  test("an already-live proxy preserves the service/refusal exit codes without bypassing cleanup", () => {
     // The `OCX_SERVICE === "1"` comparison moved into `decideStartWithLiveOwner`
     // (src/cli/dispatch.ts), where the sentinel semantics are asserted at runtime
     // across the whole matrix (tests/cli/cli-dispatch.test.ts). This oracle pins the
-    // exits that the decision routes to: stay-out exits 0, the conflict exits 1.
+    // typed exits that the decision routes to: stay-out returns 0, the conflict returns 1.
     expect(cliSource).toMatch(/decideStartWithLiveOwner\(\{/);
-    // Anchored at the owner branch. `chooseListenPort` carries its own stay-out/refusal pair
-    // for the busy-port guard (#5004) and it sits EARLIER in the file, so an unanchored match
-    // would quietly move to that one and stop asserting anything about this branch.
-    const ownerBranch = cliSource.slice(cliSource.indexOf("decideStartWithLiveOwner({"));
-    const stayOut = ownerBranch.match(/decision === "service-stay-out"[\s\S]{0,800}?process\.exit\(0\)/);
-    expect(stayOut, "the service stay-out decision must exit 0 when the port is already served").not.toBeNull();
-    const nonService = ownerBranch.match(/Proxy already running[\s\S]{0,300}?process\.exit\(1\)/);
+    // Anchor after the lease transaction begins. The earlier preflight has the same decision
+    // pair but does not need a typed exit because it owns no lease yet.
+    const transaction = cliSource.slice(cliSource.indexOf("bindAndPublishStartOwnership({"));
+    const ownerBranch = transaction.slice(transaction.indexOf("decideStartWithLiveOwner({"));
+    const stayOut = ownerBranch.match(/decision === "service-stay-out"[\s\S]{0,800}?StartCommandExit\(0\)/);
+    expect(stayOut, "the service stay-out decision must return 0 when the port is already served").not.toBeNull();
+    const nonService = ownerBranch.match(/decision === "refuse"[\s\S]{0,500}?StartCommandExit\(1\)/);
     expect(nonService, "non-service refusal keeps the exit 1 conflict error").not.toBeNull();
   });
 
diff --git a/tests/cli/cli-resolve-subprocess.test.ts b/tests/cli/cli-resolve-subprocess.test.ts
new file mode 100644
index 00000000000..0015daeb079
--- /dev/null
+++ b/tests/cli/cli-resolve-subprocess.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));
+const cliPath = join(repoRoot, "src", "cli", "index.ts");
+
+interface ResolveRun {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+async function runResolveCli(args: string[], home: string): Promise<ResolveRun> {
+  const child = Bun.spawn([process.execPath, cliPath, ...args], {
+    cwd: repoRoot,
+    env: { ...process.env, OPENCODEX_HOME: home },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const timer = setTimeout(() => child.kill(), 15_000);
+  try {
+    const [exitCode, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ]);
+    return { exitCode, stdout, stderr };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+describe("ocx resolve real subprocess", () => {
+  test("a home whose configured port is closed resolves with a proven-absent verdict", async () => {
+    // Port 9 is the suite's conventional dead port (see cli-help.test.ts): the liveness
+    // fallback probes the configured port when no records exist, and on a developer
+    // machine a real proxy can answer the 10100 default — that is findLiveProxy working
+    // as designed, so the deterministic verdict case pins a closed port instead.
+    const home = mkdtempSync(join(tmpdir(), "ocx-resolve-closed-port-"));
+    try {
+      writeFileSync(join(home, "config.json"), JSON.stringify({ port: 9 }), "utf8");
+      const run = await runResolveCli(["resolve", "--json"], home);
+      expect(run.exitCode).toBe(0);
+      const parsed = JSON.parse(run.stdout) as {
+        schema: string;
+        configHome: string;
+        port: { effective: number; configured: number; source: string };
+        liveness: { status: string; pid: null; port: null; source: null };
+      };
+      expect(parsed.schema).toBe("ocx-resolve/1");
+      expect(parsed.configHome).toBe(home);
+      expect(parsed.port).toEqual({ effective: 9, configured: 9, source: "config" });
+      expect(parsed.liveness).toEqual({ status: "absent-proven", pid: null, port: null, source: null });
+    } finally {
+      removeTreeWithRetry(home);
+    }
+  });
+
+  test("a configured custom port stays the effective port while nothing is live", async () => {
+    const home = mkdtempSync(join(tmpdir(), "ocx-resolve-custom-port-"));
+    try {
+      writeFileSync(join(home, "config.json"), JSON.stringify({ port: 23456 }), "utf8");
+      const run = await runResolveCli(["resolve", "--json"], home);
+      expect(run.exitCode).toBe(0);
+      const parsed = JSON.parse(run.stdout) as { port: { effective: number; configured: number; source: string } };
+      expect(parsed.port).toEqual({ effective: 23456, configured: 23456, source: "config" });
+    } finally {
+      removeTreeWithRetry(home);
+    }
+  });
+
+  test("any argument is a usage error before preflight side effects", async () => {
+    const home = mkdtempSync(join(tmpdir(), "ocx-resolve-usage-"));
+    try {
+      const run = await runResolveCli(["resolve", "extra"], home);
+      expect(run.exitCode).toBe(64);
+      expect(run.stdout).toBe("");
+      expect(run.stderr).toContain("Usage: ocx resolve");
+    } finally {
+      removeTreeWithRetry(home);
+    }
+  });
+
+  test("help is registered for the verb", async () => {
+    const home = mkdtempSync(join(tmpdir(), "ocx-resolve-help-"));
+    try {
+      mkdirSync(home, { recursive: true });
+      const run = await runResolveCli(["help", "resolve"], home);
+      expect(run.exitCode).toBe(0);
+      expect(run.stdout).toContain("Usage: ocx resolve");
+    } finally {
+      removeTreeWithRetry(home);
+    }
+  });
+
+  test("the default form prints human output, not JSON", async () => {
+    const home = mkdtempSync(join(tmpdir(), "ocx-resolve-human-"));
+    try {
+      writeFileSync(join(home, "config.json"), JSON.stringify({ port: 9 }), "utf8");
+      const run = await runResolveCli(["resolve"], home);
+      expect(run.exitCode).toBe(0);
+      expect(run.stdout).toContain(`Config home: ${home}`);
+      expect(run.stdout).toContain("No live proxy (absence proven); effective port 9 (configured).");
+    } finally {
+      removeTreeWithRetry(home);
+    }
+  });
+
+  test("an invalid config.json is refused rather than resolved to defaults", async () => {
+    const home = mkdtempSync(join(tmpdir(), "ocx-resolve-invalid-config-"));
+    try {
+      writeFileSync(join(home, "config.json"), "{ not json", "utf8");
+      const run = await runResolveCli(["resolve", "--json"], home);
+      expect(run.exitCode).toBe(1);
+      expect(run.stdout).toBe("");
+      expect(run.stderr).toContain("refusing to guess");
+    } finally {
+      removeTreeWithRetry(home);
+    }
+  });
+});
diff --git a/tests/cli/cli-resolve.test.ts b/tests/cli/cli-resolve.test.ts
new file mode 100644
index 00000000000..a7177ff241b
--- /dev/null
+++ b/tests/cli/cli-resolve.test.ts
@@ -0,0 +1,279 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import {
+  RESOLVE_DEFAULT_PORT,
+  RESOLVE_SCHEMA,
+  buildResolveJson,
+  parseResolveArgs,
+  runResolve,
+} from "../../src/cli/resolve";
+import type { LiveProxy } from "../../src/server/proxy-liveness";
+import type { ConfigDiagnostics } from "../../src/config";
+import { repoPath } from "../helpers/repo-root";
+
+function fakeLive(overrides: Partial<LiveProxy> = {}): LiveProxy {
+  return {
+    pid: 4242,
+    port: 10110,
+    hostname: "127.0.0.1",
+    source: "runtime",
+    version: "9.9.9",
+    ...overrides,
+  };
+}
+
+describe("parseResolveArgs", () => {
+  test("accepts the bare verb and --json, rejects anything else with code 64", () => {
+    expect(parseResolveArgs([])).toEqual({ ok: true, args: { json: false } });
+    expect(parseResolveArgs(["--json"])).toEqual({ ok: true, args: { json: true } });
+    expect(parseResolveArgs(["--json", "--json"])).toEqual({ ok: true, args: { json: true } });
+    for (const argv of [["extra"], ["--wait", "5"], ["-"], ["--json", "extra"]]) {
+      expect(parseResolveArgs(argv)).toEqual({ ok: false, code: 64 });
+    }
+  });
+});
+
+describe("buildResolveJson", () => {
+  test("a live runtime-record proxy answers with its own port and identity", () => {
+    const json = buildResolveJson({ port: 12345 }, fakeLive(), "/home/fixture/.opencodex", "1.2.3");
+    expect(json).toEqual({
+      schema: RESOLVE_SCHEMA,
+      cliVersion: "1.2.3",
+      configHome: "/home/fixture/.opencodex",
+      port: { effective: 10110, configured: 12345, source: "runtime" },
+      liveness: {
+        status: "live",
+        pid: 4242,
+        port: 10110,
+        hostname: "127.0.0.1",
+        source: "runtime",
+        version: "9.9.9",
+      },
+    });
+  });
+
+  test("without a live proxy the configured port is the effective one", () => {
+    const json = buildResolveJson({ port: 12345 }, null, "/home/fixture/.opencodex", "1.2.3");
+    expect(json.port).toEqual({ effective: 12345, configured: 12345, source: "config" });
+    expect(json.liveness).toEqual({ status: "absent-proven", pid: null, port: null, source: null });
+  });
+
+  test("an absent configured port resolves to the CLI default", () => {
+    const json = buildResolveJson({}, null, "/home/fixture/.opencodex", "1.2.3");
+    expect(json.port).toEqual({
+      effective: RESOLVE_DEFAULT_PORT,
+      configured: RESOLVE_DEFAULT_PORT,
+      source: "config",
+    });
+  });
+
+  test("optional liveness identity fields are omitted, never null-coerced", () => {
+    const legacy = fakeLive({ version: undefined, role: undefined, hostname: undefined });
+    const json = buildResolveJson({}, legacy, "/h", "1.2.3");
+    expect(json.liveness).toEqual({
+      status: "live",
+      pid: 4242,
+      port: 10110,
+      source: "runtime",
+    });
+  });
+});
+
+describe("runResolve", () => {
+  test("prints exactly one JSON document and exits 0 for a live proxy", async () => {
+    const lines: string[] = [];
+    const errors: string[] = [];
+    const code = await runResolve({ json: true }, {
+      configDir: () => "/home/fixture/.opencodex",
+      readDiagnostics: () => ({ config: { port: 12345 }, source: "file", error: null } as ConfigDiagnostics),
+      findLive: async () => fakeLive(),
+      cliVersion: () => "1.2.3",
+      stdout: { log: value => lines.push(value) },
+      stderr: { error: value => errors.push(value) },
+    });
+    expect(code).toBe(0);
+    expect(errors).toEqual([]);
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0]!)).toEqual({
+      schema: RESOLVE_SCHEMA,
+      cliVersion: "1.2.3",
+      configHome: "/home/fixture/.opencodex",
+      port: { effective: 10110, configured: 12345, source: "runtime" },
+      liveness: {
+        status: "live",
+        pid: 4242,
+        port: 10110,
+        hostname: "127.0.0.1",
+        source: "runtime",
+        version: "9.9.9",
+      },
+    });
+  });
+
+  test("a proven-absent verdict is a successful answer, not a failure", async () => {
+    const lines: string[] = [];
+    const code = await runResolve({ json: true }, {
+      configDir: () => "/h",
+      readDiagnostics: () => ({ config: {}, source: "default", error: null } as ConfigDiagnostics),
+      findLive: async () => null,
+      readRuntime: () => null,
+      probeEndpoint: () => "dead",
+      cliVersion: () => "1.2.3",
+      stdout: { log: value => lines.push(value) },
+    });
+    expect(code).toBe(0);
+    const parsed = JSON.parse(lines[0]!) as { liveness: { status: string }; port: { effective: number } };
+    expect(parsed.liveness.status).toBe("absent-proven");
+    expect(parsed.port.effective).toBe(RESOLVE_DEFAULT_PORT);
+  });
+
+  test("accepts async dead probes for every candidate endpoint", async () => {
+    const lines: string[] = [];
+    const code = await runResolve({ json: true }, {
+      configDir: () => "/h",
+      readDiagnostics: () => ({ config: {}, source: "default", error: null } as ConfigDiagnostics),
+      findLive: async () => null,
+      readRuntime: () => ({ port: 10110, hostname: "127.0.0.1" }),
+      probeEndpoint: async () => "dead",
+      cliVersion: () => "1.2.3",
+      stdout: { log: value => lines.push(value) },
+    });
+    expect(code).toBe(0);
+    expect((JSON.parse(lines[0]!) as { liveness: { status: string } }).liveness.status).toBe("absent-proven");
+  });
+
+  test("an undecidable probe is unknown, and unknown is never answered as absent", async () => {
+    // The launch decision keys on this verdict: a timed-out probe or a listener that
+    // withholds /healthz must exit 1 rather than let the caller start a second runtime.
+    for (const probeEndpoint of [() => "unknown" as const, () => { throw new Error("spawn unavailable"); }]) {
+      const lines: string[] = [];
+      const errors: string[] = [];
+      const code = await runResolve({ json: true }, {
+        configDir: () => "/h",
+        readDiagnostics: () => ({ config: {}, source: "default", error: null } as ConfigDiagnostics),
+        findLive: async () => null,
+        readRuntime: () => null,
+        probeEndpoint,
+        cliVersion: () => "1.2.3",
+        stdout: { log: value => lines.push(value) },
+        stderr: { error: value => errors.push(value) },
+      });
+      expect(code).toBe(1);
+      expect(lines).toEqual([]);
+      expect(errors.join("\n")).toContain("unknown");
+    }
+  });
+
+  test("absence requires every endpoint dead, not just the configured one", async () => {
+    // The runtime record can point at a live port while the configured port refuses;
+    // answering from the configured port alone would shadow-start over the record.
+    // Every candidate is probed: an unknown runtime endpoint defeats the proof even when the
+    // configured endpoint is dead.
+    const seen: string[] = [];
+    const code = await runResolve({ json: true }, {
+      configDir: () => "/h",
+      readDiagnostics: () => ({ config: { port: 10100 }, source: "file", error: null } as ConfigDiagnostics),
+      findLive: async () => null,
+      readRuntime: () => ({ port: 10110, hostname: "127.0.0.1" }),
+      probeEndpoint: endpoint => { seen.push(String(endpoint.port)); return endpoint.port === 10110 ? "unknown" : "dead"; },
+      cliVersion: () => "1.2.3",
+      stdout: { log: () => {} },
+      stderr: { error: () => {} },
+    });
+    expect(code).toBe(1);
+    expect(seen).toContain("10110");
+  });
+
+  test("proven absent probes both the runtime record and the configured port", async () => {
+    const seen: string[] = [];
+    const lines: string[] = [];
+    const code = await runResolve({ json: true }, {
+      configDir: () => "/h",
+      readDiagnostics: () => ({ config: { port: 10100 }, source: "file", error: null } as ConfigDiagnostics),
+      findLive: async () => null,
+      readRuntime: () => ({ port: 10110, hostname: "127.0.0.1" }),
+      probeEndpoint: endpoint => { seen.push(String(endpoint.port)); return "dead"; },
+      cliVersion: () => "1.2.3",
+      stdout: { log: value => lines.push(value) },
+    });
+    expect(code).toBe(0);
+    expect(seen).toEqual(["10110", "10100"]);
+    expect((JSON.parse(lines[0]!) as { liveness: { status: string } }).liveness.status).toBe("absent-proven");
+  });
+
+  test("a config read failure exits 1 with nothing on stdout", async () => {
+    const lines: string[] = [];
+    const errors: string[] = [];
+    const code = await runResolve({ json: true }, {
+      configDir: () => "/h",
+      readDiagnostics: () => { throw new Error("config.json is not readable"); },
+      findLive: async () => null,
+      cliVersion: () => "1.2.3",
+      stdout: { log: value => lines.push(value) },
+      stderr: { error: value => errors.push(value) },
+    });
+    expect(code).toBe(1);
+    expect(lines).toEqual([]);
+    expect(errors.join("\n")).toContain("config.json is not readable");
+  });
+
+  test("an invalid config is refused, not repaired to defaults", async () => {
+    // loadConfig repairs a broken config to factory defaults; a shell contract must not
+    // answer 10100 for a config the operator pointed at another port. The diagnostics
+    // surface distinguishes that case (source "fallback") so resolve can exit 1.
+    const lines: string[] = [];
+    const errors: string[] = [];
+    let probed = false;
+    const code = await runResolve({ json: true }, {
+      configDir: () => "/h",
+      readDiagnostics: () => ({ config: {}, source: "fallback", error: "invalid_json" } as ConfigDiagnostics),
+      findLive: async () => { probed = true; return null; },
+      cliVersion: () => "1.2.3",
+      stdout: { log: value => lines.push(value) },
+      stderr: { error: value => errors.push(value) },
+    });
+    expect(code).toBe(1);
+    expect(lines).toEqual([]);
+    expect(errors.join("\n")).toContain("refusing to guess");
+    // No liveness probe may run against a guessed port.
+    expect(probed).toBe(false);
+  });
+
+  test("the production default probes with the ownership-safe budget", () => {
+    // Source oracle: the verdict feeds the shell's launch decision, so it borrows the
+    // start path's START_OWNERSHIP_LIVENESS budget instead of the 750ms single probe.
+    const src = readFileSync(repoPath("src", "cli", "resolve.ts"), "utf8");
+    expect(src).toContain("findLiveProxy(START_OWNERSHIP_LIVENESS)");
+  });
+
+  test("the default output is two human lines, never JSON", async () => {
+    const lines: string[] = [];
+    const code = await runResolve({ json: false }, {
+      configDir: () => "/home/fixture/.opencodex",
+      readDiagnostics: () => ({ config: { port: 12345 }, source: "file", error: null } as ConfigDiagnostics),
+      findLive: async () => fakeLive(),
+      cliVersion: () => "1.2.3",
+      stdout: { log: value => lines.push(value) },
+    });
+    expect(code).toBe(0);
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toBe("Config home: /home/fixture/.opencodex");
+    expect(lines[1]).toContain("Proxy live on port 10110 (PID 4242, 9.9.9)");
+    expect(lines.every(line => { try { JSON.parse(line); return false; } catch { return true; } })).toBe(true);
+  });
+
+  test("human output for a proven-absent verdict names the effective port", async () => {
+    const lines: string[] = [];
+    const code = await runResolve({ json: false }, {
+      configDir: () => "/h",
+      readDiagnostics: () => ({ config: {}, source: "default", error: null } as ConfigDiagnostics),
+      findLive: async () => null,
+      readRuntime: () => null,
+      probeEndpoint: () => "dead",
+      cliVersion: () => "1.2.3",
+      stdout: { log: value => lines.push(value) },
+    });
+    expect(code).toBe(0);
+    expect(lines[1]).toBe(`No live proxy (absence proven); effective port ${RESOLVE_DEFAULT_PORT} (configured).`);
+  });
+});
diff --git a/tests/cli/cli-restore-back.test.ts b/tests/cli/cli-restore-back.test.ts
index a750ae8ee92..a25461bd3c6 100644
--- a/tests/cli/cli-restore-back.test.ts
+++ b/tests/cli/cli-restore-back.test.ts
@@ -185,6 +185,14 @@ describe("ocx restore back", () => {
       const restoreHelp = runCli(["help", "restore"], env);
       expect(restoreHelp.status).toBe(0);
       expect(`${restoreHelp.stdout}\n${restoreHelp.stderr}`).toContain("ocx restore [back]");
+      // #4812 left the escape hatch undiscoverable: the flag worked, but no help text named
+      // it, so a user whose paginated restore kept the provider table had nothing to read.
+      // Read the flag out of the parser rather than restating it, so a rename cannot pass.
+      const parsed = readFileSync(join(repoRoot, "src", "cli", "dispatch.ts"), "utf8")
+        .match(/const removeProviderTable = takeFlag\(restoreArgs, "(--[a-z-]+)"\)/)?.[1];
+      expect(parsed).toBeTruthy();
+      expect(`${restoreHelp.stdout}\n${restoreHelp.stderr}`).toContain(parsed!);
+      expect(`${usage.stdout}\n${usage.stderr}`).toContain(parsed!);
     } finally {
       removeTreeWithRetry(codexHome);
       removeTreeWithRetry(ocxHome);
diff --git a/tests/cli/cli-stop-json.test.ts b/tests/cli/cli-stop-json.test.ts
new file mode 100644
index 00000000000..2ea64a40713
--- /dev/null
+++ b/tests/cli/cli-stop-json.test.ts
@@ -0,0 +1,258 @@
+import { describe, expect, test } from "bun:test";
+import { dispatchCommand } from "../../src/cli/dispatch";
+import type { CliDispatchDeps } from "../../src/cli/dispatch";
+import type { CliHead } from "../../src/cli/root";
+import {
+  STOP_SUMMARY_SCHEMA,
+  summarizeStopRun,
+  type StopRunRecord,
+  type StopSummaryJson,
+} from "../../src/cli/stop-report";
+import { STOP_HISTORY_DEFERRED_EXIT_CODE, STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "../../src/update/stop-contract.mjs";
+
+/**
+ * A test batch shares ONE Bun process, and Bun does not clear process.exitCode on a
+ * bare undefined assignment — the suite convention is restore-with-`?? 0`
+ * (cli-dispatch.test.ts, service.test.ts). A leftover nonzero exitCode fails the batch
+ * with zero failing tests, which is exactly what shard batch output then shows.
+ */
+function withExitCode(code: number): () => void {
+  const previousExitCode = process.exitCode;
+  process.exitCode = code;
+  return () => {
+    process.exitCode = previousExitCode ?? 0;
+  };
+}
+
+function record(overrides: Partial<StopRunRecord> = {}): StopRunRecord {
+  return {
+    service: "absent",
+    proxy: "stopped",
+    sharedTeardown: "restored",
+    inheritedTeardownBlocks: false,
+    receiptClearFailed: false,
+    ...overrides,
+  };
+}
+
+function summarize(rec: StopRunRecord, signals: { failed?: boolean; historyOnly?: boolean; historyDeferred?: boolean; exitCode?: number }): StopSummaryJson {
+  return summarizeStopRun(rec, {
+    failed: signals.failed ?? false,
+    historyOnly: signals.historyOnly ?? false,
+    historyDeferred: signals.historyDeferred ?? false,
+    exitCode: signals.exitCode ?? 0,
+  });
+}
+
+describe("summarizeStopRun", () => {
+  test("a clean tracked-pid stop is stopped, ok, and runtime-down", () => {
+    const summary = summarize(record(), { exitCode: 0 });
+    expect(summary).toEqual({
+      schema: STOP_SUMMARY_SCHEMA,
+      ok: true,
+      outcome: "stopped",
+      exitCode: 0,
+      runtimeDown: true,
+      service: "absent",
+      proxy: "stopped",
+      sharedTeardown: "restored",
+      message: "The proxy stopped.",
+    });
+  });
+
+  test("nothing running is a successful not-running outcome", () => {
+    const summary = summarize(record({ proxy: "not-running", sharedTeardown: "restored" }), { exitCode: 0 });
+    expect(summary.outcome).toBe("not-running");
+    expect(summary.ok).toBe(true);
+    expect(summary.runtimeDown).toBe(true);
+    expect(summary.message).toBe("No proxy was running.");
+  });
+
+  test("history-incomplete keeps the proxy down with its own exit code", () => {
+    const summary = summarize(record(), { historyOnly: true, exitCode: STOP_HISTORY_INCOMPLETE_EXIT_CODE });
+    expect(summary.outcome).toBe("history-incomplete");
+    expect(summary.ok).toBe(false);
+    expect(summary.runtimeDown).toBe(true);
+  });
+
+  test("history-deferred is only clean with the deferred exit code", () => {
+    const clean = summarize(record({ sharedTeardown: "refused" }), {
+      historyDeferred: true,
+      exitCode: STOP_HISTORY_DEFERRED_EXIT_CODE,
+    });
+    expect(clean.outcome).toBe("history-deferred");
+    expect(clean.message).toContain("refused");
+
+    const dishonest = summarize(record({ sharedTeardown: "refused" }), { historyDeferred: true, exitCode: 1 });
+    expect(dishonest.outcome).toBe("failed");
+  });
+
+  test("a respawned survivor fails with the runtime up", () => {
+    const summary = summarize(record({ proxy: "respawned", service: "stopped-respawnable", sharedTeardown: "skipped" }), {
+      failed: true,
+      exitCode: 1,
+    });
+    expect(summary.outcome).toBe("failed");
+    expect(summary.ok).toBe(false);
+    expect(summary.runtimeDown).toBe(false);
+    expect(summary.message).toContain("respawned");
+  });
+
+  test("an ownership refusal names the refusing proxy", () => {
+    const summary = summarize(record({ proxy: "ownership-refused", sharedTeardown: "skipped" }), { failed: true, exitCode: 1 });
+    expect(summary.outcome).toBe("failed");
+    expect(summary.runtimeDown).toBe(false);
+    expect(summary.message).toContain("refused the stop");
+  });
+
+  test("an unresolvable pid is reported rather than treated as stopped", () => {
+    const summary = summarize(record({ proxy: "unresolvable-pid", sharedTeardown: "skipped" }), { failed: true, exitCode: 1 });
+    expect(summary.runtimeDown).toBe(false);
+    expect(summary.message).toContain("process id could not be resolved");
+  });
+
+  test("a service-manager failure outranks the stopped proxy for the message", () => {
+    const summary = summarize(record({ service: "failed" }), { failed: true, exitCode: 1 });
+    expect(summary.message).toContain("service manager did not stop");
+  });
+
+  test("inherited teardown blocks and receipt-clear failures are surfaced", () => {
+    const inherited = summarize(record({ inheritedTeardownBlocks: true, sharedTeardown: "skipped" }), { failed: true, exitCode: 1 });
+    expect(inherited.message).toContain("outstanding shared teardown");
+
+    const receipt = summarize(record({ receiptClearFailed: true }), { failed: true, exitCode: 1 });
+    expect(receipt.message).toContain("receipt");
+  });
+
+  test("the proxy-owned teardown keeps its own classification", () => {
+    const summary = summarize(record({ sharedTeardown: "performed-by-proxy" }), { exitCode: 0 });
+    expect(summary.sharedTeardown).toBe("performed-by-proxy");
+    expect(summary.outcome).toBe("stopped");
+  });
+
+  test("a failed shared teardown is not reported as restored", () => {
+    // restore.other means the config/catalog restore failed: the proxy is down but the
+    // client config may still point at it. The summary must say failed, not restored.
+    const summary = summarize(record({ sharedTeardown: "failed" }), { failed: true, exitCode: 1 });
+    expect(summary.outcome).toBe("failed");
+    expect(summary.runtimeDown).toBe(true);
+    expect(summary.sharedTeardown).toBe("failed");
+    expect(summary.message).toContain("teardown failed");
+  });
+});
+
+describe("ocx stop --json dispatch", () => {
+  function captureConsole() {
+    const originalLog = console.log;
+    const originalError = console.error;
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+    console.log = (...values: unknown[]) => { stdout.push(values.map(String).join(" ")); };
+    console.error = (...values: unknown[]) => { stderr.push(values.map(String).join(" ")); };
+    return {
+      stdout,
+      stderr,
+      restore() {
+        console.log = originalLog;
+        console.error = originalError;
+      },
+    };
+  }
+
+  function stopDeps(handleStop: CliDispatchDeps["handleStop"], args: string[]): CliDispatchDeps {
+    const head: CliHead = { kind: "command", command: "stop", args };
+    return { args, head, handleStop } as unknown as CliDispatchDeps;
+  }
+
+  test("emits exactly one JSON document and moves human output to stderr", async () => {
+    const restoreExitCode = withExitCode(0);
+    const summary = summarizeStopRun(record(), { failed: false, historyOnly: false, historyDeferred: false, exitCode: 0 });
+    const captured = captureConsole();
+    try {
+      const code = await dispatchCommand(
+        { kind: "command", command: "stop", args: ["stop", "--json"] },
+        stopDeps(async () => {
+          // The real handleStop logs through console.log; the JSON dispatch must move
+          // that stream to stderr for the duration of the stop call.
+          console.log("Service manager stopped.");
+          return { ok: true, summary };
+        }, ["stop", "--json"]),
+      );
+      expect(code).toBe(0);
+      expect(captured.stdout).toHaveLength(1);
+      expect(JSON.parse(captured.stdout[0]!)).toEqual(summary);
+      // The stop path's human line and the downtime warning are human output: stderr
+      // in JSON mode.
+      expect(captured.stderr.some(line => line.includes("Service manager stopped."))).toBe(true);
+      expect(captured.stderr.some(line => line.includes("will fail until it is restarted"))).toBe(true);
+    } finally {
+      captured.restore();
+      restoreExitCode();
+    }
+  });
+
+  test("preserves the history exit codes across the JSON boundary", async () => {
+    const restoreExitCode = withExitCode(STOP_HISTORY_INCOMPLETE_EXIT_CODE);
+    const summary = summarizeStopRun(record(), {
+      failed: false,
+      historyOnly: true,
+      historyDeferred: false,
+      exitCode: STOP_HISTORY_INCOMPLETE_EXIT_CODE,
+    });
+    const captured = captureConsole();
+    try {
+      const code = await dispatchCommand(
+        { kind: "command", command: "stop", args: ["stop", "--json"] },
+        stopDeps(async () => ({ ok: true, summary }), ["stop", "--json"]),
+      );
+      expect(code).toBe(STOP_HISTORY_INCOMPLETE_EXIT_CODE);
+      expect((JSON.parse(captured.stdout[0]!) as StopSummaryJson).exitCode).toBe(STOP_HISTORY_INCOMPLETE_EXIT_CODE);
+    } finally {
+      captured.restore();
+      restoreExitCode();
+    }
+  });
+
+  test("without --json the human output and warning stay on stdout", async () => {
+    const restoreExitCode = withExitCode(0);
+    const summary = summarizeStopRun(record(), { failed: false, historyOnly: false, historyDeferred: false, exitCode: 0 });
+    const captured = captureConsole();
+    try {
+      const code = await dispatchCommand(
+        { kind: "command", command: "stop", args: ["stop"] },
+        stopDeps(async () => {
+          console.log("Service manager stopped.");
+          return { ok: true, summary };
+        }, ["stop"]),
+      );
+      expect(code).toBe(0);
+      expect(captured.stdout.some(line => line.includes("Service manager stopped."))).toBe(true);
+      expect(captured.stdout.some(line => line.includes("will fail until it is restarted"))).toBe(true);
+      expect(captured.stdout.every(line => { try { JSON.parse(line); return false; } catch { return true; } })).toBe(true);
+    } finally {
+      captured.restore();
+      restoreExitCode();
+    }
+  });
+
+  test("a failed stop never prints the downtime warning in human mode", async () => {
+    // handleStop now returns { ok, summary }: an object is always truthy, so keying the
+    // warning on the return value would print "requests will fail" for a failed stop.
+    const restoreExitCode = withExitCode(1);
+    const summary = summarizeStopRun(record({ proxy: "stop-failed", sharedTeardown: "skipped" }), {
+      failed: true, historyOnly: false, historyDeferred: false, exitCode: 1,
+    });
+    const captured = captureConsole();
+    try {
+      const code = await dispatchCommand(
+        { kind: "command", command: "stop", args: ["stop"] },
+        stopDeps(async () => ({ ok: false, summary }), ["stop"]),
+      );
+      expect(code).toBe(1);
+      expect(captured.stdout.some(line => line.includes("will fail until it is restarted"))).toBe(false);
+    } finally {
+      captured.restore();
+      restoreExitCode();
+    }
+  });
+});
diff --git a/tests/cli/start-ownership-publication.test.ts b/tests/cli/start-ownership-publication.test.ts
new file mode 100644
index 00000000000..23a3c825987
--- /dev/null
+++ b/tests/cli/start-ownership-publication.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import {
+  bindAndPublishStartOwnership,
+  StartOwnershipRollbackUncertainError,
+} from "../../src/cli/start-ownership-publication";
+
+function fixture(options: {
+  failPid?: boolean;
+  failRuntime?: boolean;
+  failStop?: boolean;
+  failRemoveRuntime?: boolean;
+  failRemovePid?: boolean;
+} = {}) {
+  const events: string[] = [];
+  const deps = {
+    acquireLease: () => ({ release: () => { events.push("release"); } }),
+    bind: async () => { events.push("bind"); return { id: 1 }; },
+    writePid: () => {
+      events.push("pid");
+      if (options.failPid) throw new Error("pid write failed");
+    },
+    writeRuntime: () => {
+      events.push("runtime");
+      if (options.failRuntime) throw new Error("runtime write failed");
+    },
+    stopBound: async () => {
+      events.push("stop");
+      if (options.failStop) throw new Error("stop failed");
+    },
+    removeRuntime: () => {
+      events.push("remove-runtime");
+      if (options.failRemoveRuntime) throw new Error("runtime cleanup failed");
+    },
+    removePid: () => {
+      events.push("remove-pid");
+      if (options.failRemovePid) throw new Error("pid cleanup failed");
+    },
+  };
+  return { events, deps };
+}
+
+describe("start ownership publication", () => {
+  test("success releases only after bind and both records", async () => {
+    const { events, deps } = fixture();
+    await bindAndPublishStartOwnership(deps);
+    expect(events).toEqual(["bind", "pid", "runtime", "release"]);
+  });
+
+  test("a bind refusal releases without publishing or rollback", async () => {
+    const { events, deps } = fixture();
+    deps.bind = async () => { events.push("bind-refused"); throw new Error("refused"); };
+    await expect(bindAndPublishStartOwnership(deps)).rejects.toThrow("refused");
+    expect(events).toEqual(["bind-refused", "release"]);
+  });
+
+  for (const failure of ["pid", "runtime"] as const) {
+    test(`${failure} publication failure stops and cleans before release`, async () => {
+      const { events, deps } = fixture({
+        failPid: failure === "pid",
+        failRuntime: failure === "runtime",
+      });
+      await expect(bindAndPublishStartOwnership(deps)).rejects.toThrow(`${failure} write failed`);
+      expect(events).toEqual(failure === "pid"
+        ? ["bind", "pid", "stop", "remove-runtime", "remove-pid", "release"]
+        : ["bind", "pid", "runtime", "stop", "remove-runtime", "remove-pid", "release"]);
+    });
+  }
+
+  test("listener rollback uncertainty cleans records but retains the lease", async () => {
+    const { events, deps } = fixture({
+      failRuntime: true,
+      failStop: true,
+    });
+    await expect(bindAndPublishStartOwnership(deps)).rejects.toBeInstanceOf(StartOwnershipRollbackUncertainError);
+    expect(events).toEqual(["bind", "pid", "runtime", "stop", "remove-runtime", "remove-pid"]);
+  });
+
+  test("cleanup failures still attempt both records and release after the listener stopped", async () => {
+    const { events, deps } = fixture({ failRuntime: true, failRemoveRuntime: true, failRemovePid: true });
+    await expect(bindAndPublishStartOwnership(deps)).rejects.toBeInstanceOf(AggregateError);
+    expect(events).toEqual(["bind", "pid", "runtime", "stop", "remove-runtime", "remove-pid", "release"]);
+  });
+});
diff --git a/tests/cli/uninstall.test.ts b/tests/cli/uninstall.test.ts
index ea984f274fd..1b0e6f399b5 100644
--- a/tests/cli/uninstall.test.ts
+++ b/tests/cli/uninstall.test.ts
@@ -243,7 +243,7 @@ describe("uninstall gates shared teardown on a proven service stop", () => {
   });
 });
   test("proof covers every distinct endpoint, not just the preferred one", async () => {
-    const { endpointsToProve, everyEndpointProvenDown } = await import("../../src/cli/uninstall-plan");
+    const { endpointsToProve, everyEndpointProvenDown, everyEndpointProvenDownAsync } = await import("../../src/cli/uninstall-plan");
 
     // A stale runtime record pointing at a closed port, and the live proxy on the
     // configured one. Probing only the runtime candidate reports "dead" for a port nobody
@@ -267,6 +267,8 @@ describe("uninstall gates shared teardown on a proven service stop", () => {
     expect(endpointsToProve(null, {})).toEqual([{ hostname: "127.0.0.1", port: 10100 }]);
     // An empty set is not proof of anything.
     expect(everyEndpointProvenDown([], () => "dead")).toBe(false);
+    expect(await everyEndpointProvenDownAsync(endpoints, async () => "dead")).toBe(true);
+    expect(await everyEndpointProvenDownAsync([], async () => "dead")).toBe(false);
     // A nonsense runtime port is skipped rather than probed.
     expect(endpointsToProve({ port: 0 }, { port: 10100 })).toEqual([{ hostname: "127.0.0.1", port: 10100 }]);
   });
@@ -284,7 +286,7 @@ describe("uninstall gates shared teardown on a proven service stop", () => {
       .toBeLessThan(windowStep.indexOf("observed.respawnWindowVerified = true;"));
     // And the proof itself asks every candidate.
     expect(fn).toContain("endpointsToProve(readRuntimePort(), loadConfig())");
-    expect(fn).toContain("everyEndpointProvenDown(endpoints, e => probeProxyLiveness(e.port, e.hostname))");
+    expect(fn).toContain("everyEndpointProvenDownAsync(endpoints, probeEndpointLiveness)");
   });
 
 const safeTeardown: UninstallObservation = {
diff --git a/tests/clients/cline-writer.test.ts b/tests/clients/cline-writer.test.ts
index 4247f0abde8..ff06f29dbc8 100644
--- a/tests/clients/cline-writer.test.ts
+++ b/tests/clients/cline-writer.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { clineConfigPath } from "../../src/clients/config-export";
@@ -140,6 +140,33 @@ describe("Cline journaled pair", () => {
     expect(readFileSync(catalog, "utf8")).toBe(originalCatalog);
   });
 
+  // Skipped on Windows with the other symlink regressions: link creation needs
+  // a privilege the hosted runners do not grant, and the boundary under test is
+  // the platform-independent lstat-plus-rename path in the shared writer.
+  test.skipIf(process.platform === "win32")("a member exchanged for a symlink at the write boundary cannot redirect replacement", () => {
+    seed();
+    const victim = join(root, "victim.json");
+    const displaced = `${settings}.attacker-saved`;
+    writeFileSync(victim, '{"sentinel":true}');
+    const io = input.store!.io();
+    let exchanged = false;
+    const result = applyIntegration({ ...input, io: {
+      ...io,
+      writeText: (path, text) => {
+        if (path === settings && !exchanged) {
+          exchanged = true;
+          renameSync(settings, displaced);
+          symlinkSync(victim, settings);
+        }
+        io.writeText(path, text);
+      },
+    } });
+    expect(result.ok).toBe(false);
+    expect(readFileSync(victim, "utf8")).toBe('{"sentinel":true}');
+    expect(lstatSync(settings).isSymbolicLink()).toBe(true);
+    expect(readFileSync(displaced, "utf8")).toBe(originalSettings);
+  });
+
   test("occupied custom provider requires explicit overwrite and remains reversible", () => {
     seed();
     const doc = settingsDoc();
diff --git a/tests/clients/desktop-cli-contracts.test.ts b/tests/clients/desktop-cli-contracts.test.ts
new file mode 100644
index 00000000000..d4ae062c866
--- /dev/null
+++ b/tests/clients/desktop-cli-contracts.test.ts
@@ -0,0 +1,133 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * The two CLI surfaces the shell drives, read against the CLI that defines them.
+ *
+ * D5 and D4: the shell stops resolving the home, the port and liveness itself, and stops performing
+ * the teardown itself. `src/cli/resolve.ts` and `src/cli/stop-report.ts` own those answers; the Rust
+ * side is a reader. Both halves are asserted here together so a schema, a status value or an
+ * outcome name cannot change on one side and be discovered on a user's machine.
+ *
+ * The rule that matters most is the one a reader can get wrong quietly: liveness has three answers,
+ * and only a proven absence authorises starting a runtime. Everything that can go wrong on the
+ * shell side has to fold into the third one, because the reading that must never happen is "the
+ * resolve failed, so nobody must be listening".
+ */
+const SHELL = "desktop/src-tauri/src";
+const RESOLVE_RS = repoPath(`${SHELL}/resolve.rs`);
+const STOP_RS = repoPath(`${SHELL}/runtime_stop.rs`);
+const STARTUP = repoPath(`${SHELL}/startup.rs`);
+const RESOLVE_TS = repoPath("src/cli/resolve.ts");
+const STOP_TS = repoPath("src/cli/stop-report.ts");
+
+function code(path: string): string {
+  return readFileSync(path, "utf8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+}
+
+describe("desktop CLI contracts", () => {
+  const resolveRs = code(RESOLVE_RS);
+  const stopRs = code(STOP_RS);
+  const resolveTs = code(RESOLVE_TS);
+  const stopTs = code(STOP_TS);
+
+  test("both sides name the same wire versions", () => {
+    expect(resolveTs).toContain('RESOLVE_SCHEMA = "ocx-resolve/1"');
+    expect(resolveRs).toContain('pub const SCHEMA: &str = "ocx-resolve/1"');
+    expect(stopTs).toContain('STOP_SUMMARY_SCHEMA = "ocx-stop/1"');
+    expect(stopRs).toContain('pub const SCHEMA: &str = "ocx-stop/1"');
+    // A document announcing anything else is not understood rather than half-read.
+    expect(resolveRs).toContain("resolved.schema != SCHEMA");
+    expect(stopRs).toContain("summary.schema != SCHEMA");
+  });
+
+  test("liveness keeps its three answers, and only one of them authorises a start", () => {
+    // Two reach the wire; the third exits 1 before the document is built.
+    expect(resolveTs).toContain('status: "live" | "absent-proven"');
+    expect(resolveRs).toContain('#[serde(rename_all = "kebab-case")]');
+    expect(resolveRs).toContain("    Live,");
+    expect(resolveRs).toContain("    AbsentProven,");
+    const rule = resolveRs.slice(resolveRs.indexOf("pub fn may_start("));
+    const body = rule.slice(0, rule.indexOf("\n}"));
+    expect(body).toContain("Some(Status::AbsentProven)");
+    expect(body).not.toContain("Status::Live");
+  });
+
+  test("a live listener this app cannot manage is neither attached to nor started beside", () => {
+    // Core's liveness predicate accepts a connected client's listener on purpose, so
+    // duplicate-start avoidance can see it; a caller that needs the management plane has to
+    // discriminate on the role rather than narrow that predicate.
+    expect(resolveTs).toContain("role?: string");
+    const verdict = resolveRs.slice(resolveRs.indexOf("pub fn live_verdict("));
+    const body = verdict.slice(0, verdict.indexOf("\n}"));
+    expect(body).toContain('role.as_deref() == Some("client")');
+    expect(body).toContain("LiveVerdict::Unusable");
+    // And an address this shell cannot reach on loopback is the same kind of answer.
+    expect(body).toContain("loopback_reachable(resolved.liveness.hostname.as_deref())");
+    const startup = code(STARTUP);
+    const unusable = startup.indexOf("resolve::LiveVerdict::Unusable(reason) =>");
+    const spawn = startup.indexOf("spawn_runtime(app, endpoint, &watch)");
+    expect(unusable).toBeGreaterThan(-1);
+    expect(startup.slice(unusable, spawn)).toContain("return;");
+  });
+
+  test("everything that can go wrong on this side folds into unknown", () => {
+    const reader = resolveRs.slice(resolveRs.indexOf("pub fn read("), resolveRs.indexOf("pub async fn run("));
+    // A non-zero exit is the CLI's own refusal, including the exit 1 it uses for unknown liveness.
+    expect(reader).toContain("if exit_code != Some(0) {");
+    expect(reader).toContain("Resolution::Unknown");
+    const runner = resolveRs.slice(resolveRs.indexOf("pub async fn run("));
+    const body = runner.slice(0, runner.indexOf("\n}"));
+    // A missing binary, a failed spawn and a deadline all answer the same way.
+    expect(body.match(/Resolution::Unknown/g) || []).toHaveLength(3);
+    expect(body).toContain("timeout_at(deadline, command.output())");
+  });
+
+  test("the startup sequence refuses to start on anything but a proven absence", () => {
+    const startup = code(STARTUP);
+    const run = startup.slice(startup.indexOf("async fn run(app: &AppHandle)"));
+    const unknown = run.indexOf("let Some(answer) = resolution.resolved() else {");
+    const attach = run.indexOf("match resolve::live_verdict(&resolution) {");
+    const guard = run.indexOf("if !resolve::may_start(&resolution) {");
+    const spawn = run.indexOf("spawn_runtime(app, endpoint, &watch)");
+    expect(unknown).toBeGreaterThan(-1);
+    expect(attach).toBeGreaterThan(unknown);
+    expect(guard).toBeGreaterThan(attach);
+    expect(spawn).toBeGreaterThan(guard);
+    // The unresolved branch fails the state; it does not fall through to a start.
+    expect(run.slice(unknown, attach)).toContain("Phase::Resolving,");
+    expect(run.slice(unknown, attach)).toContain("return;");
+  });
+
+  test("a stop is a success only when the CLI said so twice", () => {
+    // The process status and the document have to agree, and the document has to say the runtime
+    // is down: taking the summary's word for its own exit status is taking a claim as its own
+    // evidence.
+    expect(stopTs).toContain("ok: signals.exitCode === 0");
+    expect(stopTs).toContain("runtimeDown: record.proxy ===");
+    const reader = stopRs.slice(stopRs.indexOf("pub fn read("), stopRs.indexOf("pub async fn run("));
+    expect(reader).toContain("if exit_code != Some(0)");
+    expect(reader).toContain("|| !summary.ok");
+    expect(reader).toContain("|| summary.exit_code != 0");
+    expect(reader).toContain("|| !summary.runtime_down");
+    // And the document has to agree with itself rather than be trusted to.
+    expect(reader).toContain("|| !agrees");
+    expect(reader).toContain("(Outcome::Stopped, Proxy::Stopped)");
+    expect(reader).toContain("(Outcome::NotRunning, Proxy::NotRunning)");
+    expect(reader).toContain("StopResult::Failed");
+    const stopped = reader.indexOf("StopResult::Stopped(summary)");
+    expect(stopped).toBeGreaterThan(reader.indexOf("if exit_code != Some(0)"));
+  });
+
+  test("the outcomes the shell can be handed are the outcomes the CLI can emit", () => {
+    expect(stopTs).toContain(
+      'outcome: "stopped" | "not-running" | "history-incomplete" | "history-deferred" | "failed"',
+    );
+    // The shell does not re-derive the outcome; it carries the CLI's own words into its diagnostic.
+    expect(stopRs).toContain("summary.outcome");
+    expect(stopRs).toContain("summary.exit_code");
+    expect(stopRs).toContain("summary.message");
+    expect(stopRs).not.toContain('== "stopped"');
+  });
+});
diff --git a/tests/clients/desktop-exit-ownership.test.ts b/tests/clients/desktop-exit-ownership.test.ts
new file mode 100644
index 00000000000..27cc075f3fa
--- /dev/null
+++ b/tests/clients/desktop-exit-ownership.test.ts
@@ -0,0 +1,275 @@
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * INV-DESKTOP-01 — only the tray's Quit ends the app, and nothing ends the runtime by force.
+ *
+ * Three gestures used to mean the same thing. Closing the window hid it, but Cmd+Q reached
+ * `RunEvent::Exit` with no `ExitRequested` handler in between, and that called
+ * `CommandChild::kill()` — a SIGKILL on Unix — on the runtime this app had started. The CLI's own
+ * stop restores client configuration, lets in-flight requests finish and clears state files; none
+ * of that survived a keystroke the user reads as "hide". The updater took the same path.
+ *
+ * macOS needs one thing more than the event handler, and it is the part that is easiest to get
+ * wrong while believing it works: Tauri's default menu carries a predefined Quit wired straight to
+ * Cocoa's `terminate:`, and the pinned tao raises no cancellable event for it, so `prevent_exit`
+ * never sees it. The replacement item is therefore part of this contract, not a detail.
+ *
+ * The wiring is the contract and it is not visible from behaviour alone — CI builds the shell
+ * against a zero-byte sidecar and has no session to press Cmd+Q in — so it is read out of the
+ * source, the way the Start at Login ordering already is.
+ */
+const SRC = "desktop/src-tauri/src";
+const LIB = repoPath(`${SRC}/lib.rs`);
+const EXIT = repoPath(`${SRC}/exit.rs`);
+const MENU = repoPath(`${SRC}/menu.rs`);
+const TRAY = repoPath(`${SRC}/tray.rs`);
+const WINDOW = repoPath(`${SRC}/window.rs`);
+const UPDATER = repoPath(`${SRC}/updater.rs`);
+
+function code(path: string): string {
+  return readFileSync(path, "utf8").replace(/\/\/[^\n]*/g, "");
+}
+
+/** Every Rust file in the shell, walked from disk so a new module cannot opt itself out. */
+function shellSources(directory: string = SRC): string[] {
+  return readdirSync(repoPath(directory), { withFileTypes: true }).flatMap((entry) => {
+    const path = `${directory}/${entry.name}`;
+    if (entry.isDirectory()) return shellSources(path);
+    return entry.name.endsWith(".rs") ? [path] : [];
+  });
+}
+
+describe("desktop exit ownership", () => {
+  test("the event loop intercepts the exit request instead of letting it through", () => {
+    const lib = code(LIB);
+    expect(lib).toContain("RunEvent::ExitRequested");
+    expect(lib).toContain("exit::on_exit_requested(app, code, &api)");
+  });
+
+  test("no file in the shell kills the runtime process", () => {
+    const sources = shellSources();
+    expect(sources.length).toBeGreaterThan(10);
+    for (const source of sources) {
+      expect(code(repoPath(source))).not.toContain(".kill()");
+    }
+  });
+
+  test("the tray's Quit asks the coordinator rather than ending the process itself", () => {
+    const tray = code(TRAY);
+    expect(tray).toContain('"quit" => exit::request(app, ExitReason::UserQuit)');
+    expect(tray).not.toContain("app.exit(");
+  });
+
+  test("the macOS menu's Quit is an ordinary item routed through the gesture path", () => {
+    const menu = code(MENU);
+    // The predefined item is the one that cannot be held: it calls Cocoa's terminate: directly.
+    expect(menu).not.toContain("PredefinedMenuItem::quit");
+    expect(menu).toContain('Some("CmdOrCtrl+Q")');
+    expect(menu).toContain("crate::exit::gesture(app)");
+    // Losing the default menu would take the clipboard items with it, and the failure diagnostic
+    // is a block of text the user is asked to copy.
+    for (const item of ["cut", "copy", "paste", "select_all"]) {
+      expect(menu).toContain(`PredefinedMenuItem::${item}`);
+    }
+    const lib = code(LIB);
+    expect(lib).toContain(".menu(menu::build)");
+    expect(lib).toContain("menu::on_event(app, event.id().as_ref())");
+  });
+
+  test("a restart is told apart from a quit and keeps its own reason", () => {
+    const exit = code(EXIT);
+    expect(exit).toContain("ExitReason::CoordinatedRestart");
+    expect(exit).toContain("tauri::RESTART_EXIT_CODE");
+    const updater = code(UPDATER);
+    expect(updater).toContain("crate::exit::prepare_restart(app).await");
+    expect(updater).not.toContain("app.restart()");
+  });
+
+  test("an update stops the runtime before it replaces anything", () => {
+    const updater = code(UPDATER);
+    const install = updater.slice(updater.indexOf("pub async fn install("));
+    const body = install.slice(0, install.indexOf("\n}"));
+    const downloaded = body.indexOf(".download(");
+    const prepared = body.indexOf("crate::exit::prepare_restart(app).await");
+    const installed = body.indexOf("update.install(package)");
+    expect(downloaded).toBeGreaterThan(-1);
+    expect(prepared).toBeGreaterThan(downloaded);
+    expect(installed).toBeGreaterThan(prepared);
+    // The combined call is the shape that cannot drain first.
+    expect(body).not.toContain("download_and_install");
+    // A drain that did not complete refuses the install rather than proceeding.
+    expect(body.slice(prepared, installed)).toContain("if readiness != RestartReadiness::Ready {");
+    expect(body.slice(prepared, installed)).toContain("return Err(");
+  });
+
+  test("an update restart drains through the same path a quit does", () => {
+    const exit = code(EXIT);
+    const prepare = exit.indexOf("pub async fn prepare_restart");
+    expect(prepare).toBeGreaterThan(-1);
+    const body = exit.slice(prepare, exit.indexOf("pub fn complete_restart", prepare));
+    expect(body).toContain("claim_drain(ExitReason::CoordinatedRestart)");
+    expect(body).toContain("drain_current(app).await");
+    expect(body).toContain("coordinator.finish_drain(verdict)");
+    // D4: the stop is the bundled CLI's, which owns the receipt-backed teardown this process
+    // cannot perform on itself.
+    expect(exit).toContain("runtime_stop::run(app, deadline).await");
+  });
+
+  test("a failed drain is not recorded as a drain, and a restart refuses it", () => {
+    const exit = code(EXIT);
+    const record = exit.slice(exit.indexOf("pub fn finish_drain("));
+    const body = record.slice(0, record.indexOf("\n    }"));
+    expect(body).toContain("DrainVerdict::Drained => ExitPhase::Drained");
+    expect(body).toContain("DrainVerdict::Failed => ExitPhase::DrainFailed");
+    expect(body).toContain("DrainVerdict::OwnershipUnknown => ExitPhase::OwnershipUnknown");
+    const rule = exit.slice(exit.indexOf("pub fn decide("), exit.indexOf("struct Inner {"));
+    expect(rule).toContain("ExitPhase::DrainFailed | ExitPhase::OwnershipUnknown => match reason");
+    expect(rule).toContain("Some(ExitReason::CoordinatedRestart) => ExitDecision::Refuse");
+    // A quit still closes the app on one, which is the trade that is defensible.
+    expect(rule).toContain("_ => ExitDecision::Proceed");
+    // And the refusal is recoverable: the update stayed pending, so the next attempt runs the
+    // stop again rather than finding the app permanently unable to try.
+    const claim = exit.slice(exit.indexOf("pub fn claim_drain"), exit.indexOf("pub fn finish_drain"));
+    expect(claim).toContain("ExitPhase::DrainFailed | ExitPhase::OwnershipUnknown => {");
+    expect(claim).toContain("ExitPhase::Draining | ExitPhase::Drained => None,");
+  });
+
+  test("stop, quit and update are one execution over one child", () => {
+    const tray = code(TRAY);
+    expect(tray).toContain("exit::request_stop(app)");
+    expect(tray).not.toContain("sidecar::drain");
+    const exit = code(EXIT);
+    const stop = exit.slice(exit.indexOf("pub fn request_stop("));
+    const body = stop.slice(0, stop.indexOf("\n}"));
+    expect(body).toContain("coordinator.begin_stop()");
+    expect(body).toContain("drain_current(&app).await");
+    // A quit that landed during the stop is handed back and run, not dropped.
+    expect(body).toContain("coordinator.finish_stop()");
+    expect(body).toContain("drain_now(&app, reason)");
+  });
+
+  test("the reason and the drain are claimed in one step", () => {
+    const exit = code(EXIT);
+    const claim = exit.indexOf("pub fn claim_drain");
+    expect(claim).toBeGreaterThan(-1);
+    const body = exit.slice(claim, exit.indexOf("pub fn finish_drain", claim));
+    expect(body.length).toBeGreaterThan(0);
+    // One match over the phase, so the reason a caller wins and the move out of Idle cannot be
+    // separated by a second caller arriving between them.
+    expect(body).toContain("match inner.phase {");
+    const idle = body.indexOf("ExitPhase::Idle => {");
+    expect(idle).toBeGreaterThan(-1);
+    const arm = body.slice(
+      idle,
+      body.indexOf("ExitPhase::Spawning | ExitPhase::Stopping => {", idle),
+    );
+    expect(arm).toContain("inner.reason.get_or_insert(fallback)");
+    expect(arm).toContain("inner.phase = ExitPhase::Draining;");
+    // Nothing else in the file moves the phase to draining.
+    expect(exit.split("inner.phase = ExitPhase::Draining;")).toHaveLength(4);
+  });
+
+  test("a quit that lands while a runtime is starting is deferred, not lost", () => {
+    const exit = code(EXIT);
+    // The lock is never held across process creation, so the main thread's exit handler cannot
+    // end up waiting on a spawn; the exit is held by the phase instead.
+    expect(exit).toContain("ExitPhase::Spawning");
+    expect(exit).toContain(
+      "ExitPhase::Spawning | ExitPhase::Stopping | ExitPhase::Draining => ExitDecision::Wait",
+    );
+    const claim = exit.slice(exit.indexOf("pub fn claim_drain"), exit.indexOf("pub fn finish_drain"));
+    expect(claim).toContain("ExitPhase::Spawning | ExitPhase::Stopping => {");
+    expect(claim).toContain("inner.deferred = true;");
+    const finish = exit.slice(
+      exit.indexOf("fn finish(&self, phase: ExitPhase)"),
+      exit.indexOf("impl Default for ExitCoordinator"),
+    );
+    expect(finish).toContain("inner.deferred");
+    expect(finish).toContain("inner.phase = ExitPhase::Draining;");
+    const startup = code(repoPath(`${SRC}/startup.rs`));
+    const spawn = startup.slice(startup.indexOf("fn spawn_runtime("));
+    expect(spawn).toContain("if !coordinator.begin_spawn() {");
+    expect(spawn).toContain("crate::exit::drain_now(app, reason)");
+    expect(spawn.indexOf("state.adopt(child)")).toBeLessThan(spawn.indexOf("coordinator.finish_spawn()"));
+  });
+
+  test("no tray setter is called while the tray mutex is held", () => {
+    const tray = code(repoPath(`${SRC}/tray.rs`));
+    // Those setters dispatch to the main thread and wait for it, and the tray is built on the main
+    // thread while holding this mutex, so the two together are a cycle.
+    expect(tray).toContain("fn menu_handles(app: &AppHandle) -> Option<TrayMenu>");
+    // Every setter is reached through the copy, never through a live guard: the nearest thing
+    // before it is the handle copy, not the lock.
+    const setters = [...tray.matchAll(/\.(?:set_enabled|set_text)\(/g)];
+    expect(setters.length).toBeGreaterThan(5);
+    for (const setter of setters) {
+      const before = tray.slice(0, setter.index);
+      expect(before.lastIndexOf("menu_handles(app)")).toBeGreaterThan(
+        before.lastIndexOf("menu.lock()"),
+      );
+    }
+  });
+
+  test("the exit is held until the drain reports", () => {
+    const exit = code(EXIT);
+    const handler = exit.slice(
+      exit.indexOf("pub fn on_exit_requested"),
+      exit.indexOf("pub fn start_drain"),
+    );
+    expect(handler.length).toBeGreaterThan(0);
+    for (const arm of [
+      "ExitDecision::Hide =>",
+      "ExitDecision::Wait =>",
+      "ExitDecision::Drain(reason) =>",
+    ]) {
+      const at = handler.indexOf(arm);
+      expect(at).toBeGreaterThan(-1);
+      expect(handler.slice(at, at + 160)).toContain("api.prevent_exit()");
+    }
+    const proceed = handler.indexOf("ExitDecision::Proceed =>");
+    expect(proceed).toBeGreaterThan(-1);
+    expect(handler.slice(proceed)).not.toContain("prevent_exit");
+    expect(exit).toContain("coordinator.finish_drain(verdict)");
+  });
+
+  test("closing the window takes the same decision the quit gesture does", () => {
+    const window = code(WINDOW);
+    const close = window.indexOf("CloseRequested");
+    expect(close).toBeGreaterThan(-1);
+    const branch = window.slice(close, window.indexOf("});", close));
+    expect(branch).toContain("api.prevent_close()");
+    expect(branch).toContain("exit::gesture(");
+    const exit = code(EXIT);
+    const gesture = exit.slice(exit.indexOf("pub fn gesture("));
+    const body = gesture.slice(0, gesture.indexOf("\n}"));
+    expect(body).toContain("ExitDecision::Hide => hide_windows(app)");
+    expect(body).toContain("ExitDecision::Drain(reason) => start_drain(app, reason)");
+  });
+
+  test("a drain never runs against a runtime this app did not start", () => {
+    const exit = code(EXIT);
+    const drain = exit.slice(exit.indexOf("pub async fn drain_current("));
+    const body = drain.slice(0, drain.indexOf("\nenum Ownership"));
+    // Only a confirmed-ours runtime is stopped. A foreign one is left alone, and one that cannot
+    // be identified stops nothing at all.
+    expect(body).toContain("Ownership::Foreign => DrainVerdict::Drained");
+    expect(body).toContain("Ownership::Unknown => DrainVerdict::OwnershipUnknown");
+    expect(body.indexOf("Ownership::Ours =>")).toBeLessThan(body.indexOf("runtime_stop::run"));
+    // Nothing in the shell performs the stop itself any more.
+    expect(code(repoPath(`${SRC}/sidecar.rs`))).not.toContain("fn drain(");
+    expect(code(repoPath(`${SRC}/proxy.rs`))).not.toContain("Method::POST");
+  });
+
+  test("only an observed exit or a refused connection proves the runtime stopped", () => {
+    const exit = code(EXIT);
+    const start = exit.indexOf("async fn confirm(");
+    expect(start).toBeGreaterThan(-1);
+    const body = exit.slice(start, exit.indexOf("fn hide_windows(", start));
+    expect(body).toContain("watch.exit().is_some()");
+    expect(body).toContain("error.is_unreachable()");
+    // Any-error-means-gone is the shape this replaces.
+    expect(exit).not.toContain("proxy.is_alive().await.is_err()");
+  });
+});
diff --git a/tests/clients/desktop-install-identity.test.ts b/tests/clients/desktop-install-identity.test.ts
new file mode 100644
index 00000000000..4772e1a6c95
--- /dev/null
+++ b/tests/clients/desktop-install-identity.test.ts
@@ -0,0 +1,128 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { parseServiceOwnershipRecord } from "../../src/service/state-record.mjs";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * The desktop app's half of the runtime-ownership claim.
+ *
+ * The claim lives in the shared service install state, which core owns across two files: the
+ * validation that decides what a record may say is in `src/service/state-record.mjs`,
+ * and the types, the three answers a read can give and `ownershipGrantedTo` — the comparison an
+ * installation applies to its own locally stored install id — are in `src/service/state.ts`. The
+ * shell holds the other half, an id of its own to compare against, and mirrors the rule rather
+ * than inventing one, because a weaker version of a question core already answers is how the
+ * shell ended up guessing a port it should have been told.
+ *
+ * Both halves are read here together, so a change on either side breaks this rather than leaving
+ * the two to disagree in a place only a takeover would reveal.
+ */
+const SHELL = "desktop/src-tauri/src";
+const IDENTITY = repoPath(`${SHELL}/identity.rs`);
+const OWNERSHIP = repoPath(`${SHELL}/ownership.rs`);
+const STARTUP = repoPath(`${SHELL}/startup.rs`);
+const STATE = repoPath("src/service/state.ts");
+
+function code(path: string): string {
+  return readFileSync(path, "utf8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+}
+
+describe("desktop install identity", () => {
+  const identity = code(IDENTITY);
+  const ownership = code(OWNERSHIP);
+  const state = code(STATE);
+
+  test("the installation's id is minted once and never rewritten", () => {
+    // Exclusive, because two launches racing to mint would answer to two ids, and the second one
+    // would find a claim that is not its own and ask again for consent already given.
+    expect(identity).toContain(".create_new(true)");
+    const mint = identity.slice(identity.indexOf("pub fn install_id_in"));
+    const body = mint.slice(0, mint.indexOf("\n}"));
+    expect(body.indexOf("if let Some(existing) = read(&path)")).toBeLessThan(
+      body.indexOf("mint(&path)"),
+    );
+    expect(body).toContain("return Some(existing);");
+    // It is the app's own directory, not the shared record: an id stored only in the shared one
+    // would be whoever wrote it last.
+    expect(identity).toContain("app_config_dir()");
+  });
+
+  test("a blank record is replaced rather than answered with", () => {
+    expect(identity).toContain("ErrorKind::AlreadyExists");
+    const replace = identity.slice(identity.indexOf("ErrorKind::AlreadyExists"));
+    expect(replace.slice(0, 300)).toContain("read(&path).is_none()");
+  });
+
+  test("the owner values are the ones the record accepts", () => {
+    // Exercise the parser a record on disk actually meets, while also pinning the exported type
+    // every caller compiles against. If runtime acceptance and the type diverge, this takeover
+    // boundary fails at review instead of after an installation has claimed the runtime.
+    const claim = { installId: "install-a", consentGeneration: 1 };
+    expect(parseServiceOwnershipRecord({ ...claim, owner: "cli" })).toEqual({ ...claim, owner: "cli" });
+    expect(parseServiceOwnershipRecord({ ...claim, owner: "desktop" })).toEqual({ ...claim, owner: "desktop" });
+    expect(parseServiceOwnershipRecord({ ...claim, owner: "another-owner" })).toBeNull();
+    expect(state).toContain('export type ServiceOwner = "cli" | "desktop"');
+    expect(ownership).toContain('#[serde(rename_all = "lowercase")]');
+    expect(ownership).toContain("    Cli,");
+    expect(ownership).toContain("    Desktop,");
+  });
+
+  test("the claim's wire fields are the recorded ones", () => {
+    for (const field of ["installId", "consentGeneration"]) {
+      expect(state).toContain(`ownership.${field}`);
+    }
+    expect(ownership).toContain('#[serde(rename_all = "camelCase")]');
+    expect(ownership).toContain("pub install_id: String");
+    expect(ownership).toContain("pub consent_generation: u64");
+  });
+
+  test("the three answers a read can give are all three", () => {
+    for (const kind of ["none", "owned", "unknown"]) {
+      expect(state).toContain(`kind: "${kind}"`);
+    }
+    expect(ownership).toContain('#[serde(tag = "kind", rename_all = "lowercase")]');
+    expect(ownership).toContain("    None,");
+    expect(ownership).toContain("Owned { ownership: Claim }");
+    expect(ownership).toContain("Unknown { reason: String }");
+  });
+
+  test("the comparison is the one the record publishes, and no more", () => {
+    const rule = state.slice(state.indexOf("export function ownershipGrantedTo"));
+    expect(rule.slice(0, 300)).toContain(
+      "ownership.owner === owner && ownership.installId === installId",
+    );
+    const mirror = ownership.slice(ownership.indexOf("pub fn granted_to"));
+    const body = mirror.slice(0, mirror.indexOf("\n}"));
+    expect(body).toContain("claim.owner == owner && claim.install_id == install_id");
+    // The generation moves on every grant; comparing it would make a held consent look foreign.
+    expect(body).not.toContain("consent_generation");
+  });
+
+  test("an unreadable record refuses instead of reading as unowned", () => {
+    const verdict = ownership.slice(ownership.indexOf("pub fn consent("));
+    const body = verdict.slice(0, verdict.indexOf("\n}"));
+    expect(body).toContain("Recorded::Unknown { .. } => Consent::Refuse");
+    expect(body).toContain("Recorded::None => Consent::AskFirstTime");
+  });
+
+  test("the shell does not read the recorded claim itself", () => {
+    // Resolving means reading every state path and failing closed on an unreadable one, a corrupt
+    // anchor and paths that disagree. That answer belongs to the CLI.
+    for (const leak of ["service-state", "serviceStatePaths", "read_to_string", "fs::"]) {
+      expect(ownership).not.toContain(leak);
+    }
+    const seam = ownership.slice(ownership.indexOf("pub fn resolve(_app: &AppHandle)"));
+    expect(seam.slice(0, 120)).toContain("None");
+  });
+
+  test("not having asked is distinct from nobody owning it", () => {
+    // Option::None means the CLI has not been asked; Recorded::None means it answered that no
+    // claim exists. Collapsing them would let a takeover proceed on a question never put.
+    expect(ownership).toContain("pub fn resolve(_app: &AppHandle) -> Option<Recorded>");
+    expect(ownership).toContain("(None, _) => ");
+    const startup = code(STARTUP);
+    expect(startup).toContain("ownership::describe(ownership::resolve(app).as_ref()");
+    expect(startup).toContain("identity::install_id(app)");
+    expect(startup).toContain('format!("runtime ownership: {}", registration.identity)');
+  });
+});
diff --git a/tests/clients/desktop-proxy-direct-transport.test.ts b/tests/clients/desktop-proxy-direct-transport.test.ts
new file mode 100644
index 00000000000..c4c76e2c50c
--- /dev/null
+++ b/tests/clients/desktop-proxy-direct-transport.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * The desktop shell's management client talks to the loopback proxy with the admin token
+ * attached. reqwest resolves system proxy configuration by default — HTTP_PROXY,
+ * HTTPS_PROXY, and the platform proxy settings behind them — so a machine-wide proxy
+ * would receive a credential that is only ever meant for the loopback endpoint. The builder
+ * has to opt out explicitly; nothing in the request path re-checks it afterwards.
+ */
+describe("desktop management transport", () => {
+  const source = readFileSync(repoPath("desktop", "src-tauri", "src", "proxy.rs"), "utf8");
+
+  test("the proxy client disables system proxy resolution for its loopback traffic", () => {
+    // Line comments are stripped first: a .no_proxy() that only exists in prose must not
+    // satisfy the contract.
+    const code = source.replace(/\/\/[^\n]*/g, "");
+    const builder = code.split("Client::builder()")[1]?.split(".build()")[0];
+    expect(builder).toBeDefined();
+    expect(builder).toContain(".no_proxy()");
+  });
+});
diff --git a/tests/clients/desktop-runtime-identity.test.ts b/tests/clients/desktop-runtime-identity.test.ts
new file mode 100644
index 00000000000..8ce8f2de491
--- /dev/null
+++ b/tests/clients/desktop-runtime-identity.test.ts
@@ -0,0 +1,143 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * Which instance the shell is talking to, and what it will send there.
+ *
+ * The management token is the admin credential for this machine's proxy, and the endpoint is a
+ * port a local process can take. So identity comes first, from the unauthenticated health body the
+ * runtime already publishes — the marker, the pid and the port — and the credential follows only
+ * for the instance the shell decided to trust. The same facts answer a second question the shell
+ * used to answer with a boolean: whether the process holding the port is the child it started.
+ *
+ * Both are read out of the source, because CI has no running proxy to address and no Windows
+ * webview to navigate.
+ */
+const SHELL = "desktop/src-tauri/src";
+const PROXY = repoPath(`${SHELL}/proxy.rs`);
+const EXIT = repoPath(`${SHELL}/exit.rs`);
+const LIB = repoPath(`${SHELL}/lib.rs`);
+const STARTUP = repoPath(`${SHELL}/startup.rs`);
+const WINDOW = repoPath(`${SHELL}/window.rs`);
+const SERVE = repoPath("src/server/index/serve-options.ts");
+
+function code(path: string): string {
+  return readFileSync(path, "utf8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+}
+
+describe("desktop runtime identity", () => {
+  const proxy = code(PROXY);
+  const exit = code(EXIT);
+
+  test("the identity it reads is the one the runtime publishes", () => {
+    // Unauthenticated, so it can be read before anything secret is sent.
+    const health = code(SERVE);
+    for (const field of ['service: "opencodex"', "pid: process.pid", "port: healthPort"]) {
+      expect(health).toContain(field);
+    }
+    const reader = proxy.slice(proxy.indexOf("pub fn identity_from("));
+    const body = reader.slice(0, reader.indexOf("\n}"));
+    expect(body).toContain('body.get("service")');
+    expect(body).toContain('body.get("pid")');
+    expect(body).toContain('body.get("port")');
+    // A 200 from something else on the port is not this proxy, and a body describing a different
+    // listener does not authorise a credential for this one.
+    expect(body).toContain("if port != addressed_port {");
+  });
+
+  test("the credential is never sent to an unconfirmed instance", () => {
+    const start = proxy.indexOf("async fn authorised_token(");
+    expect(start).toBeGreaterThan(-1);
+    const body = proxy.slice(start, proxy.indexOf("async fn send(", start));
+    expect(body).toContain("let Some(binding) = self.binding() else");
+    // Re-confirmed here, not trusted from when it was made: in between, the child can exit and
+    // something else can hold the port.
+    expect(body).toContain("let identity = self.identify().await?;");
+    expect(body).toContain("if identity != binding.identity");
+    expect(body).toContain("if self.binding() != Some(binding)");
+    const token = body.indexOf("self.auth.token()");
+    expect(token).toBeGreaterThan(body.indexOf("if self.binding() != Some(binding)"));
+  });
+
+  test("a request is bound to the pid, the port and the generation it was authorised under", () => {
+    expect(proxy).toContain("pub struct RuntimeIdentity {");
+    expect(proxy).toContain("pub pid: u32");
+    expect(proxy).toContain("pub port: u16");
+    expect(proxy).toContain("pub struct RuntimeBinding {");
+    expect(proxy).toContain("pub generation: u64");
+    const bind = proxy.slice(proxy.indexOf("pub fn bind("));
+    expect(bind.slice(0, bind.indexOf("\n    }"))).toContain("*generations += 1;");
+  });
+
+  test("the local management client refuses redirects and system proxies", () => {
+    const builder = proxy.slice(proxy.indexOf("Client::builder()"), proxy.indexOf(".build()?"));
+    expect(builder).toContain("redirect(redirect::Policy::none())");
+    expect(builder).toContain(".no_proxy()");
+  });
+
+  test("attaching to a runtime does not carry ownership of the last one", () => {
+    const lib = code(LIB);
+    const attach = lib.slice(lib.indexOf("pub fn attach("));
+    const body = attach.slice(0, attach.indexOf("\n    }"));
+    expect(body).toContain("self.confirmed.store(false, Ordering::Release)");
+    // A spawn records a pid; it does not record that the pid is the one holding the port.
+    const adopt = lib.slice(lib.indexOf("pub fn adopt("));
+    expect(adopt.slice(0, adopt.indexOf("\n    }"))).toContain(
+      "self.confirmed.store(false, Ordering::Release)",
+    );
+    const confirm = lib.slice(lib.indexOf("pub fn confirm_ownership("));
+    expect(confirm.slice(0, confirm.indexOf("\n    }"))).toContain(
+      "self.child_pid() == Some(identity.pid)",
+    );
+  });
+
+  test("ownership is confirmed from the answering pid before anything is stopped", () => {
+    const start = exit.indexOf("async fn confirm(");
+    expect(start).toBeGreaterThan(-1);
+    const body = exit.slice(start, exit.indexOf("fn hide_windows(", start));
+    expect(body).toContain("identity.pid == child_pid => Ownership::Ours");
+    expect(body).toContain("Ok(_) => Ownership::Foreign");
+    // Nothing listening is only proof the child is gone if the child said so.
+    expect(body).toContain("watch.exit().is_some()");
+    expect(body).toContain("Ownership::Unknown");
+    const drain = exit.slice(exit.indexOf("pub async fn drain_current("));
+    const drainBody = drain.slice(0, drain.indexOf("\nenum Ownership"));
+    expect(drainBody).toContain("Ownership::Foreign => DrainVerdict::Drained");
+    expect(drainBody).toContain("Ownership::Unknown => DrainVerdict::OwnershipUnknown");
+  });
+
+  test("the startup sequence is what grants ownership, and only on a readable answer", () => {
+    const startup = code(STARTUP);
+    const bind = startup.slice(startup.indexOf("async fn bind("));
+    const body = bind.slice(0, bind.indexOf("\n}"));
+    expect(body).toContain("proxy.identify()");
+    expect(body).toContain("proxy.bind(identity)");
+    expect(body).toContain("state.confirm_ownership(identity)");
+    // An answer that cannot be read leaves the app owning nothing.
+    expect(body).toContain("_ => return None,");
+    // And the sequence does not report Ready against an instance it could not identify: the
+    // management token is only ever sent to a bound one, so a dashboard there would not load.
+    const callers = startup.match(/bind\(app, &proxy, deadline\)\.await\.is_none\(\)/g) || [];
+    expect(callers).toHaveLength(2);
+  });
+
+  test("the app's own origin is allowed by both spellings, and nothing wider", () => {
+    const window = code(WINDOW);
+    const rule = window.slice(window.indexOf("fn is_app_origin("));
+    const body = rule.slice(0, rule.indexOf("\n}"));
+    // The custom scheme everywhere, and the http spelling WebView2 needs on Windows.
+    expect(body).toContain('"tauri" => true');
+    expect(body).toContain('url.host_str() == Some("tauri.localhost")');
+    // Not https, which is not the scheme the pinned Tauri serves the app over, and not a port,
+    // which would mean something else is answering.
+    expect(body).toContain("url.port().is_none()");
+    expect(body).not.toContain('"https"');
+    expect(window).toContain("if is_app_origin(url) {");
+    // Not localhost generally, and not a remote IPC widening.
+    expect(window).not.toContain('Some("localhost")');
+    expect(readFileSync(repoPath("desktop/src-tauri/capabilities/default.json"), "utf8")).not.toContain(
+      "remote",
+    );
+  });
+});
diff --git a/tests/clients/desktop-start-at-login-default.test.ts b/tests/clients/desktop-start-at-login-default.test.ts
new file mode 100644
index 00000000000..f968fd97ae5
--- /dev/null
+++ b/tests/clients/desktop-start-at-login-default.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * A menu bar app that is not running has no menu bar item, so leaving Start at Login off by
+ * default means an installed app is simply gone after a reboot. The desktop shell enables it once
+ * per installation.
+ *
+ * The ordering is the whole contract and it is not visible from behaviour alone, so it is read out
+ * of the source: the marker is written before the login item is touched, the enable is guarded by
+ * the current state, an existing marker returns early, and the tray is built afterwards so its
+ * checkbox reflects the result. Get the write order backwards and a user who turns the setting off
+ * has it turned back on for them on the next launch.
+ *
+ * The one-time rewrite that teaches an existing login item to announce itself is the exception, and
+ * it writes its marker the other way round on purpose — see the comment on it.
+ */
+const FIRST_RUN = repoPath("desktop/src-tauri/src/first_run.rs");
+const STARTUP = repoPath("desktop/src-tauri/src/startup.rs");
+
+function code(path: string): string {
+  return readFileSync(path, "utf8").replace(/\/\/[^\n]*/g, "");
+}
+
+describe("start at login default", () => {
+  const firstRun = code(FIRST_RUN);
+
+  test("an existing marker returns before anything is changed", () => {
+    const early = firstRun.indexOf("marker.exists()");
+    const enable = firstRun.indexOf("autolaunch().enable()");
+    expect(early).toBeGreaterThan(-1);
+    expect(enable).toBeGreaterThan(-1);
+    expect(early).toBeLessThan(enable);
+    expect(firstRun.slice(early, enable)).toContain("return");
+  });
+
+  test("the marker is written before the login item is registered", () => {
+    const write = firstRun.indexOf("fs::write(&marker");
+    const enable = firstRun.indexOf("autolaunch().enable()");
+    expect(write).toBeGreaterThan(-1);
+    expect(write).toBeLessThan(enable);
+  });
+
+  test("enabling is guarded by the current autolaunch state", () => {
+    const guard = firstRun.indexOf("autolaunch().is_enabled()");
+    const enable = firstRun.indexOf("autolaunch().enable()");
+    expect(guard).toBeGreaterThan(-1);
+    expect(guard).toBeLessThan(enable);
+  });
+
+  test("nothing ever deletes the marker", () => {
+    expect(firstRun).not.toContain("remove_file");
+    expect(firstRun).not.toContain("remove_dir");
+  });
+
+  test("it runs before the tray is installed", () => {
+    const startup = code(STARTUP);
+    const applied = startup.indexOf("first_run::apply_start_at_login_default");
+    const tray = startup.indexOf("crate::tray::install");
+    expect(applied).toBeGreaterThan(-1);
+    expect(tray).toBeGreaterThan(-1);
+    expect(applied).toBeLessThan(tray);
+  });
+
+  test("the launch-origin rewrite claims its marker only once it has succeeded", () => {
+    const start = firstRun.indexOf("pub fn adopt_launch_origin_argument");
+    expect(start).toBeGreaterThan(-1);
+    const body = firstRun.slice(start);
+    const enable = body.indexOf("autolaunch().enable()");
+    const claim = body.indexOf("fs::write(&claimed");
+    expect(enable).toBeGreaterThan(-1);
+    expect(claim).toBeGreaterThan(enable);
+    // It never turns the setting on or off; it only rewrites an entry that is already there.
+    expect(body).toContain("Ok(true) =>");
+    expect(body).not.toContain("autolaunch().disable()");
+  });
+});
diff --git a/tests/clients/desktop-startup-surface.test.ts b/tests/clients/desktop-startup-surface.test.ts
new file mode 100644
index 00000000000..2f1e6876fd6
--- /dev/null
+++ b/tests/clients/desktop-startup-surface.test.ts
@@ -0,0 +1,227 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * The startup surface exists before the work it reports on.
+ *
+ * Discovery, the liveness probe, the sidecar spawn and the health wait all used to run inside
+ * `setup()`, and the window was created hidden afterwards. Every failure in that stretch was
+ * therefore invisible: the spawn event stream was destructured into `_events` and dropped, so the
+ * child's exit code went with it, and a run of probes that time out rather than refuse takes over a
+ * minute with nothing on screen. Ordering is the whole of the fix, and a state that reports work
+ * already finished elsewhere is not a state — it is a label. Both are read out of the source.
+ */
+const SRC = "desktop/src-tauri/src";
+const LIB = repoPath(`${SRC}/lib.rs`);
+const SIDECAR = repoPath(`${SRC}/sidecar.rs`);
+const STARTUP = repoPath(`${SRC}/startup.rs`);
+const PROXY = repoPath(`${SRC}/proxy.rs`);
+const PAGE = repoPath("desktop/ui/main.js");
+const CONFIG = repoPath("desktop/src-tauri/tauri.conf.json");
+
+function code(path: string): string {
+  return readFileSync(path, "utf8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+}
+
+describe("desktop startup surface", () => {
+  const lib = code(LIB);
+  const startup = code(STARTUP);
+
+  test("the window is built and shown before the sequence that reports into it", () => {
+    const setup = lib.indexOf(".setup(|app|");
+    expect(setup).toBeGreaterThan(-1);
+    const built = lib.indexOf("WebviewWindowBuilder::new", setup);
+    const shown = lib.indexOf("window::show(&window)", setup);
+    const begun = lib.indexOf("startup::begin(app.handle())", setup);
+    expect(built).toBeGreaterThan(-1);
+    expect(shown).toBeGreaterThan(built);
+    expect(begun).toBeGreaterThan(shown);
+  });
+
+  test("setup resolves nothing, registers nothing and starts nothing", () => {
+    const setup = lib.slice(
+      lib.indexOf(".setup(|app|"),
+      lib.indexOf(".build(tauri::generate_context!())"),
+    );
+    expect(setup.length).toBeGreaterThan(0);
+    for (const call of [
+      "block_on",
+      "ensure_proxy",
+      "resolve::run",
+      "ProxyClient::new",
+      "tray_availability::detect()",
+      "tray::install",
+      "first_run::",
+      "sidecar::",
+    ]) {
+      expect(setup).not.toContain(call);
+    }
+  });
+
+  test("resolving and registering are states that own their work", () => {
+    expect(startup).toContain("Phase::Resolving");
+    // D5: the shell asks the bundled CLI rather than reading a port record and guessing.
+    expect(startup).toContain("resolve::run(app, deadline).await");
+    expect(startup).toContain("ProxyClient::new(endpoint");
+    expect(startup).toContain("Phase::Registering");
+    expect(startup).toContain("tray_availability::detect");
+    expect(startup).toContain("first_run::apply_start_at_login_default(app)");
+    expect(startup).toContain("crate::tray::install(&handle)");
+  });
+
+  test("the app's own surface is registered before the runtime is touched", () => {
+    const registering = startup.indexOf("Phase::Registering, None)");
+    const resolving = startup.indexOf("Phase::Resolving, None)");
+    const starting = startup.indexOf("Phase::Starting, None)");
+    expect(registering).toBeGreaterThan(-1);
+    expect(resolving).toBeGreaterThan(registering);
+    expect(starting).toBeGreaterThan(resolving);
+  });
+
+  test("the spawn event stream is consumed rather than discarded", () => {
+    const sidecar = code(SIDECAR);
+    expect(sidecar).not.toContain("_events");
+    expect(sidecar).toContain("let (events, child) = command.spawn()");
+    expect(sidecar).toContain("watch.follow(events)");
+    expect(sidecar).toContain("CommandEvent::Terminated(payload)");
+  });
+
+  test("the child's exit code is what ends the wait early", () => {
+    const wait = startup.indexOf("Phase::Waiting, None);");
+    expect(wait).toBeGreaterThan(-1);
+    const loop = startup.slice(wait, startup.indexOf("async fn register(", wait));
+    expect(loop).toContain("watch.exit()");
+    expect(loop).toContain("exit.describe()");
+  });
+
+  test("one deadline covers the whole sequence and bounds every probe under it", () => {
+    expect(startup).toContain("pub const DEADLINE: Duration");
+    expect(startup).toContain("let deadline = started + DEADLINE;");
+    // The budget for finding an existing runtime is the CLI's now, not a second one here: the
+    // tuned probe budgets exist because a shell-side reimplementation answered "nobody is
+    // listening" twice and started duplicate proxies.
+    expect(startup).not.toContain("ATTACH_BUDGET");
+    expect(startup).not.toContain("fn healthy_by");
+    expect(startup).toContain("resolve::run(app, deadline).await");
+    // A probe bounded only by the client's own timeout overruns whatever budget it was started
+    // under, which is how a stated ceiling becomes an unstated one.
+    expect(startup).not.toContain("proxy.is_alive()");
+    expect(startup).toContain("proxy.alive_within(deadline)");
+    // Registration waits on a session bus and on the main thread, and both can stall; neither is
+    // allowed to leave the page in a state whose retry could do nothing.
+    expect(startup).toContain("tokio::time::timeout_at(\n        deadline,");
+    expect(startup).toContain("tokio::time::timeout_at(deadline, receiver)");
+    const proxy = code(PROXY);
+    expect(proxy).toContain("timeout_at(deadline, self.is_alive())");
+    // The stop is the bundled CLI's now, under its own deadline.
+    const stop = code(repoPath("desktop/src-tauri/src/runtime_stop.rs"));
+    expect(stop).toContain("timeout_at(deadline, command.output())");
+    expect(stop).toContain("pub const DEADLINE: Duration");
+  });
+
+  test("a retry waits on the child it already started rather than starting a second one", () => {
+    expect(startup).toContain("&& watch.exit().is_none()");
+    const guard = startup.indexOf("if owns_live_child {");
+    const spawn = startup.indexOf("sidecar::start(app, endpoint, watch)");
+    expect(guard).toBeGreaterThan(-1);
+    expect(spawn).toBeGreaterThan(guard);
+  });
+
+  test("the diagnostic names the state, the endpoint, the home and how the child ended", () => {
+    const start = startup.indexOf("pub fn diagnostic(");
+    expect(start).toBeGreaterThan(-1);
+    const body = startup.slice(start, startup.indexOf("fn report(", start));
+    for (const field of [
+      "state:",
+      "reason:",
+      "elapsed:",
+      "endpoint:",
+      "home:",
+      "runtime process:",
+      "runtime output",
+    ]) {
+      expect(body).toContain(field);
+    }
+    expect(body).toContain("exit.describe()");
+  });
+
+  test("the snapshot carries the finished states, not just the current one", () => {
+    expect(startup).toContain("pub completed: Vec<&'static str>");
+    expect(startup).toContain("pub failed_phase: Option<&'static str>");
+    const page = readFileSync(PAGE, "utf8");
+    expect(page).toContain("progress.completed");
+    expect(page).toContain("progress.failedPhase");
+  });
+
+  test("the retry, the snapshot and the phase list are reachable from the page", () => {
+    const handler = lib.slice(
+      lib.indexOf("generate_handler!["),
+      lib.indexOf("])", lib.indexOf("generate_handler![")),
+    );
+    for (const command of ["startup_snapshot", "startup_phases", "retry_startup"]) {
+      expect(lib).toContain(`fn ${command}(`);
+      expect(handler).toContain(command);
+    }
+    expect(JSON.parse(readFileSync(CONFIG, "utf8")).app.withGlobalTauri).toBe(true);
+  });
+
+  test("the page derives its phases instead of restating them", () => {
+    const page = readFileSync(PAGE, "utf8");
+    expect(page).toContain('invoke("startup_phases")');
+    expect(page).toContain('invoke("startup_snapshot")');
+    expect(page).toContain('invoke("retry_startup")');
+    expect(page).toContain('listen("startup-phase"');
+    for (const phase of ["resolving", "probing", "attaching", "starting", "waiting", "registering"]) {
+      expect(page).not.toContain(`"${phase}"`);
+    }
+  });
+
+  test("every call into the shell can fail without leaving the page blank", () => {
+    const page = readFileSync(PAGE, "utf8");
+    expect(page).toContain("function reportPageFailure");
+    // Both entry points — the first load and the retry — have to catch, because either one
+    // failing silently leaves a window that says "Starting…" forever.
+    expect(page.match(/reportPageFailure\(/g) || []).toHaveLength(3);
+    const retry = page.slice(page.indexOf('retry.addEventListener'));
+    expect(retry.slice(0, 400)).toContain("catch");
+  });
+
+  test("the page never reaches for a dialog the webview cannot draw", () => {
+    const page = readFileSync(PAGE, "utf8")
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/\/\/[^\n]*/g, "");
+    // The call form, not the word: a method on a receiver or a property of that name is fine.
+    expect(page).not.toMatch(/(^|[^.\w$])(?:window\s*\.\s*)?(?:alert|confirm|prompt)\s*\(/);
+    expect(page).toContain("#diagnostic");
+    expect(page).toContain("clipboard.writeText");
+  });
+});
+
+/**
+ * The surface has to be able to stay silent.
+ *
+ * Two defects made it speak when it had nothing to say and stay quiet when it did. An id rule
+ * with display: grid outranks the user-agent [hidden] { display: none } rule, so the failure
+ * block - the Retry button and the empty diagnostic box - was painted during every normal start.
+ * And an invoke whose command never answers returns a promise that neither settles nor rejects,
+ * so the page kept its initial markup for as long as the shell stayed silent. Together they are
+ * the screen a user reads as a dead application: a starting headline, no checklist, one Retry.
+ */
+describe("the bootstrap page reports only what it was told", () => {
+  const markup = readFileSync(repoPath("desktop/ui/index.html"), "utf8");
+  const page = readFileSync(PAGE, "utf8");
+
+  test("the failure block honours its hidden attribute", () => {
+    expect(/#failure\[hidden\][^{]*\{[^}]*display:\s*none/.test(markup)).toBe(true);
+  });
+
+  test("the handshake with the shell is bounded", () => {
+    expect(page).toContain("HANDSHAKE_DEADLINE_MS");
+    for (const command of ["startup_phases", "startup_snapshot"]) {
+      const bounded = 'withDeadline(invoke(\"' + command + '\")';
+      expect(page.includes(bounded)).toBe(true);
+    }
+    expect(page).toContain("withDeadline(listen(");
+  });
+});
diff --git a/tests/clients/desktop-tray-availability.test.ts b/tests/clients/desktop-tray-availability.test.ts
new file mode 100644
index 00000000000..d230f606edd
--- /dev/null
+++ b/tests/clients/desktop-tray-availability.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * INV-DESKTOP-02 — tray availability is an answer from the session, and where there is none the
+ * window is shown and closing it quits through the same graceful drain.
+ *
+ * The pinned Linux backend creates an AppIndicator and reports success without checking that
+ * anything will display it, so `TrayIconBuilder::build` returning `Ok` proves nothing. Nor does the
+ * watcher merely existing: a StatusNotifierWatcher with no host attached still accepts
+ * registrations and still draws nothing, which is why the question asked is the specification's own
+ * — is a host registered. On stock GNOME the answer is no, and the shell's macOS-shaped assumptions
+ * (a window created hidden, a close that always hides) then left a running process with no way back
+ * in. The probe and the branches it feeds are read out of the source because a hosted Linux runner
+ * has no graphical session to observe them in.
+ */
+const SRC = "desktop/src-tauri/src";
+const AVAILABILITY = repoPath(`${SRC}/tray_availability.rs`);
+const LIB = repoPath(`${SRC}/lib.rs`);
+const EXIT = repoPath(`${SRC}/exit.rs`);
+const STARTUP = repoPath(`${SRC}/startup.rs`);
+
+function code(path: string): string {
+  return readFileSync(path, "utf8").replace(/\/\/[^\n]*/g, "");
+}
+
+describe("desktop tray availability", () => {
+  const availability = code(AVAILABILITY);
+  const startup = code(STARTUP);
+
+  test("the probe asks whether a host is registered, not whether a watcher exists", () => {
+    expect(availability).toContain('"org.kde.StatusNotifierWatcher"');
+    expect(availability).toContain('"IsStatusNotifierHostRegistered"');
+    expect(availability).toContain("Connection::new_session()");
+    expect(availability).toContain('#[cfg(target_os = "linux")]');
+    // A name that merely has an owner is the weaker question this replaces.
+    expect(availability).not.toContain("NameHasOwner");
+  });
+
+  test("an unanswerable probe is read the same way as a watcher with no host", () => {
+    const start = availability.indexOf("pub fn from_host_registered");
+    expect(start).toBeGreaterThan(-1);
+    const body = availability.slice(start, availability.indexOf("\n}", start));
+    expect(body).toContain("Some(true) => TrayAvailability::Available");
+    expect(body).toContain("Some(false) | None => TrayAvailability::Unavailable");
+  });
+
+  test("nothing is assumed on the platform that needs the probe", () => {
+    const start = availability.indexOf("pub fn assumed()");
+    expect(start).toBeGreaterThan(-1);
+    const body = availability.slice(start, availability.indexOf("\n    }", start));
+    expect(body).toContain('cfg!(target_os = "linux")');
+    expect(body).toContain("Self::Unavailable");
+    // The window can be closed before the probe answers, so the coordinator starts from the
+    // platform assumption rather than from optimism.
+    expect(code(EXIT)).toContain("TrayAvailability::assumed().hides_to_tray()");
+  });
+
+  test("the verdict reaches the coordinator that decides what a close means", () => {
+    expect(startup).toContain("coordinator.set_tray(verdict)");
+    expect(code(EXIT)).toContain("pub fn set_tray(&self, tray: TrayAvailability)");
+    expect(code(repoPath(`${SRC}/window.rs`))).toContain("exit::gesture(");
+    expect(code(EXIT)).toContain("decide(inner.phase, inner.reason, inner.hides_to_tray)");
+  });
+
+  test("a tray is only claimed once an icon exists to claim", () => {
+    // The verdict is published after the install, not before it: announcing a tray and then
+    // failing to build one would hide the window into nothing.
+    const verdict = startup.indexOf("let verdict = if tray.is_available() && install_tray(app, deadline).await");
+    const published = startup.indexOf("coordinator.set_tray(verdict)");
+    expect(verdict).toBeGreaterThan(-1);
+    expect(published).toBeGreaterThan(verdict);
+    expect(startup.slice(verdict, published)).toContain("TrayAvailability::Unavailable");
+  });
+
+  test("a retry does not register a second tray", () => {
+    const register = startup.slice(startup.indexOf("async fn register("), startup.indexOf("async fn install_tray("));
+    expect(register).toContain("startup.registration()");
+    expect(register.indexOf("return done;")).toBeLessThan(register.indexOf("install_tray(app, deadline)"));
+    expect(register).toContain("startup.remember_registration(registration.clone())");
+  });
+
+  test("tray availability decides the launch, not the origin of the launch", () => {
+    const start = startup.indexOf("pub fn shows_window");
+    expect(start).toBeGreaterThan(-1);
+    const body = startup.slice(start, startup.indexOf("\n}", start));
+    expect(body).toContain("!tray.is_available() || origin == LaunchOrigin::User");
+    // The window is shown from inside the sequence, once the verdict is in, so a login launch on a
+    // session with no tray is not left hidden with nothing to reopen it from.
+    expect(startup).toContain("if shows_window(LaunchOrigin::detect(), verdict)");
+    expect(code(LIB)).toContain("startup::LaunchOrigin::detect() == startup::LaunchOrigin::User");
+  });
+});
diff --git a/tests/clients/desktop-widget-entry.test.ts b/tests/clients/desktop-widget-entry.test.ts
new file mode 100644
index 00000000000..6871bbd56cc
--- /dev/null
+++ b/tests/clients/desktop-widget-entry.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+
+/**
+ * The WidgetKit extension needs two things that look unrelated, and either one alone produces a
+ * widget that is never offered in the gallery with nothing in the build to say so.
+ *
+ * Without `@main` on the WidgetBundle, nothing references it, the linker drops it, and the
+ * extension still registers with `pluginkit` because the Info.plist alone is enough. The gallery
+ * then has no configuration to offer. That is what shipped.
+ *
+ * Without the `_NSExtensionMain` linker entry, the Swift main runs instead of the extension host's
+ * bootstrap and ExtensionFoundation traps in `_EXRunningExtension._shared` — EXC_BREAKPOINT on
+ * every launch, one crash report per attempt, and `chronod` logging
+ * "query failed - will try lazy reload later".
+ *
+ * Both were measured on a real install. Neither is visible to a build that only checks the bundle
+ * is well formed and the signature verifies, which is why they are asserted from the source.
+ */
+const PACKAGE = repoPath("app/Package.swift");
+const VIEWS = repoPath("app/Sources/OpenCodexWidget/Views.swift");
+
+function stripComments(source: string): string {
+  return source.replace(/\/\/[^\n]*/g, "");
+}
+
+describe("widget extension entry point", () => {
+  test("the linker entry is NSExtensionMain, as it is for an Xcode app-extension target", () => {
+    const code = stripComments(readFileSync(PACKAGE, "utf8"));
+    expect(code).toContain("_NSExtensionMain");
+  });
+
+  test("the target is compiled in extension-only mode", () => {
+    // Xcode's app-extension target sets APPLICATION_EXTENSION_API_ONLY; SwiftPM has no such
+    // target, so the compiler's spelling is passed by hand. It belongs beside the linker entry
+    // because the two are one contract: the projects that have a SwiftPM widget extension
+    // working supply both, and dropping either brings back a failure that the build, the
+    // signature and the registration all continue to look fine through.
+    const code = stripComments(readFileSync(PACKAGE, "utf8"));
+    expect(code).toContain("-application-extension");
+  });
+
+  test("the widget bundle is the Swift entry, so the linker keeps it", () => {
+    const views = readFileSync(VIEWS, "utf8");
+    expect(views).toMatch(/@main\s*\n\s*struct OpenCodexWidgetBundle: WidgetBundle/);
+  });
+
+  test("there is no main.swift competing with @main", () => {
+    // SwiftPM refuses @main in a target that also has a main.swift, and the refusal is a build
+    // error rather than a silent fallback - but the file existing at all means someone moved the
+    // entry back out of the bundle.
+    expect(existsSync(repoPath("app/Sources/OpenCodexWidget/main.swift"))).toBe(false);
+  });
+
+  test("the bundle actually carries a widget", () => {
+    const views = readFileSync(VIEWS, "utf8");
+    // A WidgetBundle with an empty body offers nothing, which is the same failure by another route.
+    expect(views).toMatch(/OpenCodexWidget\(\)/);
+    expect(views).toMatch(/configurationDisplayName/);
+  });
+});
diff --git a/tests/clients/integrations-current-store.test.ts b/tests/clients/integrations-current-store.test.ts
new file mode 100644
index 00000000000..089c8e1de93
--- /dev/null
+++ b/tests/clients/integrations-current-store.test.ts
@@ -0,0 +1,381 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  OPENCODE_PROVIDER_ID,
+  ZCODE_STORE_MODEL_RULES_PATH,
+  ZCODE_STORE_PROVIDER_RULES_PATH,
+  ZCODE_STORE_SCHEMA_VERSION,
+  buildZcodeStoreProviderRule,
+  type ExportModel,
+} from "../../src/clients/config-export";
+import { formatSelectorConjunction } from "../../src/integrations/merge";
+import { DYNAMIC_SEGMENT, previewIntegration } from "../../src/integrations/mutation-plan";
+import { fingerprint } from "../../src/integrations/ownership";
+import { INTEGRATION_CLIENTS } from "../../src/integrations/registry";
+import { exportContextOf, readIntegrationState, readPath } from "../../src/integrations/state";
+import { createIntegrationStateStore, type IntegrationStateStore } from "../../src/integrations/store";
+import {
+  applyIntegration,
+  disableIntegration,
+  overwriteIntegration,
+  refreshIntegration,
+  restoreIntegration,
+  type IntegrationWriteInput,
+} from "../../src/integrations/writer";
+import type { OcxConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+/**
+ * Writing the store the client actually reads (#5348).
+ *
+ * The sibling file covers the refusal, which is what happens when this file's
+ * precondition fails. Here the store carries a schema whose shape has been
+ * observed, so enable, refresh and disable all act on it — and the properties
+ * worth pinning are the ones that make that safe rather than merely working:
+ * a rule the user owns is never taken over, a rule belonging to another
+ * provider is never matched by ours, and the client's file is never deleted.
+ *
+ * Every location comes from the exported schema constants rather than a
+ * literal, so a change to where the store keeps its rules moves the fixture
+ * with the source instead of leaving it green against a shape nobody writes.
+ */
+let home: string;
+let store: IntegrationStateStore;
+
+const TEST_ENV = {} as NodeJS.ProcessEnv;
+
+const MODELS: ExportModel[] = [
+  { namespaced: "anthropic/claude-opus-4-8", provider: "anthropic", id: "claude-opus-4-8", contextWindow: 200_000 },
+];
+
+const MORE_MODELS: ExportModel[] = [
+  ...MODELS,
+  { namespaced: "xai/grok-4-2", provider: "xai", id: "grok-4-2", contextWindow: 256_000 },
+];
+
+const CONFIG: OcxConfig = {
+  port: 10100,
+  hostname: "127.0.0.1",
+  defaultProvider: "mock",
+  providers: { mock: { adapter: "openai-chat", baseUrl: "http://127.0.0.1/v1" } },
+} as unknown as OcxConfig;
+
+const spec = () => INTEGRATION_CLIENTS.zcode;
+
+function conjunction(criteria: Parameters<typeof formatSelectorConjunction>[0]): string {
+  const selector = formatSelectorConjunction(criteria);
+  if (selector === null) throw new Error("test fixture must be a valid conjunction");
+  return selector;
+}
+
+function withoutLastCriterion(selector: string): string {
+  const separator = selector.lastIndexOf(",");
+  if (separator < 0) throw new Error("test fixture must contain multiple criteria");
+  return `${selector.slice(0, separator)}${selector.slice(-1)}`;
+}
+
+/** The rule paths, spelled the way the contribution spells them. */
+const OUR_PROVIDER_RULE = [...ZCODE_STORE_PROVIDER_RULES_PATH, `[providerId=${OPENCODE_PROVIDER_ID}]`];
+const ourModelRule = (modelId: string) => [
+  ...ZCODE_STORE_MODEL_RULES_PATH,
+  conjunction([
+    { field: "providerId", value: OPENCODE_PROVIDER_ID },
+    { field: "modelId", value: modelId },
+  ]),
+];
+
+beforeEach(() => {
+  const base = mkdtempSync(join(tmpdir(), "ocx-current-store-"));
+  home = join(base, "home");
+  mkdirSync(home, { recursive: true });
+  store = createIntegrationStateStore(join(base, "store", "integrations"));
+});
+
+afterEach(() => {
+  removeTreeWithRetry(dirname(home));
+});
+
+function configPath(): string {
+  return spec().configPath(TEST_ENV, home);
+}
+
+function storePath(): string {
+  return spec().currentStore!.path(TEST_ENV, home);
+}
+
+/** Install the client and give it a store the way a first launch would. */
+function installWithStore(contents: unknown = { schemaVersion: ZCODE_STORE_SCHEMA_VERSION, config: {} }): string {
+  mkdirSync(spec().detectDir(TEST_ENV, home), { recursive: true });
+  mkdirSync(dirname(configPath()), { recursive: true });
+  const path = storePath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(contents, null, 2)}\n`);
+  return path;
+}
+
+function readStore(): unknown {
+  return JSON.parse(readFileSync(storePath(), "utf8"));
+}
+
+function input(overrides: Partial<IntegrationWriteInput> = {}): IntegrationWriteInput {
+  return { clientId: "zcode", models: MODELS, config: CONFIG, port: 10100, env: TEST_ENV, home, store, ...overrides };
+}
+
+describe("writing the provider store the client reads", () => {
+  test("enable puts the intended provider in the store, and leaves the config file alone", () => {
+    const path = installWithStore();
+
+    const result = applyIntegration(input());
+
+    expect(result.ok).toBe(true);
+    // The whole point: the rule is in the file the client opens, in the shape
+    // that file's reader understands.
+    // Compared against the builder through the same context the writer derives,
+    // so the base URL is the one `ocx export` composes rather than a literal.
+    expect(readPath(readStore(), OUR_PROVIDER_RULE))
+      .toEqual(buildZcodeStoreProviderRule(exportContextOf(input())));
+    expect(readPath(readStore(), ourModelRule("anthropic/claude-opus-4-8")))
+      .toMatchObject({ config: { properties: { contextWindow: 200_000 } } });
+    // And nothing was written to the file it stopped reading.
+    expect(existsSync(configPath())).toBe(false);
+    // Ownership follows the file that was written, so a later disable removes
+    // from there rather than from the config path.
+    expect(store.readRecords().zcode?.configPath).toBe(path);
+  });
+
+  test("status reports the store as the file this integration is about", () => {
+    const path = installWithStore();
+    expect(applyIntegration(input()).ok).toBe(true);
+
+    const status = readIntegrationState(input());
+
+    expect(status).toMatchObject({ state: "current", configPath: path });
+    // No notice, because there is no second file the client reads instead.
+    expect(status.supersededBy).toBeUndefined();
+  });
+
+  test("a catalog refresh updates the store rather than reporting nothing to do", () => {
+    installWithStore();
+    expect(applyIntegration(input()).ok).toBe(true);
+
+    const refreshed = refreshIntegration(input({ models: MORE_MODELS }));
+
+    expect(refreshed.ok).toBe(true);
+    const rule = readPath(readStore(), OUR_PROVIDER_RULE) as { config: { personalModelIds: string[] } };
+    expect(rule.config.personalModelIds).toEqual(MORE_MODELS.map(model => model.namespaced).sort());
+    expect(readPath(readStore(), ourModelRule("xai/grok-4-2"))).toBeDefined();
+  });
+
+  test("an unrepresentable model stays in the provider roster without a model-rule fragment", () => {
+    const unrepresentable: ExportModel = {
+      namespaced: "anthropic/model,variant",
+      provider: "anthropic",
+      id: "model,variant",
+      contextWindow: 128_000,
+    };
+    installWithStore();
+    expect(applyIntegration(input({ models: [...MODELS, unrepresentable] })).ok).toBe(true);
+
+    const provider = readPath(readStore(), OUR_PROVIDER_RULE) as { config: { personalModelIds: string[] } };
+    const rules = readPath(readStore(), ZCODE_STORE_MODEL_RULES_PATH) as Array<{ modelId: string }>;
+    expect(provider.config.personalModelIds).toContain(unrepresentable.namespaced);
+    expect(rules.map(rule => rule.modelId)).toEqual(MODELS.map(model => model.namespaced));
+  });
+
+  test("disable leaves nothing this project put in the store, and keeps the file", () => {
+    const theirProvider = { providerId: "their-provider", enabled: true, providerName: "Theirs", config: {} };
+    const theirModel = {
+      providerId: "their-provider",
+      // The SAME model id as ours, under a different provider. A selector naming
+      // only the model would have matched this rule and replaced it.
+      modelId: "anthropic/claude-opus-4-8",
+      config: { properties: { contextWindow: 1 } },
+    };
+    installWithStore({
+      schemaVersion: ZCODE_STORE_SCHEMA_VERSION,
+      config: {
+        providerConfigRules: { providerRules: [theirProvider] },
+        modelConfigRules: { providerModelRules: [theirModel] },
+      },
+    });
+    expect(applyIntegration(input()).ok).toBe(true);
+    expect(readPath(readStore(), ourModelRule("anthropic/claude-opus-4-8"))).toBeDefined();
+
+    const disabled = disableIntegration(input());
+
+    expect(disabled.ok).toBe(true);
+    expect(readPath(readStore(), OUR_PROVIDER_RULE)).toBeUndefined();
+    expect(readPath(readStore(), ourModelRule("anthropic/claude-opus-4-8"))).toBeUndefined();
+    // Theirs survives, including the model rule our selector deliberately does
+    // not match, and the file itself is still the file the client reads.
+    expect(readPath(readStore(), [...ZCODE_STORE_PROVIDER_RULES_PATH, "[providerId=their-provider]"]))
+      .toEqual(theirProvider);
+    expect(readPath(readStore(), [...ZCODE_STORE_MODEL_RULES_PATH, conjunction([
+      { field: "providerId", value: "their-provider" },
+      { field: "modelId", value: "anthropic/claude-opus-4-8" },
+    ])]))
+      .toEqual(theirModel);
+    expect(existsSync(storePath())).toBe(true);
+    expect(readIntegrationState(input())).toMatchObject({ state: "absent" });
+  });
+
+  test("a rule the user owns is not taken over, and overwrite is the only way past it", () => {
+    // The shape the client's own migration produces: our provider id, in the
+    // store, with no ownership record of ours behind it.
+    const migrated = {
+      providerId: OPENCODE_PROVIDER_ID,
+      enabled: false,
+      providerName: "Hand edited",
+      config: { personalModelIds: ["kept"] },
+    };
+    installWithStore({
+      schemaVersion: ZCODE_STORE_SCHEMA_VERSION,
+      config: { providerConfigRules: { providerRules: [migrated] } },
+    });
+
+    const refused = applyIntegration(input());
+
+    expect(refused.ok).toBe(false);
+    if (!refused.ok) expect(refused.reason).toBe("conflict");
+    expect(readPath(readStore(), OUR_PROVIDER_RULE)).toEqual(migrated);
+
+    expect(overwriteIntegration(input()).ok).toBe(true);
+    expect(readPath(readStore(), OUR_PROVIDER_RULE)).toMatchObject({ enabled: true });
+  });
+
+  test("a schema we cannot establish falls back to reporting the write as ineffective", () => {
+    // One past the version whose shape has been observed. The file is perfectly
+    // readable; what is missing is any basis for asserting a nesting inside it.
+    const path = installWithStore({ schemaVersion: ZCODE_STORE_SCHEMA_VERSION + 1, config: {} });
+    const before = readFileSync(path, "utf8");
+
+    const result = applyIntegration(input());
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("superseded_store");
+      expect(result.message).toContain(path);
+    }
+    expect(readFileSync(path, "utf8")).toBe(before);
+    expect(existsSync(configPath())).toBe(false);
+    expect(readIntegrationState(input()).supersededBy).toBe(path);
+  });
+
+  test("a block applied before the client moved keeps the operation on that file", () => {
+    // Applied while the client still read its config file...
+    mkdirSync(spec().detectDir(TEST_ENV, home), { recursive: true });
+    mkdirSync(dirname(configPath()), { recursive: true });
+    expect(applyIntegration(input()).ok).toBe(true);
+    // ...and only then does the client create the store it reads now.
+    const path = installWithStore();
+
+    const refused = refreshIntegration(input({ models: MORE_MODELS }));
+
+    expect(refused.ok).toBe(false);
+    if (!refused.ok) {
+      expect(refused.reason).toBe("superseded_store");
+      // Both files, because the remedy names both.
+      expect(refused.message).toContain(configPath());
+      expect(refused.message).toContain(path);
+    }
+    // Nothing was orphaned: the store is untouched and our block is still
+    // where the record says it is, so disable can remove it.
+    expect(readPath(readStore(), OUR_PROVIDER_RULE)).toBeUndefined();
+    expect(readIntegrationState(input())).toMatchObject({ state: "current", configPath: configPath(), supersededBy: path });
+
+    expect(disableIntegration(input()).ok).toBe(true);
+    expect(readFileSync(configPath(), "utf8")).not.toContain("opencodex");
+    // And now the same switch reaches the client.
+    expect(applyIntegration(input()).ok).toBe(true);
+    expect(readPath(readStore(), OUR_PROVIDER_RULE)).toBeDefined();
+  });
+
+  test("an unreadable recorded selector keeps a config-file operation on that file", () => {
+    mkdirSync(spec().detectDir(TEST_ENV, home), { recursive: true });
+    mkdirSync(dirname(configPath()), { recursive: true });
+    expect(applyIntegration(input()).ok).toBe(true);
+    const record = store.readRecords().zcode!;
+    const malformed = withoutLastCriterion(conjunction([
+      { field: "providerId", value: OPENCODE_PROVIDER_ID },
+      { field: "modelId", value: MODELS[0]!.namespaced },
+    ]));
+    store.putRecord({
+      ...record,
+      fragmentPaths: [[...ZCODE_STORE_MODEL_RULES_PATH, malformed]],
+    });
+    const currentStorePath = installWithStore();
+
+    expect(readIntegrationState(input())).toMatchObject({
+      state: "unsafe",
+      reason: "unparseable",
+      configPath: configPath(),
+      supersededBy: currentStorePath,
+    });
+    expect(readPath(readStore(), OUR_PROVIDER_RULE)).toBeUndefined();
+  });
+
+  test("restore preview treats an unreadable prior selector as an unknown replacement", () => {
+    const path = installWithStore();
+    expect(applyIntegration(input()).ok).toBe(true);
+    const priorRecord = store.readRecords().zcode!;
+    const malformed = withoutLastCriterion(conjunction([
+      { field: "providerId", value: OPENCODE_PROVIDER_ID },
+      { field: "modelId", value: MODELS[0]!.namespaced },
+    ]));
+    const before = readFileSync(path, "utf8");
+    const opId = "restore-malformed-selector";
+    store.appendJournal({
+      opId,
+      clientId: "zcode",
+      kind: "refresh",
+      at: "2026-09-21T00:00:00.000Z",
+      configPath: path,
+      snapshot: store.captureSnapshot("zcode", opId, before),
+      resultFingerprint: fingerprint(before),
+      resultAbsent: false,
+      priorRecord: {
+        ...priorRecord,
+        fragmentPaths: [[...ZCODE_STORE_MODEL_RULES_PATH, malformed]],
+      },
+    });
+
+    const plan = previewIntegration(input(), { operation: "restore", opId });
+
+    expect(plan.canApply).toBe(true);
+    expect(plan.refusalReason).toBeUndefined();
+    expect(plan.changes).toContainEqual({
+      kind: "replace",
+      path: `${ZCODE_STORE_MODEL_RULES_PATH.join(".")}.${DYNAMIC_SEGMENT}`,
+    });
+  });
+
+  test("an undo of a store apply puts the store back", () => {
+    const path = installWithStore();
+    const before = readFileSync(path, "utf8");
+    const applied = applyIntegration(input());
+    expect(applied.ok).toBe(true);
+    if (!applied.ok) return;
+
+    // Undo used to require the row to name the config file, which would have
+    // made every store operation unrestorable.
+    const undone = restoreIntegration({ ...input(), opId: applied.opId! });
+
+    expect(undone.ok).toBe(true);
+    expect(readFileSync(path, "utf8")).toBe(before);
+  });
+
+  test("the plan publishes the managed template, never a model id", () => {
+    installWithStore();
+
+    const plan = previewIntegration(input(), { operation: "apply" });
+
+    expect(plan.canApply).toBe(true);
+    const paths = plan.changes.map(change => change.path);
+    expect(paths).toContain(`${ZCODE_STORE_PROVIDER_RULES_PATH.join(".")}.[providerId=${OPENCODE_PROVIDER_ID}]`);
+    // The model rule carries the model id inside its own selector, so the
+    // published segment is the dynamic template and the id never leaves.
+    expect(paths.some(path => path.includes("anthropic/claude-opus-4-8"))).toBe(false);
+  });
+});
diff --git a/tests/clients/integrations-merge.test.ts b/tests/clients/integrations-merge.test.ts
index 6585d9f1e93..d663c3fefb3 100644
--- a/tests/clients/integrations-merge.test.ts
+++ b/tests/clients/integrations-merge.test.ts
@@ -5,8 +5,10 @@ import { dirname, join } from "node:path";
 import type { ExportModel, ManagedContribution } from "../../src/clients/config-export";
 import {
   AmbiguousSelectorError,
+  InvalidSelectorError,
   createdContainerPaths,
   deletePath,
+  formatSelectorConjunction,
   parseSegment,
   setPath,
 } from "../../src/integrations/merge";
@@ -32,21 +34,65 @@ const OURS = { id: "opencodex", name: "OpenCodex" };
 const THEIRS = { id: "lmstudio", name: "LM Studio" };
 const SELECT = ["providers", "[id=opencodex]"] as const;
 
+function conjunction(criteria: Parameters<typeof formatSelectorConjunction>[0]): string {
+  const selector = formatSelectorConjunction(criteria);
+  if (selector === null) throw new Error("test fixture must be a valid conjunction");
+  return selector;
+}
+
+function withoutLastCriterion(selector: string): string {
+  const separator = selector.lastIndexOf(",");
+  if (separator < 0) throw new Error("test fixture must contain multiple criteria");
+  return `${selector.slice(0, separator)}${selector.slice(-1)}`;
+}
+
 function contribution(path: readonly string[], value: unknown = OURS): ManagedContribution {
   return { clientId: "raycast", fragments: [{ path, value }] };
 }
 
 describe("parseSegment", () => {
   test("a selector splits into field and value; anything else is a key", () => {
-    expect(parseSegment("[id=opencodex]")).toEqual({ kind: "select", field: "id", value: "opencodex" });
+    expect(parseSegment("[id=opencodex]"))
+      .toEqual({ kind: "select", criteria: [{ field: "id", value: "opencodex" }] });
     expect(parseSegment("[model_id=anthropic/claude-opus-5]"))
-      .toEqual({ kind: "select", field: "model_id", value: "anthropic/claude-opus-5" });
+      .toEqual({ kind: "select", criteria: [{ field: "model_id", value: "anthropic/claude-opus-5" }] });
     expect(parseSegment("providers")).toEqual({ kind: "key", key: "providers" });
     // Near misses stay keys: a client whose map literally has such a key keeps working.
     expect(parseSegment("[id=]")).toEqual({ kind: "key", key: "[id=]" });
     expect(parseSegment("[=x]")).toEqual({ kind: "key", key: "[=x]" });
     expect(parseSegment("[id=x")).toEqual({ kind: "key", key: "[id=x" });
   });
+
+  test("unversioned selectors keep commas and equals inside one legacy value", () => {
+    expect(parseSegment("[id=a,b=c]")).toEqual({
+      kind: "select",
+      criteria: [{ field: "id", value: "a,b=c" }],
+    });
+    expect(parseSegment("[name=Acme, Inc.]"))
+      .toEqual({ kind: "select", criteria: [{ field: "name", value: "Acme, Inc." }] });
+  });
+
+  test("a formatted conjunction names every criterion and malformed marked input is refused", () => {
+    const criteria = [
+      { field: "providerId", value: "opencodex" },
+      { field: "modelId", value: "anthropic/claude-opus-5" },
+    ];
+    const selector = conjunction(criteria);
+    expect(parseSegment(selector)).toEqual({ kind: "select", criteria });
+    expect(() => parseSegment(withoutLastCriterion(selector))).toThrow(InvalidSelectorError);
+  });
+
+  test("the conjunction formatter refuses unrepresentable criteria", () => {
+    const invalid: Parameters<typeof formatSelectorConjunction>[0][] = [
+      [],
+      [{ field: "id", value: "one" }],
+      [{ field: "not-a-field", value: "one" }, { field: "id", value: "two" }],
+      [{ field: "providerId", value: "" }, { field: "modelId", value: "two" }],
+      [{ field: "providerId", value: "one,two" }, { field: "modelId", value: "two" }],
+      [{ field: "providerId", value: "one]two" }, { field: "modelId", value: "two" }],
+    ];
+    for (const criteria of invalid) expect(formatSelectorConjunction(criteria)).toBeNull();
+  });
 });
 
 describe("setPath with a selector", () => {
@@ -153,6 +199,23 @@ describe("readPath and blockedContainerPath with a selector", () => {
     expect(blockedContainerPath({ providers: [{ id: "opencodex", name: 1 }] }, contribution(["providers", "[id=opencodex]", "name", "leaf"], "X")))
       .toEqual(["providers", "[id=opencodex]", "name"]);
   });
+
+  test("a formatted conjunction selects only the row matching every criterion", () => {
+    const modelId = "anthropic/claude-opus-5";
+    const selector = conjunction([
+      { field: "providerId", value: "opencodex" },
+      { field: "modelId", value: modelId },
+    ]);
+    const both = { providerId: "opencodex", modelId, owner: "both" };
+    const doc = {
+      rules: [
+        { providerId: "opencodex", modelId: "other", owner: "provider-only" },
+        { providerId: "other", modelId, owner: "model-only" },
+        both,
+      ],
+    };
+    expect(readPath(doc, ["rules", selector])).toEqual(both);
+  });
 });
 
 describe("plain-key paths are unchanged", () => {
@@ -254,6 +317,20 @@ describe("raycast writer round trip", () => {
     expect(Bun.YAML.parse(readFileSync(configPath, "utf8"))).toEqual({ providers: { opencodex: {} } });
   });
 
+  test("a persisted legacy selector keeps its comma-and-equals value", () => {
+    const configPath = installRaycast();
+    writeFileSync(configPath, Bun.YAML.stringify({ providers: [THEIRS] }));
+    expect(applyIntegration(input())).toMatchObject({ ok: true });
+
+    const legacyPath = ["providers", "[id=a,b=c]"];
+    store.putRecord({ ...store.readRecords().raycast!, fragmentPaths: [legacyPath] });
+    const persistedPath = store.readRecords().raycast!.fragmentPaths[0]!;
+    const legacyRow = { id: "a,b=c", owner: "legacy" };
+    const apparentConjunctionRow = { id: "a", b: "c", owner: "other" };
+
+    expect(readPath({ providers: [apparentConjunctionRow, legacyRow] }, persistedPath)).toEqual(legacyRow);
+  });
+
   for (const recorded of [false, true]) {
     for (const count of [0, 1, 2]) {
       test(`${count} matching rows with record=${recorded} agree across status and mutation`, () => {
diff --git a/tests/clients/integrations-superseded-store.test.ts b/tests/clients/integrations-superseded-store.test.ts
new file mode 100644
index 00000000000..4ee1c3c3be3
--- /dev/null
+++ b/tests/clients/integrations-superseded-store.test.ts
@@ -0,0 +1,211 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { ClientPathError, type ExportModel } from "../../src/clients/config-export";
+import { previewIntegration } from "../../src/integrations/mutation-plan";
+import { INTEGRATION_CLIENTS } from "../../src/integrations/registry";
+import { resolveIntegrationTarget } from "../../src/integrations/target";
+import { createIntegrationStateStore, type IntegrationStateStore } from "../../src/integrations/store";
+import { readIntegrationState } from "../../src/integrations/state";
+import {
+  applyIntegration,
+  disableIntegration,
+  refreshIntegration,
+  type IntegrationWriteInput,
+} from "../../src/integrations/writer";
+import type { OcxConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+/**
+ * A write the client cannot read is refused, not reported (#5348).
+ *
+ * ZCode 3.14 moved its providers to a second file and kept the first one
+ * reachable only through an import that runs once, on an install that has never
+ * created the second. Everything the integration checks still passed: the file
+ * was writable, the block merged, the journal recorded a correct apply. The
+ * only wrong part was the report, so these cases are about what the operation
+ * SAYS as much as what it writes.
+ *
+ * These are the cases where the store cannot be written: it holds no document
+ * whose schema has been observed, or it is not there at all. Writing the store
+ * is the sibling file; this one is what happens when that is impossible, which
+ * is why the refusal has to stay correct rather than become dead code.
+ *
+ * Every path here comes from the registry resolvers rather than a literal, so a
+ * change to where either file lives moves the fixture with the source instead
+ * of leaving it green against a location nobody uses.
+ */
+let home: string;
+let store: IntegrationStateStore;
+
+const TEST_ENV = {} as NodeJS.ProcessEnv;
+
+const MODELS: ExportModel[] = [
+  { namespaced: "anthropic/claude-opus-4-8", provider: "anthropic", id: "claude-opus-4-8", contextWindow: 200_000 },
+];
+
+const CONFIG: OcxConfig = {
+  port: 10100,
+  hostname: "127.0.0.1",
+  defaultProvider: "mock",
+  providers: { mock: { adapter: "openai-chat", baseUrl: "http://127.0.0.1/v1" } },
+} as unknown as OcxConfig;
+
+beforeEach(() => {
+  const base = mkdtempSync(join(tmpdir(), "ocx-superseded-store-"));
+  home = join(base, "home");
+  mkdirSync(home, { recursive: true });
+  store = createIntegrationStateStore(join(base, "store", "integrations"));
+});
+
+afterEach(() => {
+  removeTreeWithRetry(dirname(home));
+});
+
+const spec = () => INTEGRATION_CLIENTS.zcode;
+
+/** Install the client: its detect directory and the parent of its config file. */
+function installZcode(): string {
+  mkdirSync(spec().detectDir(TEST_ENV, home), { recursive: true });
+  const configPath = spec().configPath(TEST_ENV, home);
+  mkdirSync(dirname(configPath), { recursive: true });
+  return configPath;
+}
+
+/** The file whose presence means the client stopped reading its config file. */
+function storePath(env: NodeJS.ProcessEnv = TEST_ENV): string {
+  return spec().currentStore!.path(env, home);
+}
+
+function createStore(contents = "{}\n"): string {
+  const path = storePath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, contents);
+  return path;
+}
+
+function input(overrides: Partial<IntegrationWriteInput> = {}): IntegrationWriteInput {
+  return { clientId: "zcode", models: MODELS, config: CONFIG, port: 10100, env: TEST_ENV, home, store, ...overrides };
+}
+
+describe("a client that moved its provider store", () => {
+  test("apply refuses instead of writing a file nothing reads", () => {
+    const configPath = installZcode();
+    const storeFile = createStore();
+
+    const result = applyIntegration(input());
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("superseded_store");
+      // Both locations, because the user has to know which file to look at and
+      // which one the client opens instead.
+      expect(result.message).toContain(storeFile);
+      expect(result.message).toContain(configPath);
+    }
+    // The point of the refusal: nothing was written, and nothing claims we own
+    // anything here.
+    expect(existsSync(configPath)).toBe(false);
+    expect(Object.keys(store.readRecords())).not.toContain("zcode");
+  });
+
+  test("refresh refuses on the same evidence", () => {
+    installZcode();
+    createStore();
+    const result = refreshIntegration(input());
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("superseded_store");
+  });
+
+  test("the preview refuses before the operator confirms anything", () => {
+    installZcode();
+    createStore();
+    const plan = previewIntegration(input(), { operation: "apply" });
+    expect(plan.refusalReason).toBe("superseded_store");
+    expect(plan.canApply).toBe(false);
+    expect(plan.willChange).toBe(false);
+  });
+
+  test("an absent store leaves the existing write path alone", () => {
+    const configPath = installZcode();
+    expect(existsSync(storePath())).toBe(false);
+
+    const result = applyIntegration(input());
+
+    expect(result.ok).toBe(true);
+    // A client that has never run still imports the file we write, which is why
+    // the refusal is keyed on the store's presence and not on the client at all.
+    expect(readFileSync(configPath, "utf8")).toContain("opencodex");
+    expect(readIntegrationState(input())).toMatchObject({ state: "current" });
+  });
+
+  test("status reports the store beside a block that really is current", () => {
+    installZcode();
+    expect(applyIntegration(input()).ok).toBe(true);
+    const storeFile = createStore();
+
+    const status = readIntegrationState(input());
+
+    // Both halves are true at once, and only the second one is new.
+    expect(status.state).toBe("current");
+    expect(status.supersededBy).toBe(storeFile);
+  });
+
+  test("disable still removes what we wrote before the client moved", () => {
+    const configPath = installZcode();
+    expect(applyIntegration(input()).ok).toBe(true);
+    createStore();
+
+    const result = disableIntegration(input());
+
+    expect(result.ok).toBe(true);
+    // Removing our own bytes from this file is as effective as it ever was, and
+    // refusing it would leave the block unremovable through the tool.
+    expect(readFileSync(configPath, "utf8")).not.toContain("opencodex");
+    expect(readIntegrationState(input())).toMatchObject({ state: "absent" });
+  });
+
+  test("only a regular file counts as the store", () => {
+    installZcode();
+    // A directory at that path is not a provider list the client loaded, and
+    // refusing over it would block an apply that would have worked.
+    mkdirSync(storePath(), { recursive: true });
+    const resolved = resolveIntegrationTarget({
+      clientId: "zcode",
+      configPath: spec().configPath(TEST_ENV, home),
+      io: store.io(),
+      record: null,
+      env: TEST_ENV,
+      home,
+    });
+    expect(resolved.ineffective).toBeNull();
+    expect(resolved.configPath).toBe(spec().configPath(TEST_ENV, home));
+    expect(applyIntegration(input()).ok).toBe(true);
+  });
+
+  test("a relative store override is refused rather than resolved against a guess", () => {
+    installZcode();
+    const env = { ZCODE_PERSONAL_PROVIDER_CONFIG_FILE: "v2/provider_config.json" } as NodeJS.ProcessEnv;
+    // The client resolves it against its own working directory; we cannot know
+    // that one, and here the answer decides whether an apply is called effective.
+    expect(() => storePath(env)).toThrow(ClientPathError);
+    const result = applyIntegration(input({ env }));
+    expect(result.ok).toBe(false);
+  });
+
+  test("an operator who relocated the store is measured against the file they moved it to", () => {
+    installZcode();
+    const relocated = join(home, "elsewhere", "provider_config.json");
+    mkdirSync(dirname(relocated), { recursive: true });
+    writeFileSync(relocated, "{}\n");
+    const env = { ZCODE_PERSONAL_PROVIDER_CONFIG_FILE: relocated } as NodeJS.ProcessEnv;
+
+    const result = applyIntegration(input({ env }));
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.message).toContain(relocated);
+    // The default location is empty, so only the override could have produced this.
+    expect(existsSync(spec().currentStore!.path(TEST_ENV, home))).toBe(false);
+  });
+});
diff --git a/tests/clients/integrations-writer.test.ts b/tests/clients/integrations-writer.test.ts
index 16d118cd3fd..57311a676db 100644
--- a/tests/clients/integrations-writer.test.ts
+++ b/tests/clients/integrations-writer.test.ts
@@ -1,5 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import {
+  mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { buildClientContribution, type ExportModel } from "../../src/clients/config-export";
@@ -93,6 +95,14 @@ function installOmp(): string {
   return configPath;
 }
 
+function installOmo(): string {
+  const spec = INTEGRATION_CLIENTS.omo;
+  mkdirSync(spec.detectDir(TEST_ENV, home), { recursive: true });
+  const configPath = spec.configPath(TEST_ENV, home);
+  mkdirSync(dirname(configPath), { recursive: true });
+  return configPath;
+}
+
 function installDsh(): string {
   const spec = INTEGRATION_CLIENTS.dsh;
   mkdirSync(spec.detectDir(TEST_ENV, home), { recursive: true });
@@ -149,6 +159,48 @@ function reverseJsonObjectKeys(value: unknown): unknown {
 }
 
 describe("apply", () => {
+  // The symlink regressions skip Windows: creating one there needs a privilege
+  // the hosted runners do not grant, and the boundary under test — lstat
+  // classification and rename-replacement of the named entry — is the shared
+  // code path every platform takes.
+  test.skipIf(process.platform === "win32")("refuses an omo catalog symlink without changing its target", () => {
+    const configPath = installOmo();
+    const victim = join(dirname(home), "victim.json");
+    const original = '{"security":{"mode":"strict"}}\n';
+    writeFileSync(victim, original);
+    symlinkSync(victim, configPath);
+
+    expect(readIntegrationState(input({ clientId: "omo" })).state).toBe("unsafe");
+    const result = applyIntegration(input({ clientId: "omo" }));
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("unsafe");
+    expect(readFileSync(victim, "utf8")).toBe(original);
+    expect(store.listOperations("omo")).toHaveLength(0);
+  });
+
+  test.skipIf(process.platform === "win32")("an omo symlink swap before commit cannot replace its target", () => {
+    const configPath = installOmo();
+    const checked = '{"notes":"client-owned"}\n';
+    writeFileSync(configPath, checked);
+    const victim = join(dirname(home), "victim.json");
+    const original = '{"security":{"mode":"strict"}}\n';
+    writeFileSync(victim, original);
+    const captureSnapshot = store.captureSnapshot.bind(store);
+    store.captureSnapshot = (clientId, opId, before) => {
+      const snapshot = captureSnapshot(clientId, opId, before);
+      unlinkSync(configPath);
+      symlinkSync(victim, configPath);
+      return snapshot;
+    };
+
+    const result = applyIntegration(input({ clientId: "omo" }));
+
+    expect(result.ok).toBe(false);
+    expect(readFileSync(victim, "utf8")).toBe(original);
+    expect(store.readRecords().omo).toBeUndefined();
+  });
+
   test("refuses Kimi TOML date rewrites without changing the file or ownership store", () => {
     const spec = INTEGRATION_CLIENTS.kimi;
     mkdirSync(spec.detectDir(TEST_ENV, home), { recursive: true });
@@ -789,6 +841,24 @@ describe("apply", () => {
 });
 
 describe("disable", () => {
+  test.skipIf(process.platform === "win32")("refuses a symlinked managed target and leaves its target alone", () => {
+    const configPath = installOmo();
+    const applied = applyIntegration(input({ clientId: "omo" }));
+    expect(applied.ok).toBe(true);
+    const victim = join(dirname(home), "victim.json");
+    const original = '{"security":{"mode":"strict"}}\n';
+    writeFileSync(victim, original);
+    unlinkSync(configPath);
+    symlinkSync(victim, configPath);
+
+    const result = disableIntegration(input({ clientId: "omo" }));
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("unsafe");
+    expect(readFileSync(victim, "utf8")).toBe(original);
+    expect(store.readRecords().omo).toBeDefined();
+  });
+
   test("removes only our block and leaves the rest byte-identical", () => {
     const configPath = installHermes();
     const original = "providers:\n  other:\n    api: http://elsewhere\nunknown_top: keep-me\n";
@@ -1078,6 +1148,24 @@ describe("Hermes source preservation", () => {
 });
 
 describe("restore", () => {
+  test.skipIf(process.platform === "win32")("refuses a symlinked managed target and leaves its target alone", () => {
+    const configPath = installOmo();
+    const applied = applyIntegration(input({ clientId: "omo" }));
+    expect(applied.ok).toBe(true);
+    const opId = store.listOperations("omo")[0]!.opId;
+    const victim = join(dirname(home), "victim.json");
+    const original = '{"security":{"mode":"strict"}}\n';
+    writeFileSync(victim, original);
+    unlinkSync(configPath);
+    symlinkSync(victim, configPath);
+
+    const result = restoreIntegration({ ...input({ clientId: "omo" }), opId });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("unsafe");
+    expect(readFileSync(victim, "utf8")).toBe(original);
+  });
+
   test("undoes an apply back to the exact prior bytes", () => {
     const configPath = installHermes();
     const original = "providers:\n  other:\n    api: http://elsewhere\n";
diff --git a/tests/clients/mutation-plan.test.ts b/tests/clients/mutation-plan.test.ts
index 4af951a290c..0a38274bb8a 100644
--- a/tests/clients/mutation-plan.test.ts
+++ b/tests/clients/mutation-plan.test.ts
@@ -5,6 +5,7 @@ import { dirname, join, relative } from "node:path";
 import {
   MANAGED_PATH_TEMPLATES,
   PLAN_CHANGE_LIMIT,
+  PLAN_UNBOUND_FINGERPRINT,
   buildMutationPlan,
   canonicalSchemaPath,
   orderPlanChanges,
@@ -88,6 +89,7 @@ const BASE: PlanFingerprintInput = {
   detectDir: "/home/example/.cline",
   installKind: "dir",
   admissionBlocked: false,
+  ineffectiveWrite: null,
   before: "{}",
   contribution: CONTRIBUTION,
   record: RECORD,
@@ -180,7 +182,11 @@ describe("integration mutation plan projection", () => {
 describe("integration plan fingerprint", () => {
   test("is stable for the same inputs and carries its version", () => {
     expect(planFingerprint(BASE)).toBe(planFingerprint({ ...BASE }));
-    expect(planFingerprint(BASE).startsWith("p1:")).toBe(true);
+    // Derived from the one exported value that carries the version, so a bump
+    // cannot leave this case asserting the previous vocabulary.
+    const version = PLAN_UNBOUND_FINGERPRINT.split(":")[0]!;
+    expect(version).not.toBe("");
+    expect(planFingerprint(BASE).startsWith(`${version}:`)).toBe(true);
   });
 
   test("every authority input changes it", () => {
@@ -196,6 +202,13 @@ describe("integration plan fingerprint", () => {
       { ...BASE, installKind: "missing" },
       { ...BASE, installKind: "file" },
       { ...BASE, admissionBlocked: true },
+      // A client that creates its new provider store while a confirmation is
+      // outstanding changes whether the write can reach it at all, and leaves
+      // the file, the record and the contribution untouched while doing it.
+      { ...BASE, ineffectiveWrite: "unestablished-schema\u0000/home/example/.client/store.json" },
+      // The same location with a different reason is a different answer: a store
+      // whose schema stops being one we recognise moves nothing on disk.
+      { ...BASE, ineffectiveWrite: "owned-config-file\u0000/home/example/.client/store.json" },
       // Different bytes, and absent distinguished from empty: restoring over a missing file and
       // over an empty one are different operations.
       { ...BASE, before: "{ }" },
@@ -281,6 +294,8 @@ describe("integration mutation plan", () => {
     // Installation outranks a conflict the file would otherwise report.
     expect(buildMutationPlan({ ...conflicted, installKind: "missing" }).refusalReason).toBe("not_installed");
     expect(buildMutationPlan({ ...conflicted, admissionBlocked: true }).refusalReason).toBe("non_loopback");
+    expect(buildMutationPlan({ ...conflicted, ineffectiveWrite: "owned-config-file\u0000/store.json" }).refusalReason)
+      .toBe("superseded_store");
     // And a conflict outranks the classifier's unsafe, which apply reports last.
     expect(buildMutationPlan(conflicted).refusalReason).toBe("conflict");
     expect(buildMutationPlan({ ...PLAN_BASE, classified: { state: "unsafe", reason: "blocked-container" } }).refusalReason)
@@ -296,6 +311,9 @@ describe("integration mutation plan", () => {
     // client is installed now, and it emits nothing admission policy could object to.
     expect(buildMutationPlan({ ...disable, installKind: "missing" }).canApply).toBe(true);
     expect(buildMutationPlan({ ...disable, admissionBlocked: true }).canApply).toBe(true);
+    // Removing bytes this project wrote to this file stays possible after the
+    // client stops reading it; refusing would strand the block forever.
+    expect(buildMutationPlan({ ...disable, ineffectiveWrite: "owned-config-file\u0000/store.json" }).canApply).toBe(true);
     expect(buildMutationPlan({ ...disable, classified: { state: "conflict", reason: "foreign-edit" } }).refusalReason)
       .toBe("conflict");
   });
diff --git a/tests/codex-integration/codex-app-server-processes.test.ts b/tests/codex-integration/codex-app-server-processes.test.ts
index 343d193cea0..8f170d2f1ea 100644
--- a/tests/codex-integration/codex-app-server-processes.test.ts
+++ b/tests/codex-integration/codex-app-server-processes.test.ts
@@ -677,6 +677,8 @@ describe("Codex app-server process matching (#476)", () => {
     const snapshots = [{ pid: 7, commandLine: "codex app-server --listen unix://x" }];
     const io = {
       listSnapshots: () => snapshots,
+      readStartMs: () => 1_000,
+      catalogMtimeMs: () => 2_000,
       kill: () => {},
       isAlive: () => false,
       waitExit: () => true,
@@ -700,6 +702,55 @@ describe("Codex app-server process matching (#476)", () => {
     expect(restarted.restart?.stopped).toEqual([7]);
     expect(logs.some(line => line.includes("Stopping Codex app-server"))).toBe(true);
   });
+
+  test("afterCatalogWriteHandleAppServers warns only for processes proven stale", () => {
+    const errors: string[] = [];
+    const snapshots = [
+      { pid: 7, commandLine: "codex app-server --listen unix://stale" },
+      { pid: 8, commandLine: "codex app-server --listen unix://fresh" },
+    ];
+    const result = afterCatalogWriteHandleAppServers({
+      restart: false,
+      log: { log: () => {}, error: line => errors.push(String(line)) },
+      io: {
+        listSnapshots: () => snapshots,
+        readStartMs: pid => pid === 7 ? 1_000 : 3_000,
+        catalogMtimeMs: () => 2_000,
+      },
+    });
+    expect(result.warned).toBe(true);
+    expect(result.processes.map(process => process.pid)).toEqual([7]);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toContain("PID: 7");
+    expect(errors[0]).not.toContain("8");
+  });
+
+  test("afterCatalogWriteHandleAppServers stays quiet for fresh and unknown observations", () => {
+    const errors: string[] = [];
+    const base = {
+      restart: false,
+      log: { log: () => {}, error: line => errors.push(String(line)) },
+    } as const;
+    const fresh = afterCatalogWriteHandleAppServers({
+      ...base,
+      io: {
+        listSnapshots: () => [{ pid: 7, commandLine: "codex app-server --listen unix://fresh" }],
+        readStartMs: () => 3_000,
+        catalogMtimeMs: () => 2_000,
+      },
+    });
+    const unknown = afterCatalogWriteHandleAppServers({
+      ...base,
+      io: {
+        listSnapshots: () => [{ pid: 8, commandLine: "codex app-server --listen unix://unknown" }],
+        readStartMs: () => null,
+        catalogMtimeMs: () => 2_000,
+      },
+    });
+    expect(fresh.warned).toBe(false);
+    expect(unknown.warned).toBe(false);
+    expect(errors).toEqual([]);
+  });
 });
 
 describe("CLI /api sync wiring for stale app-servers (#476)", () => {
diff --git a/tests/codex-integration/codex-auth-api.test.ts b/tests/codex-integration/codex-auth-api.test.ts
index ab750aa06d0..c17088cb15e 100644
--- a/tests/codex-integration/codex-auth-api.test.ts
+++ b/tests/codex-integration/codex-auth-api.test.ts
@@ -170,7 +170,7 @@ async function completeMockCodexOAuth(options: {
     done: true,
     loggedIn: true,
   } as ReturnType<typeof oauth.getLoginStatus>);
-  const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(() => {});
+  const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(async () => ({ status: "started" as const }));
   // Mirrors the login-status poll delay in login-flow.ts; other timers are intentionally dropped.
   const CODEX_OAUTH_LOGIN_POLL_INTERVAL_MS = 2_000;
   const timeoutSpy = spyOn(globalThis, "setTimeout").mockImplementation(((
@@ -4593,7 +4593,7 @@ describe("codex-auth API", () => {
       instructions: "Enter code: ABCD-EFGH",
       deviceCode: "ABCD-EFGH",
     }));
-    const openSpy = spyOn(openUrlModule, "openUrl").mockImplementation(() => {});
+    const openSpy = spyOn(openUrlModule, "openUrl").mockImplementation(async () => ({ status: "started" as const }));
     try {
       const req = new Request("http://localhost/api/codex-auth/login", {
         method: "POST",
@@ -4699,7 +4699,7 @@ describe("codex-auth API", () => {
       controller.onAuth({ url: "https://example.test/oauth" });
       throw new Error("late failure at /home/alice/.opencodex/auth.json.ocx-tmp sk-secret-provider-key");
     };
-    const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(() => {});
+    const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(async () => ({ status: "started" as const }));
     const timeoutSpy = spyOn(globalThis, "setTimeout").mockImplementation(((
       callback: (...args: unknown[]) => void,
       delay?: number,
@@ -4747,7 +4747,7 @@ describe("codex-auth API", () => {
     const { OAuthMutationBusyError } = await import("../../src/oauth/store");
     const openUrlMod = await import("../../src/lib/open-url");
     const originalLogin = oauth.OAUTH_PROVIDERS.chatgpt.login;
-    const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(() => {});
+    const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(async () => ({ status: "started" as const }));
     const timeoutSpy = spyOn(globalThis, "setTimeout").mockImplementation(((
       callback: (...args: unknown[]) => void,
       delay?: number,
@@ -4834,7 +4834,7 @@ describe("codex-auth API", () => {
         done: false,
         loggedIn: false,
       } as ReturnType<typeof oauth.getLoginStatus>);
-      const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(() => {});
+      const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(async () => ({ status: "started" as const }));
       const req = new Request("http://localhost/api/codex-auth/login", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -5161,7 +5161,7 @@ describe("codex-auth API", () => {
       loggedIn: false,
       error: "test-stop",
     } as ReturnType<typeof oauth.getLoginStatus>);
-    const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(() => {});
+    const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(async () => ({ status: "started" as const }));
 
     try {
       const req = new Request("http://localhost/api/codex-auth/login", {
diff --git a/tests/codex-integration/codex-inject-integration.test.ts b/tests/codex-integration/codex-inject-integration.test.ts
index 75fc7b8217e..0615fb2d374 100644
--- a/tests/codex-integration/codex-inject-integration.test.ts
+++ b/tests/codex-integration/codex-inject-integration.test.ts
@@ -9,6 +9,7 @@ import {
   MANAGED_AGENTS_TABLE_MARKER,
   MANAGED_SUBAGENT_DEFAULT_MARKER,
 } from "../../src/codex/subagent-defaults";
+import { OCX_ROUTING_MARKER_LINE } from "../../src/codex/injected-marker";
 import { SPAWN_BUDGET_MS } from "../helpers/test-budget";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
 
@@ -74,9 +75,9 @@ function runRestore(codexHome: string, ocxHome: string, asyncRestore = false): {
 
 describe("injectCodexConfig integration (Design B)", () => {
   const DESIGN_B_BLOCK = [
-    "# Auto-injected by opencodex",
+    OCX_ROUTING_MARKER_LINE,
     'openai_base_url = "http://127.0.0.1:10100/v1"',
-    "# Auto-injected by opencodex",
+    OCX_ROUTING_MARKER_LINE,
     'experimental_realtime_ws_base_url = "http://127.0.0.1:10100/v1"',
   ].join("\n");
   let codexHome: string;
@@ -784,14 +785,19 @@ describe("injectCodexConfig integration (Design B)", () => {
     expect(restoredRowBytes).toBe(rowBytes);
   });
 
-  test("a provider-table transition refuses rather than strand a paginated openai thread", () => {
-    const original = 'model_provider = "openai"\n# >>> opencodex managed openai_base_url >>>\nopenai_base_url = "http://127.0.0.1:10100/v1"\n# <<< opencodex managed openai_base_url <<<\n';
+  test("a provider-table transition keeps a paginated openai thread on the proxy instead of refusing", () => {
+    // #5321. The transition used to be refused outright, so nothing was written and the
+    // integration stayed disabled. It now completes by keeping the marker-owned root override
+    // beside the table: the row is never relabeled, and it still resolves to this proxy.
+    // The reporter's shape: a loopback root-override home turning on codexDesktopAuthless.
+    const original = `${OCX_ROUTING_MARKER_LINE}\nopenai_base_url = "http://127.0.0.1:10100/v1"\nmodel = "gpt-5.5"\n`;
     const configPath = join(codexHome, "config.toml");
     writeFileSync(configPath, original);
     const rollout = join(codexHome, "openai-paginated.jsonl");
     const bytes = JSON.stringify({ ordinal: 0, type: "session_meta", payload: { id: "fixture", history_mode: "paginated", model_provider: "openai" } }) + "\n";
     writeFileSync(rollout, bytes);
-    const db = new Database(join(codexHome, "state_5.sqlite"));
+    const dbPath = join(codexHome, "state_5.sqlite");
+    const db = new Database(dbPath);
     db.run("CREATE TABLE threads (id TEXT, rollout_path TEXT, model_provider TEXT, history_mode TEXT)");
     db.run("INSERT INTO threads VALUES ('fixture', ?, 'openai', 'paginated')", rollout);
     db.close();
@@ -799,10 +805,27 @@ describe("injectCodexConfig integration (Design B)", () => {
     const result = runInject(codexHome, ocxHome, JSON.stringify({ codexDesktopAuthless: true }));
     expect(result.status, result.stderr).toBe(0);
     expect(JSON.parse(result.stdout)).toMatchObject({
-      success: false,
-      historyPreflightFailureReason: "history_paginated_openai_requires_native_writer",
+      success: true,
+      historyPreflightFailureReason: "history_paginated_requires_native_writer",
     });
-    expect(readFileSync(configPath, "utf8")).toBe(original);
+    const written = readFileSync(configPath, "utf8");
+    expect(written).toContain("[model_providers.opencodex]");
+    expect(written).toContain(`${OCX_ROUTING_MARKER_LINE}\nopenai_base_url = "http://127.0.0.1:10100/v1"`);
+    // The safety property the refusal existed to protect: the paginated row is untouched and
+    // still tagged openai, and the retained override is what keeps it reaching the proxy.
+    expect(readFileSync(rollout, "utf8")).toBe(bytes);
+    const after = new Database(dbPath, { readonly: true });
+    expect(after.query("SELECT model_provider, history_mode FROM threads WHERE id = 'fixture'").all())
+      .toEqual([{ model_provider: "openai", history_mode: "paginated" }]);
+    after.close();
+
+    // The other half of the trap (#4812): unblocking the transition is worth nothing if the
+    // retained override then cannot come back out. Restore journals it as ours, so it does.
+    const restored = JSON.parse(runRestore(codexHome, ocxHome).stdout);
+    expect(restored.success).toBe(true);
+    const native = readFileSync(configPath, "utf8");
+    expect(native).not.toContain("openai_base_url");
+    expect(native).not.toContain('model_provider = "opencodex"');
     expect(readFileSync(rollout, "utf8")).toBe(bytes);
   });
 
@@ -909,7 +932,7 @@ describe("injectCodexConfig integration (Design B)", () => {
 
     const config = readFileSync(join(codexHome, "config.toml"), "utf8");
     expect(config).toContain('openai_base_url = "http://127.0.0.1:10100/v1"');
-    expect(config).toContain("# Auto-injected by opencodex");
+    expect(config).toContain(OCX_ROUTING_MARKER_LINE);
     expect(config).toContain("[model_providers.opencodex]");
     expect(config).not.toContain('model_provider = "opencodex"');
     expect(config).toContain('model = "gpt-5.5"');
diff --git a/tests/codex-integration/codex-inject.test.ts b/tests/codex-integration/codex-inject.test.ts
index 53762f132fd..d1763153ab9 100644
--- a/tests/codex-integration/codex-inject.test.ts
+++ b/tests/codex-integration/codex-inject.test.ts
@@ -22,7 +22,7 @@ import {
   resolveCodexProviderDisplayName,
 } from "../../src/codex/inject/config-toml";
 import { extractOcxProviderTableBlock } from "../../src/codex/inject/remove";
-import { OCX_SECTION_MARKER, stripJournaledOpenaiBaseUrl } from "../../src/codex/injected-marker";
+import { OCX_ROUTING_MARKER_LINE, OCX_SECTION_MARKER, stripJournaledOpenaiBaseUrl } from "../../src/codex/injected-marker";
 import {
   MANAGED_AGENTS_TABLE_MARKER,
   MANAGED_SUBAGENT_DEFAULT_MARKER,
@@ -469,7 +469,7 @@ describe("Design B openai_base_url injection", () => {
 
     expect(keptUserBaseUrl).toBe(false);
     const lines = content.split("\n");
-    const markerIdx = lines.findIndex(l => l.includes("Auto-injected by opencodex"));
+    const markerIdx = lines.findIndex(l => l.includes(OCX_SECTION_MARKER));
     const keyIdx = lines.findIndex(l => l.startsWith("openai_base_url"));
     const tableIdx = lines.findIndex(l => l.trim() === "[features]");
     expect(markerIdx).toBeGreaterThanOrEqual(0);
@@ -521,8 +521,10 @@ describe("Design B openai_base_url injection", () => {
       const lines = content.split("\n");
       const routing = lines.indexOf('openai_base_url = "http://127.0.0.1:10100/v1"');
       expect(routing).toBeGreaterThan(0);
-      expect(lines[routing - 1]).toContain("Auto-injected by opencodex");
-      expect(lines[routing + 1]).toContain("Auto-injected by opencodex");
+      // Asserted as the whole routing marker, not a substring of it: a substring check passes
+      // even when the wrong ownership line is written above a routing key (#5261).
+      expect(lines[routing - 1]).toBe(OCX_ROUTING_MARKER_LINE);
+      expect(lines[routing + 1]).toBe(OCX_ROUTING_MARKER_LINE);
       expect(lines[routing + 2]).toBe('experimental_realtime_ws_base_url = "http://127.0.0.1:10100/v1"');
       expect(lines.indexOf("[features]")).toBeGreaterThan(routing + 2);
       expect(content.match(/Auto-injected by opencodex/g)?.length).toBe(2);
@@ -852,12 +854,19 @@ describe("EOL boundary helpers (Windows CRLF configs)", () => {
   });
 });
 
+/**
+ * What an injection does to a marker it already owns: the routing keys carry the recovery
+ * command (#5261), and a rewrite in place refreshes a bare marker left by an earlier build.
+ * Only our own ownership line moves; everything else below is asserted unchanged.
+ */
+const refreshed = (content: string) => content.replace(OCX_SECTION_MARKER, OCX_ROUTING_MARKER_LINE);
+
 test('managed injection is idempotent and retains every unrelated value',()=>{
  const source=`model = "gpt-6-astra"\n${OCX_SECTION_MARKER}\nopenai_base_url = "http://127.0.0.1:10100/v1"\nservice_tier = "fast"\n[features]\ncontext_management.experimental_mode = true\n[features.multi_agent_v2]\nenabled = true\n`;
  const target={baseUrl:'http://127.0.0.1:10100/v1',requiresAdmissionToken:false,tokenEnv:'OPENCODEX_API_AUTH_TOKEN' as const};
  const result=setRootOpenaiBaseUrl(source,target);
  expect(result.keptUserBaseUrl).toBe(false);
- expect(result.content).toBe(source.replace('10100/v1','10100/backend-api/codex'));
+ expect(result.content).toBe(refreshed(source).replace('10100/v1','10100/backend-api/codex'));
  expect(setRootOpenaiBaseUrl(result.content,target).content).toBe(result.content);
  expect(buildRealtimeWsBaseUrlLine(target)).toContain('10100/v1');
  expect(setRootOpenaiBaseUrl(source,10100).content).toBe(result.content);
@@ -866,7 +875,7 @@ test('feature disabled and user-owned routing remain intact',()=>{
  const source='openai_base_url = "http://127.0.0.1:10100/v1"\n[features]\ncontext_management.experimental_mode = true\n';
  expect(setRootOpenaiBaseUrl(source,10100)).toEqual({content:source,keptUserBaseUrl:true});
  const managed=`${OCX_SECTION_MARKER}\nopenai_base_url = "http://127.0.0.1:10100/v1"\n[features]\ncontext_management.experimental_mode = false\n`;
- expect(setRootOpenaiBaseUrl(managed,10100).content).toBe(managed);
+ expect(setRootOpenaiBaseUrl(managed,10100).content).toBe(refreshed(managed));
 });
 
 
@@ -877,7 +886,9 @@ test("malformed TOML preserves user routing and does not enable context injectio
     const managed = `${OCX_SECTION_MARKER}\nopenai_base_url = "http://127.0.0.1:10100/v1"\n${malformed}\n`;
     for (const inject of [(source: string) => setRootOpenaiBaseUrl(source, 10100), (source: string) => setRootOpenaiBaseUrl(source, target)]) {
       expect(inject(userOwned)).toEqual({ content: userOwned, keptUserBaseUrl: true });
-      expect(inject(managed)).toEqual({ content: managed, keptUserBaseUrl: false });
+      // A file we cannot parse is still not rewritten beyond the routing we own: the marker
+      // refreshes, the malformed tail is returned byte for byte.
+      expect(inject(managed)).toEqual({ content: refreshed(managed), keptUserBaseUrl: false });
     }
   }
 });
diff --git a/tests/codex-integration/codex-main-account-refresh.test.ts b/tests/codex-integration/codex-main-account-refresh.test.ts
index d1ae3807955..9541891ba58 100644
--- a/tests/codex-integration/codex-main-account-refresh.test.ts
+++ b/tests/codex-integration/codex-main-account-refresh.test.ts
@@ -328,4 +328,28 @@ describe("publication never overwrites an external Codex writer (#2999)", () =>
     expect(token?.accessToken).toBe("ocx-staged-access");
     expect(readFileSync(authPath, "utf8")).toContain("ocx-staged-access");
   });
+
+  test("a caller cancelled during the refresh does not commit the late result", async () => {
+    // The refresh seam resolves after the caller aborted (a client that disconnected
+    // mid-/v1/models). The late result must never reach auth.json on behalf of a
+    // request that no longer exists: the publication is fenced before the rename,
+    // the file keeps its prior bytes, and the credential mutation epoch does not
+    // advance for a commit that never happened.
+    const authPath = join(home, "auth.json");
+    seedExpired(authPath);
+    const before = readFileSync(authPath, "utf8");
+    const controller = new AbortController();
+    const epochBefore = codexCredentialMutationEpoch();
+
+    await expect(getValidMainAccountToken({
+      signal: controller.signal,
+      refreshToken: async () => {
+        controller.abort(new Error("client disconnected"));
+        return refreshOk();
+      },
+    })).rejects.toThrow("client disconnected");
+
+    expect(readFileSync(authPath, "utf8")).toBe(before);
+    expect(codexCredentialMutationEpoch()).toBe(epochBefore);
+  });
 });
diff --git a/tests/codex-integration/codex-model-entitlement-admission.test.ts b/tests/codex-integration/codex-model-entitlement-admission.test.ts
new file mode 100644
index 00000000000..aa145e6ce07
--- /dev/null
+++ b/tests/codex-integration/codex-model-entitlement-admission.test.ts
@@ -0,0 +1,307 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  MAIN_CODEX_ACCOUNT_ID,
+  MainAccountTokenRefreshError,
+  MainAuthJsonChangedDuringRefreshError,
+} from "../../src/codex/main-account";
+import { resolveAdmittedCodexModelEntitlements } from "../../src/codex/model-entitlement-admission";
+import {
+  ensureCodexEntitlementFreshness,
+  resetCodexModelEntitlementCacheForTests,
+  type CodexModelEntitlementResolveOptions,
+} from "../../src/codex/model-entitlements";
+import { NativeProfileError } from "../../src/codex/native-profile-types";
+import { installIsolatedCodexHome } from "../helpers/isolated-codex-home";
+
+const emptySnapshot = {
+  modelsByAccount: new Map<string, ReadonlySet<string>>(),
+  clientVersionByAccount: new Map<string, string>(),
+  confirmedAccountIds: new Set<string>(),
+  credentialIdentities: new Map<string, string>(),
+};
+
+describe("Codex model entitlement admission", () => {
+  test("excludes native main before credential discovery when lifecycle admission is blocked", async () => {
+    let received: CodexModelEntitlementResolveOptions | undefined;
+
+    await resolveAdmittedCodexModelEntitlements({ codexAccounts: [] }, {}, {
+      acquireNativeMain: () => null,
+      resolve: async (_config, options) => {
+        received = options;
+        return emptySnapshot;
+      },
+    });
+
+    expect(received?.excludeAccountIds?.has(MAIN_CODEX_ACCOUNT_ID)).toBe(true);
+  });
+
+  test("holds the lifecycle lease through credential discovery", async () => {
+    const events: string[] = [];
+    let released = false;
+
+    await resolveAdmittedCodexModelEntitlements({ codexAccounts: [] }, {}, {
+      acquireNativeMain: () => ({ release: () => {
+        released = true;
+        events.push("lifecycle-release");
+      } }),
+      resolve: async () => {
+        expect(released).toBe(false);
+        events.push("credential-discovery");
+        return emptySnapshot;
+      },
+    });
+
+    expect(events).toEqual([
+      "credential-discovery",
+      "lifecycle-release",
+    ]);
+  });
+
+  test("falls back to Pool-only discovery when the credential claim is refused", async () => {
+    const exclusions: boolean[] = [];
+    let calls = 0;
+
+    await resolveAdmittedCodexModelEntitlements({ codexAccounts: [] }, {}, {
+      acquireNativeMain: () => ({ release: () => undefined }),
+      resolve: async (_config, options) => {
+        calls += 1;
+        if (calls === 1) {
+          throw new NativeProfileError("NATIVE_MAIN_CLAIM_BUSY", "busy", 503, true);
+        }
+        exclusions.push(options.excludeAccountIds?.has(MAIN_CODEX_ACCOUNT_ID) === true);
+        return emptySnapshot;
+      },
+    });
+
+    expect(exclusions).toEqual([true]);
+  });
+
+  test("releases the lifecycle lease before the Pool-only retry", async () => {
+    let released = false;
+    const releasedAtRetry: boolean[] = [];
+    let calls = 0;
+
+    await resolveAdmittedCodexModelEntitlements({ codexAccounts: [] }, {}, {
+      acquireNativeMain: () => ({ release: () => {
+        released = true;
+      } }),
+      resolve: async (_config, options) => {
+        calls += 1;
+        if (calls === 1) {
+          throw new NativeProfileError("NATIVE_MAIN_CLAIM_BUSY", "busy", 503, true);
+        }
+        releasedAtRetry.push(released);
+        return emptySnapshot;
+      },
+    });
+
+    expect(releasedAtRetry).toEqual([true]);
+  });
+
+  test("lets the credential phase release the lease before upstream work", async () => {
+    const events: string[] = [];
+
+    await resolveAdmittedCodexModelEntitlements({ codexAccounts: [] }, {}, {
+      acquireNativeMain: () => ({ release: () => {
+        events.push("lifecycle-release");
+      } }),
+      resolve: async (_config, options) => {
+        events.push("credential-discovery");
+        options.releaseNativeMainCredentialLease?.();
+        events.push("upstream-request");
+        return emptySnapshot;
+      },
+    });
+
+    expect(events).toEqual([
+      "credential-discovery",
+      "lifecycle-release",
+      "upstream-request",
+    ]);
+  });
+
+  test("a foreign credential owner or a failed grant still resolves the Pool", async () => {
+    for (const makeError of [
+      () => new MainAuthJsonChangedDuringRefreshError(),
+      () => new MainAccountTokenRefreshError("reauth"),
+      () => new NativeProfileError("NATIVE_MAIN_CLAIM_BUSY", "busy", 503, true),
+      () => new NativeProfileError("NATIVE_MAIN_CLAIM_UNAVAILABLE", "unavailable", 503, true),
+    ]) {
+      const exclusions: boolean[] = [];
+      let calls = 0;
+
+      await resolveAdmittedCodexModelEntitlements({ codexAccounts: [] }, {}, {
+        acquireNativeMain: () => ({ release: () => undefined }),
+        resolve: async (_config, options) => {
+          calls += 1;
+          if (calls === 1) throw makeError();
+          exclusions.push(options.excludeAccountIds?.has(MAIN_CODEX_ACCOUNT_ID) === true);
+          return emptySnapshot;
+        },
+      });
+
+      expect(exclusions).toEqual([true]);
+    }
+  });
+
+  test("propagates failures that are not credential-ownership errors", async () => {
+    const failure = new Error("upstream exploded");
+
+    await expect(resolveAdmittedCodexModelEntitlements({ codexAccounts: [] }, {}, {
+      acquireNativeMain: () => ({ release: () => undefined }),
+      resolve: async () => {
+        throw failure;
+      },
+    })).rejects.toBe(failure);
+  });
+
+  test("propagates native profile errors that are not claim-ownership failures", async () => {
+    for (const code of ["INTERNAL_ERROR", "VAULT_INVALID", "MAIN_REQUESTS_ACTIVE"] as const) {
+      let calls = 0;
+      const failure = new NativeProfileError(code, "not a credential-ownership failure");
+
+      await expect(resolveAdmittedCodexModelEntitlements({ codexAccounts: [] }, {}, {
+        acquireNativeMain: () => ({ release: () => undefined }),
+        resolve: async () => {
+          calls += 1;
+          throw failure;
+        },
+      })).rejects.toBe(failure);
+      expect(calls).toBe(1);
+    }
+  });
+
+  test("skips the fences for a caller-supplied roster or an already-excluded main", async () => {
+    let leaseAttempts = 0;
+    const seen: CodexModelEntitlementResolveOptions[] = [];
+    const deps = {
+      acquireNativeMain: () => {
+        leaseAttempts += 1;
+        return null;
+      },
+      resolve: async (_config: unknown, options: CodexModelEntitlementResolveOptions) => {
+        seen.push(options);
+        return emptySnapshot;
+      },
+    };
+
+    await resolveAdmittedCodexModelEntitlements({ codexAccounts: [] }, { credentials: [] }, deps);
+    await resolveAdmittedCodexModelEntitlements(
+      { codexAccounts: [] },
+      { excludeAccountIds: new Set([MAIN_CODEX_ACCOUNT_ID]) },
+      deps,
+    );
+
+    expect(leaseAttempts).toBe(0);
+    expect(seen[0]?.credentials).toEqual([]);
+    expect(seen[1]?.excludeAccountIds?.has(MAIN_CODEX_ACCOUNT_ID)).toBe(true);
+  });
+});
+
+describe("entitlement freshness admission", () => {
+  let home: ReturnType<typeof installIsolatedCodexHome>;
+
+  beforeEach(() => {
+    home = installIsolatedCodexHome("ocx-entitlement-admission-");
+  });
+
+  afterEach(() => {
+    home.restore();
+    resetCodexModelEntitlementCacheForTests();
+  });
+
+  test("a denied native-main admission drops main from the refresh workset", async () => {
+    const snapshots: string[] = [];
+
+    await ensureCodexEntitlementFreshness(
+      { codexAccounts: [{ id: "pool-fenced", email: "pool-fenced@example.test", isMain: false }] },
+      {
+        clientVersion: "0.146.0",
+        waitMs: 1_000,
+        credentialSnapshot: async accountId => {
+          snapshots.push(accountId);
+          return null;
+        },
+        nativeMainCredentialAdmission: async operation => operation(new Set([MAIN_CODEX_ACCOUNT_ID])),
+      },
+    );
+
+    expect(snapshots).toContain("pool-fenced");
+    expect(snapshots).not.toContain(MAIN_CODEX_ACCOUNT_ID);
+  });
+
+  test("an admitted freshness refresh snapshots main inside the claim", async () => {
+    const events: string[] = [];
+
+    await ensureCodexEntitlementFreshness({ codexAccounts: [] }, {
+      clientVersion: "0.146.0",
+      waitMs: 1_000,
+      credentialSnapshot: async accountId => {
+        events.push(`snapshot:${accountId}`);
+        return null;
+      },
+      nativeMainCredentialAdmission: async operation => {
+        events.push("admission-enter");
+        const result = await operation(new Set());
+        events.push("admission-exit");
+        return result;
+      },
+    });
+
+    const enteredAt = events.indexOf("admission-enter");
+    const mainSnapshotAt = events.indexOf(`snapshot:${MAIN_CODEX_ACCOUNT_ID}`);
+    const exitedAt = events.indexOf("admission-exit");
+    expect(enteredAt).toBeGreaterThanOrEqual(0);
+    expect(mainSnapshotAt).toBeGreaterThan(enteredAt);
+    expect(exitedAt).toBeGreaterThan(mainSnapshotAt);
+  });
+
+  test("releases the native-main lease before roster fetches", async () => {
+    const events: string[] = [];
+
+    await ensureCodexEntitlementFreshness({ codexAccounts: [] }, {
+      clientVersion: "0.146.0",
+      waitMs: 1_000,
+      credentialSnapshot: async accountId => ({
+        accountId,
+        accessToken: "token",
+        chatgptAccountId: "acct",
+        credentialIdentity: `test:${accountId}`,
+      }),
+      fetcher: async () => {
+        events.push("roster-fetch");
+        return new Response(JSON.stringify({ models: ["gpt-5"] }), { status: 200 });
+      },
+      nativeMainCredentialAdmission: async operation => operation(new Set(), () => {
+        events.push("lease-release");
+      }),
+    });
+
+    const releasedAt = events.indexOf("lease-release");
+    const fetchedAt = events.indexOf("roster-fetch");
+    expect(releasedAt).toBeGreaterThanOrEqual(0);
+    expect(fetchedAt).toBeGreaterThan(releasedAt);
+  });
+
+  test("forwards the caller signal into entitlement resolution", async () => {
+    // A cancelled data-plane request (/v1/models) must fence its own credential
+    // refresh: the signal has to reach resolveCodexModelEntitlements, which hands
+    // it to the native-main token refresh and the roster phase.
+    const controller = new AbortController();
+    let received: CodexModelEntitlementResolveOptions | undefined;
+
+    await resolveAdmittedCodexModelEntitlements(
+      { codexAccounts: [] },
+      { clientVersion: null, signal: controller.signal, credentials: [] },
+      {
+        resolve: async (_config, options) => {
+          received = options;
+          return emptySnapshot;
+        },
+      },
+    );
+
+    expect(received?.signal).toBe(controller.signal);
+  });
+});
diff --git a/tests/codex-integration/codex-prompt-adopt.test.ts b/tests/codex-integration/codex-prompt-adopt.test.ts
index 7bffd6dedce..16ec5cd637d 100644
--- a/tests/codex-integration/codex-prompt-adopt.test.ts
+++ b/tests/codex-integration/codex-prompt-adopt.test.ts
@@ -18,8 +18,12 @@ import {
   salvageProjection,
 } from "../../src/codex/prompt-layers";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { OCX_SECTION_MARKER } from "../../src/codex/injected-marker";
 
-const MARKER = "# Auto-injected by opencodex";
+// Prompt layers deliberately keep the BARE ownership marker: 'ocx restore' is not their undo,
+// so the recovery hint that routing keys carry (#5261) does not belong here. Derived from the
+// constant rather than restated, so the two scopes cannot drift apart silently.
+const MARKER = OCX_SECTION_MARKER;
 const roots: string[] = [];
 
 function fixture(config: string, store?: string) {
diff --git a/tests/codex-integration/codex-prompt-layers-read.test.ts b/tests/codex-integration/codex-prompt-layers-read.test.ts
index 7d74628d494..97b18f5a65a 100644
--- a/tests/codex-integration/codex-prompt-layers-read.test.ts
+++ b/tests/codex-integration/codex-prompt-layers-read.test.ts
@@ -15,8 +15,12 @@ import {
   readPromptLayers,
 } from "../../src/codex/prompt-layers";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { OCX_SECTION_MARKER } from "../../src/codex/injected-marker";
 
-const MARKER = "# Auto-injected by opencodex";
+// Prompt layers deliberately keep the BARE ownership marker: 'ocx restore' is not their undo,
+// so the recovery hint that routing keys carry (#5261) does not belong here. Derived from the
+// constant rather than restated, so the two scopes cannot drift apart silently.
+const MARKER = OCX_SECTION_MARKER;
 const roots: string[] = [];
 
 function fixture(config: string | null, store?: string | null): { configPath: string; storePath: string } {
diff --git a/tests/codex-integration/codex-prompt-layers-write.test.ts b/tests/codex-integration/codex-prompt-layers-write.test.ts
index 09c7d6da093..52c35bce8e1 100644
--- a/tests/codex-integration/codex-prompt-layers-write.test.ts
+++ b/tests/codex-integration/codex-prompt-layers-write.test.ts
@@ -19,8 +19,12 @@ import {
   type JournalRecord,
 } from "../../src/codex/prompt-journal";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { OCX_SECTION_MARKER } from "../../src/codex/injected-marker";
 
-const MARKER = "# Auto-injected by opencodex";
+// Prompt layers deliberately keep the BARE ownership marker: 'ocx restore' is not their undo,
+// so the recovery hint that routing keys carry (#5261) does not belong here. Derived from the
+// constant rather than restated, so the two scopes cannot drift apart silently.
+const MARKER = OCX_SECTION_MARKER;
 const roots: string[] = [];
 
 function fixture(config?: string, store?: string) {
diff --git a/tests/codex-integration/codex-prompt-layers.test.ts b/tests/codex-integration/codex-prompt-layers.test.ts
index 7a289c92013..5aec0f1f911 100644
--- a/tests/codex-integration/codex-prompt-layers.test.ts
+++ b/tests/codex-integration/codex-prompt-layers.test.ts
@@ -13,6 +13,7 @@ import { repoPath } from "../helpers/repo-root";
 import * as encoding from "../../src/codex/prompt-layers/encoding";
 import * as revision from "../../src/codex/prompt-layers/revision";
 import * as tomlRead from "../../src/codex/prompt-layers/toml-read";
+import { OCX_SECTION_MARKER } from "../../src/codex/injected-marker";
 import {
   LAYER_INVENTORY,
   TOGGLE_IDS,
@@ -183,7 +184,8 @@ describe("revision", () => {
   });
 
   test("changes when only the marker is removed", () => {
-    const withMarker = '# Auto-injected by opencodex\ndeveloper_instructions = "x"\n';
+    // Prompt layers keep the bare marker; the routing hint (#5261) is a different scope.
+    const withMarker = `${OCX_SECTION_MARKER}\ndeveloper_instructions = "x"\n`;
     const without = 'developer_instructions = "x"\n';
     expect(computeRevision(withMarker, "{}")).not.toBe(computeRevision(without, "{}"));
   });
diff --git a/tests/codex-integration/codex-prompt-route.test.ts b/tests/codex-integration/codex-prompt-route.test.ts
index ec90891f2a5..2b6b6b0263b 100644
--- a/tests/codex-integration/codex-prompt-route.test.ts
+++ b/tests/codex-integration/codex-prompt-route.test.ts
@@ -21,9 +21,13 @@ import {
 import type { ManagementPrincipal } from "../../src/server/management-auth";
 import type { OcxConfig } from "../../src/types";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { OCX_SECTION_MARKER } from "../../src/codex/injected-marker";
 import { INTERNAL_DEADLINE_MS } from "../helpers/test-budget";
 
-const MARKER = "# Auto-injected by opencodex";
+// Prompt layers deliberately keep the BARE ownership marker: 'ocx restore' is not their undo,
+// so the recovery hint that routing keys carry (#5261) does not belong here. Derived from the
+// constant rather than restated, so the two scopes cannot drift apart silently.
+const MARKER = OCX_SECTION_MARKER;
 const config = { port: 10100, defaultProvider: "openai", providers: {} } as OcxConfig;
 const roots: string[] = [];
 
diff --git a/tests/codex-integration/codex-routing-cache-affinity-detour.test.ts b/tests/codex-integration/codex-routing-cache-affinity-detour.test.ts
new file mode 100644
index 00000000000..ccf1fa38f9f
--- /dev/null
+++ b/tests/codex-integration/codex-routing-cache-affinity-detour.test.ts
@@ -0,0 +1,199 @@
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  clearCodexUpstreamHealth,
+  clearThreadAccountMap,
+  getEffectiveActiveCodexAccountId,
+  resolveCodexAccountForThread,
+  resolveCodexAccountForThreadDetailed,
+} from "../../src/codex/routing";
+import { clearPoolRotationState } from "../../src/codex/pool-rotation";
+import { saveCodexAccountCredential } from "../../src/codex/account-store";
+import {
+  clearAccountNeedsReauth,
+  clearAccountQuota,
+  updateAccountQuota,
+} from "../../src/codex/auth-api";
+import type { OcxConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { setAsyncIcaclsRunnerForTests, setIcaclsRunnerForTests } from "../../src/lib/windows-secret-acl";
+
+// These cases moved out of codex-routing.test.ts, which sits at its file-size
+// cap. They cover the cache-affinity boundary between a proactive quota-switch
+// threshold crossing (a hint) and genuine 100% exhaustion (evidence) for a
+// shared binding during a model-scoped detour.
+
+let TEST_DIR = "";
+let previousOpencodexHome: string | undefined;
+let previousCodexHome: string | undefined;
+
+const ICACLS_OK = { success: true, exitCode: 0, timedOut: false, stdout: "" };
+
+function installRoutingScratchHome(): void {
+  previousOpencodexHome = process.env.OPENCODEX_HOME;
+  previousCodexHome = process.env.CODEX_HOME;
+  TEST_DIR = mkdtempSync(join(tmpdir(), "ocx-routing-"));
+  // Routing cases exercise account state, not the operating system ACL implementation.
+  setIcaclsRunnerForTests(() => ICACLS_OK);
+  setAsyncIcaclsRunnerForTests(async () => ICACLS_OK);
+  process.env.OPENCODEX_HOME = TEST_DIR;
+  process.env.CODEX_HOME = TEST_DIR;
+}
+
+async function removeRoutingScratchHome(): Promise<void> {
+  const ownedDirectory = TEST_DIR;
+  try {
+    setIcaclsRunnerForTests(null);
+    setAsyncIcaclsRunnerForTests(null);
+  } finally {
+    if (previousOpencodexHome === undefined) delete process.env.OPENCODEX_HOME;
+    else process.env.OPENCODEX_HOME = previousOpencodexHome;
+    if (previousCodexHome === undefined) delete process.env.CODEX_HOME;
+    else process.env.CODEX_HOME = previousCodexHome;
+    if (ownedDirectory) removeTreeWithRetry(ownedDirectory);
+  }
+}
+
+function makeConfig(overrides: Partial<OcxConfig> = {}): OcxConfig {
+  return {
+    providers: {},
+    codexAccounts: [
+      { id: "a", email: "a@test", isMain: false },
+      { id: "b", email: "b@test", isMain: false },
+    ],
+    activeCodexAccountId: "a",
+    autoSwitchThreshold: 80,
+    upstreamFailoverThreshold: 3,
+    ...overrides,
+  } as OcxConfig;
+}
+
+function saveTestCredential(id: string): void {
+  saveCodexAccountCredential(id, {
+    accessToken: "access-" + id,
+    refreshToken: "refresh-" + id,
+    expiresAt: Date.now() + 5 * 60_000,
+    chatgptAccountId: "acct-" + id,
+  });
+}
+
+describe("cache affinity across model detours", () => {
+  beforeEach(() => {
+    installRoutingScratchHome();
+    clearThreadAccountMap();
+    clearCodexUpstreamHealth();
+    clearAccountQuota();
+    clearPoolRotationState();
+    clearAccountNeedsReauth("a");
+    clearAccountNeedsReauth("b");
+    saveTestCredential("a");
+    saveTestCredential("b");
+  });
+
+  afterEach(async () => {
+    try {
+      clearAccountQuota();
+      clearCodexUpstreamHealth();
+      clearThreadAccountMap();
+      clearPoolRotationState();
+      clearAccountNeedsReauth("a");
+      clearAccountNeedsReauth("b");
+    } finally {
+      await removeRoutingScratchHome();
+    }
+  });
+
+  /** \`a\` is ordered above \`b\`; the persisted operator selection is the lower tier. */
+  function orderedConfig(overrides: Partial<OcxConfig> = {}): OcxConfig {
+    return makeConfig({
+      activeCodexAccountId: "b",
+      codexAccountPriorities: { a: 1 },
+      ...overrides,
+    } as Partial<OcxConfig>);
+  }
+
+  test("cache affinity preserves an over-threshold shared binding across a model detour", () => {
+    const config = orderedConfig({
+      accountPoolStrategy: "quota",
+      activeCodexAccountId: "a",
+      activeCodexAccountPinned: "a",
+      autoSwitchThreshold: 80,
+      pool: { cacheAffinity: true },
+    });
+    const now = Date.now();
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 10);
+
+    expect(resolveCodexAccountForThread("cache-affine-model-detour", config, now, "shared")).toBe("a");
+    updateAccountQuota("a", 90);
+    expect(resolveCodexAccountForThreadDetailed(
+      "cache-affine-model-detour",
+      config,
+      now + 1,
+      "shared",
+      { modelEligibleAccountIds: new Set(["b"]) },
+    )).toMatchObject({ status: "selected", accountId: "b" });
+
+    expect(getEffectiveActiveCodexAccountId(config)).toBe("a");
+    expect(resolveCodexAccountForThread("cache-affine-model-detour", config, now + 2, "shared")).toBe("a");
+  });
+
+  test("cache affinity releases a fully exhausted shared binding across a model detour", () => {
+    const config = orderedConfig({
+      accountPoolStrategy: "quota",
+      activeCodexAccountId: "a",
+      activeCodexAccountPinned: "a",
+      autoSwitchThreshold: 80,
+      pool: { cacheAffinity: true },
+    });
+    const now = Date.now();
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 10);
+
+    expect(resolveCodexAccountForThread("cache-affine-exhausted-detour", config, now, "shared")).toBe("a");
+    updateAccountQuota("a", 100);
+    expect(resolveCodexAccountForThreadDetailed(
+      "cache-affine-exhausted-detour",
+      config,
+      now + 1,
+      "shared",
+      { modelEligibleAccountIds: new Set(["b"]) },
+    )).toMatchObject({ status: "selected", accountId: "b" });
+
+    // Genuine exhaustion is the live-binding bar: the shared cursor follows the account
+    // that actually served instead of staying parked on the drained one.
+    expect(getEffectiveActiveCodexAccountId(config)).toBe("b");
+    expect(resolveCodexAccountForThread("cache-affine-exhausted-detour", config, now + 2, "shared")).toBe("b");
+  });
+
+  test("cache affinity releases an exhausted shared binding even with quota switching disabled", () => {
+    const config = orderedConfig({
+      accountPoolStrategy: "quota",
+      activeCodexAccountId: "a",
+      activeCodexAccountPinned: "a",
+      autoSwitchThreshold: 0,
+      pool: { cacheAffinity: true },
+    });
+    const now = Date.now();
+    updateAccountQuota("a", 10);
+    updateAccountQuota("b", 10);
+
+    expect(resolveCodexAccountForThread("cache-affine-disabled-detour", config, now, "shared")).toBe("a");
+    updateAccountQuota("a", 100);
+    expect(resolveCodexAccountForThreadDetailed(
+      "cache-affine-disabled-detour",
+      config,
+      now + 1,
+      "shared",
+      { modelEligibleAccountIds: new Set(["b"]) },
+    )).toMatchObject({ status: "selected", accountId: "b" });
+
+    // Genuine exhaustion drops the binding even when threshold switching is disabled --
+    // the same >=100% boundary a live binding gets -- and the shared selection follows
+    // the account that actually served.
+    expect(getEffectiveActiveCodexAccountId(config)).toBe("b");
+    expect(resolveCodexAccountForThread("cache-affine-disabled-detour", config, now + 2, "shared")).toBe("b");
+  });
+});
diff --git a/tests/codex-integration/codex-routing.test.ts b/tests/codex-integration/codex-routing.test.ts
index b769a74c707..7d0d1b689b2 100644
--- a/tests/codex-integration/codex-routing.test.ts
+++ b/tests/codex-integration/codex-routing.test.ts
@@ -3174,7 +3174,7 @@ describe("codex account selection order", () => {
       activeCodexAccountPinned: "b",
     });
     updateAccountQuota("a", 10);
-    updateAccountQuota("b", 90);
+    updateAccountQuota("b", 100);
 
     expect(resolveCodexAccountForThreadDetailed(
       null,
@@ -3218,7 +3218,7 @@ describe("codex account selection order", () => {
       activeCodexAccountPinned: "b",
     });
     updateAccountQuota("a", 10);
-    updateAccountQuota("b", 90);
+    updateAccountQuota("b", 100);
 
     expect(resolveCodexAccountForThreadDetailed(
       null,
diff --git a/tests/codex-integration/codex-shim-autorestore.test.ts b/tests/codex-integration/codex-shim-autorestore.test.ts
index 75562bbc567..5f942c3f5dc 100644
--- a/tests/codex-integration/codex-shim-autorestore.test.ts
+++ b/tests/codex-integration/codex-shim-autorestore.test.ts
@@ -48,6 +48,10 @@ describe("Codex shim CLI auto-restore policy", () => {
       expect(skipsCodexShimAutoRestore("system", args)).toBe(true);
     }
     expect(skipsCodexShimAutoRestore("system", ["system", "update", "check"])).toBe(false);
+    // resolve is read-only inspection for embedding shells: a lookup made to populate a
+    // consent surface must not trigger a shim repair side effect first.
+    expect(skipsCodexShimAutoRestore("resolve", ["resolve"])).toBe(true);
+    expect(skipsCodexShimAutoRestore("resolve", ["resolve", "--json"])).toBe(true);
     expect(skipsCodexShimAutoRestore("status", ["status"])).toBe(false);
   });
 
diff --git a/tests/codex-integration/codex-shim-ensure-failure.test.ts b/tests/codex-integration/codex-shim-ensure-failure.test.ts
new file mode 100644
index 00000000000..ab652d64305
--- /dev/null
+++ b/tests/codex-integration/codex-shim-ensure-failure.test.ts
@@ -0,0 +1,117 @@
+/**
+ * #5261: the Codex autostart shim must never hide a failed autostart, and must never be the
+ * reason Codex does not launch.
+ *
+ * It used to do both. Both of `ocx ensure`'s streams were discarded and its exit status ignored
+ * with `|| true`, so a proxy that failed to come up was completely silent while Codex launched
+ * against injected routing pointing at a dead port. These run the real generated script against
+ * a stand-in `ensure` rather than asserting on template text, because the property under test is
+ * what the shell does with the exit status, not what the file says.
+ *
+ * Lives beside `codex-shim.test.ts` rather than inside it: that file sits close to its line cap,
+ * and the cap only moves down.
+ */
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildUnixCodexShim } from "../../src/codex/shim";
+import { CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC } from "../../src/codex/shim-templates";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { INTERNAL_DEADLINE_MS, SPAWN_BUDGET_MS } from "../helpers/test-budget";
+
+/** The shim refuses to re-enter itself, so a nested test run must not inherit its guard state. */
+function cleanShimEnv(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env, OCX_SHIM_BYPASS: "" };
+  delete env.OCX_SHIM_ACTIVE_PID;
+  delete env.OCX_SHIM_ACTIVE_DEPTH;
+  delete env.OCX_SHIM_PROBE_ACTIVE;
+  return env;
+}
+
+/**
+ * A shim whose `ensure` is `script`. The real Codex prints a marker and exits 7, so every case
+ * can tell whether Codex ran and whether its exit status survived the wrapper.
+ */
+function shimWithEnsure(dir: string, script: string): string {
+  const realCodex = join(dir, "codex-real");
+  writeFileSync(realCodex, "#!/bin/sh\necho codex-ran\nexit 7\n");
+  chmodSync(realCodex, 0o755);
+  const fakeBun = join(dir, "fake-bun");
+  writeFileSync(fakeBun, script);
+  chmodSync(fakeBun, 0o755);
+  const wrapper = join(dir, "codex");
+  writeFileSync(wrapper, buildUnixCodexShim(realCodex, fakeBun, join(dir, "cli.ts"), "process", join(dir, "absent-token")));
+  chmodSync(wrapper, 0o755);
+  return wrapper;
+}
+
+function runShim(wrapper: string) {
+  return spawnSync("/bin/sh", [wrapper, "exec", "hello"], {
+    encoding: "utf8",
+    env: cleanShimEnv(),
+    timeout: INTERNAL_DEADLINE_MS,
+  });
+}
+
+describe.skipIf(process.platform === "win32")("Codex shim autostart failure (#5261)", () => {
+  test("a failed ensure is reported once on stderr and Codex still launches", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ocx-shim-ensure-fail-"));
+    try {
+      // Writes to both streams so the assertions below also prove ensure's own chatter
+      // stays discarded: leaking it would put noise in front of every Codex launch.
+      const wrapper = shimWithEnsure(dir, "#!/bin/sh\necho ensure-stdout\necho ensure-stderr >&2\nexit 1\n");
+      const run = runShim(wrapper);
+
+      expect(run.error).toBeUndefined();
+      expect(run.stdout).toContain("codex-ran");
+      expect(run.status).toBe(7);
+      expect(run.stderr).toContain(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC);
+      expect(run.stderr).not.toContain("ensure-stderr");
+      expect(run.stdout).not.toContain("ensure-stdout");
+
+      // Once, not once per stream or per retry.
+      const occurrences = run.stderr.split(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC).length - 1;
+      expect(occurrences).toBe(1);
+    } finally {
+      removeTreeWithRetry(dir);
+    }
+  }, SPAWN_BUDGET_MS);
+
+  test("a successful ensure says nothing at all", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ocx-shim-ensure-ok-"));
+    try {
+      const wrapper = shimWithEnsure(dir, "#!/bin/sh\necho ensure-stdout\nexit 0\n");
+      const run = runShim(wrapper);
+
+      expect(run.stdout).toContain("codex-ran");
+      expect(run.status).toBe(7);
+      expect(run.stderr).not.toContain(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC);
+      expect(run.stdout).not.toContain("ensure-stdout");
+    } finally {
+      removeTreeWithRetry(dir);
+    }
+  }, SPAWN_BUDGET_MS);
+
+  test("an ensure that cannot be executed at all is still not a lockout", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ocx-shim-ensure-missing-"));
+    try {
+      // The launcher path does not exist. This is the headless/broken-install shape, and the
+      // wrapper must treat it exactly like a failed start rather than dying with it.
+      const realCodex = join(dir, "codex-real");
+      writeFileSync(realCodex, "#!/bin/sh\necho codex-ran\nexit 7\n");
+      chmodSync(realCodex, 0o755);
+      const wrapper = join(dir, "codex");
+      writeFileSync(wrapper, buildUnixCodexShim(realCodex, join(dir, "no-such-bun"), join(dir, "cli.ts"), "process", join(dir, "absent-token")));
+      chmodSync(wrapper, 0o755);
+
+      const run = runShim(wrapper);
+      expect(run.stdout).toContain("codex-ran");
+      expect(run.status).toBe(7);
+      expect(run.stderr).toContain(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC);
+    } finally {
+      removeTreeWithRetry(dir);
+    }
+  }, SPAWN_BUDGET_MS);
+});
diff --git a/tests/codex-integration/codex-shim.test.ts b/tests/codex-integration/codex-shim.test.ts
index f684fa8de91..efc971030b4 100644
--- a/tests/codex-integration/codex-shim.test.ts
+++ b/tests/codex-integration/codex-shim.test.ts
@@ -8,9 +8,8 @@ import { prependPath, withInstalledShim } from "../helpers/codex-shim-install-fi
 import { removeTreeWithRetry } from "../helpers/remove-tree";
 import { repoPath, repoRoot } from "../helpers/repo-root";
 import { INTERNAL_DEADLINE_MS, SPAWN_BUDGET_MS } from "../helpers/test-budget";
+import { CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC, SHIM_MARKER, UNIX_SHIM_REVISION_MARKER } from "../../src/codex/shim-templates";
 
-const SHIM_MARKER = "opencodex codex autostart shim";
-const UNIX_SHIM_REVISION_MARKER = "opencodex unix codex shim revision 2";
 
 /**
  * A child environment with the shim's recursion-guard state stripped.
@@ -1321,7 +1320,10 @@ printf '%s\\n' child-codex
             const driverPath = join(dir, "driver.ps1");
             const realPath = join(dir, "codex-real.ps1");
             writeFileSync(join(dir, "service-api-token"), "file-token\n");
-            writeFileSync(ensurePath, failurePhase === "ensure" ? "throw 'fixture ensure failure'\n" : "exit 19\n");
+            // The Codex phase must isolate a Codex failure, so its ensure has to SUCCEED. It used
+            // to exit 19, which the wrapper now correctly reports as a failed autostart (#5261),
+            // making both phases indistinguishable.
+            writeFileSync(ensurePath, failurePhase === "ensure" ? "throw 'fixture ensure failure'\n" : "exit 0\n");
             writeFileSync(realPath, "throw 'fixture Codex failure'\n");
             writeFileSync(wrapperPath, `\uFEFF${buildWindowsPowerShellCodexShim(realPath, ensurePath, "unused.ts", "process")}`);
             const emptyToken = callerToken === "" ? "$env:OPENCODEX_API_AUTH_TOKEN = ''\n" : "";
@@ -1333,9 +1335,14 @@ printf '%s\\n' child-codex
             });
             expect(result.error).toBeUndefined();
             expect(result.status, result.stderr).toBe(0);
+            // An ensure failure no longer stops Codex from launching (#5261). The wrapper
+            // reports it on stderr and hands over to the real launcher, so the error that
+            // reaches the caller is always Codex's own, in both phases.
+            const surfaced = "fixture Codex failure";
             expect(result.stdout.trim().split(/\r?\n/)).toEqual([
-              `error:fixture ${failurePhase} failure`, `after:${callerToken ?? ""}`, "presence-preserved:True",
+              `error:${surfaced}`, `after:${callerToken ?? ""}`, "presence-preserved:True",
             ]);
+            expect(result.stderr.includes(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC)).toBe(failurePhase === "ensure");
 
             // A failed process must complete, rather than satisfy the check through a timeout.
             writeFileSync(driverPath, `\uFEFF$ErrorActionPreference = 'Stop'\n& '${wrapperPath.replace(/'/g, "''")}' exec\n`);
@@ -1346,7 +1353,8 @@ printf '%s\\n' child-codex
             expect(uncaught.signal).toBeNull();
             expect(typeof uncaught.status, uncaught.stderr).toBe("number");
             expect(uncaught.status, uncaught.stderr).not.toBe(0);
-            expect(uncaught.stderr).toContain(`fixture ${failurePhase} failure`);
+            expect(uncaught.stderr).toContain(surfaced);
+            expect(uncaught.stderr.includes(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC)).toBe(failurePhase === "ensure");
           } finally {
             if (oldHome === undefined) delete process.env.OPENCODEX_HOME;
             else process.env.OPENCODEX_HOME = oldHome;
diff --git a/tests/codex-integration/codex-signin-lockout.test.ts b/tests/codex-integration/codex-signin-lockout.test.ts
new file mode 100644
index 00000000000..a11f6ec5789
--- /dev/null
+++ b/tests/codex-integration/codex-signin-lockout.test.ts
@@ -0,0 +1,185 @@
+/**
+ * #5261: opencodex must not be able to lock a user out of Codex.
+ *
+ * The reported machine was a Windows 11 install whose proxy had stopped. The routing
+ * opencodex had written to `~/.codex/config.toml` stayed on disk across a reboot, so Codex's
+ * own built-in openai provider kept resolving to a loopback port nothing was listening on,
+ * and the user was stopped at sign-in with no mention of opencodex on screen.
+ *
+ * Nothing here starts a proxy, binds a port, or touches a real Codex home. That is the point:
+ * these are exactly the transforms recovery must be able to run while the proxy is dead, so a
+ * test that needed one running would be testing the wrong state.
+ */
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  OCX_ROUTING_MARKER_LINE,
+  OCX_SECTION_MARKER,
+  hasInjectedCodexRouting,
+  hasInjectedOpenaiBaseUrl,
+} from "../../src/codex/injected-marker";
+import { missingOwnedCatalogPath, setRootOpenaiBaseUrl, setRootRealtimeWsBaseUrl } from "../../src/codex/inject/config-toml";
+import { stripOpencodexConfig } from "../../src/codex/inject/remove";
+import { deadProxyRoutingAdviceLines, missingCodexCatalogLines } from "../../src/cli/status";
+import { findCommand } from "../../src/cli/registry";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+/** A Windows catalog path as TOML stores it: a basic string doubles the separators (#1798). */
+const WINDOWS_CATALOG = JSON.stringify(String.raw`C:\Users\example\.codex\opencodex-catalog.json`);
+
+/** The loopback target the reported install was on. */
+const TARGET = {
+  baseUrl: "http://127.0.0.1:10100/v1",
+  requiresAdmissionToken: false,
+  tokenEnv: "OPENCODEX_API_AUTH_TOKEN",
+} as const;
+
+/** The reported file, reconstructed: routing on disk, proxy gone. `marker` is the ownership line. */
+function lockedOutConfig(marker: string): string {
+  return [
+    'model = "gpt-5.5"',
+    `model_catalog_json = ${WINDOWS_CATALOG}`,
+    marker,
+    'openai_base_url = "http://127.0.0.1:10100/v1"',
+    marker,
+    'experimental_realtime_ws_base_url = "http://127.0.0.1:10100/v1"',
+    "",
+    "[features]",
+    "fast_mode = true",
+    "",
+  ].join("\n");
+}
+
+describe("Codex sign-in lockout behind a stopped proxy (#5261)", () => {
+  test("routing written before the recovery hint existed is still recognized as ours", () => {
+    const legacy = lockedOutConfig(OCX_SECTION_MARKER);
+    expect(hasInjectedOpenaiBaseUrl(legacy)).toBe(true);
+    expect(hasInjectedCodexRouting(legacy)).toBe(true);
+  });
+
+  test("the hint changes what we write, never what we recognize or remove", () => {
+    const hinted = lockedOutConfig(OCX_ROUTING_MARKER_LINE);
+    expect(hasInjectedOpenaiBaseUrl(hinted)).toBe(true);
+    expect(hasInjectedCodexRouting(hinted)).toBe(true);
+    // Byte-identical recovery from either marker: the two forms must not diverge, or an
+    // install that upgraded mid-incident would restore differently from one that did not.
+    expect(stripOpencodexConfig(hinted)).toBe(stripOpencodexConfig(lockedOutConfig(OCX_SECTION_MARKER)));
+  });
+
+  test("recovery removes every dead endpoint without a proxy, and keeps the user's own keys", () => {
+    const restored = stripOpencodexConfig(lockedOutConfig(OCX_ROUTING_MARKER_LINE));
+    expect(restored).not.toContain("openai_base_url");
+    expect(restored).not.toContain("experimental_realtime_ws_base_url");
+    // The catalog pointer has to go with the routing. Left behind, it names a file only
+    // opencodex maintains, and Codex fails on a missing model_catalog_json target.
+    expect(restored).not.toContain("opencodex-catalog.json");
+    expect(restored).not.toContain("Auto-injected by opencodex");
+    expect(restored).toContain('model = "gpt-5.5"');
+    expect(restored).toContain("[features]");
+    expect(restored).toContain("fast_mode = true");
+  });
+
+  test("an install that predates the hint gains it on the next injection, and stays idempotent", () => {
+    const legacy = lockedOutConfig(OCX_SECTION_MARKER);
+    const markers = (content: string) => content.split("\n").filter(line => line.includes(OCX_SECTION_MARKER));
+    expect(markers(legacy)).toEqual([OCX_SECTION_MARKER, OCX_SECTION_MARKER]);
+
+    const first = setRootOpenaiBaseUrl(legacy, 10100);
+    expect(first.keptUserBaseUrl).toBe(false);
+    // Each writer refreshes only the marker it owns, so after the routing key alone the
+    // realtime marker is still the legacy line. Refreshed in place, never appended.
+    expect(markers(first.content)).toEqual([OCX_ROUTING_MARKER_LINE, OCX_SECTION_MARKER]);
+    expect(setRootOpenaiBaseUrl(first.content, 10100).content).toBe(first.content);
+
+    const both = setRootRealtimeWsBaseUrl(first.content, TARGET);
+    expect(both.keptUserRealtimeWsBaseUrl).toBe(false);
+    expect(markers(both.content)).toEqual([OCX_ROUTING_MARKER_LINE, OCX_ROUTING_MARKER_LINE]);
+    expect(setRootRealtimeWsBaseUrl(both.content, TARGET).content).toBe(both.content);
+  });
+
+  test("a user's own root override is still left alone and gains no hint", () => {
+    const userOwned = 'model = "gpt-5.5"\nopenai_base_url = "https://gateway.example/v1"\n';
+    const result = setRootOpenaiBaseUrl(userOwned, 10100);
+    expect(result.keptUserBaseUrl).toBe(true);
+    expect(result.content).toBe(userOwned);
+    expect(result.content).not.toContain("undo:");
+  });
+
+  test("a dead proxy on our own routing is told how to get Codex back without one", () => {
+    const advice = deadProxyRoutingAdviceLines({ proxyUp: false, routingKind: "opencodex-local" });
+    expect(advice.length).toBeGreaterThan(0);
+    expect(advice.join(" ")).toContain("sign-in");
+    expect(advice.join(" ")).toContain("ocx restore");
+  });
+
+  test("the advice stays silent when it would be wrong or unactionable", () => {
+    // A live proxy is not this failure.
+    expect(deadProxyRoutingAdviceLines({ proxyUp: true, routingKind: "opencodex-local" })).toEqual([]);
+    // Routing we do not own: `ocx restore` would not remove it, so promising it would mislead.
+    for (const routingKind of ["native", "custom-local", "custom-remote", "unknown"] as const) {
+      expect(deadProxyRoutingAdviceLines({ proxyUp: false, routingKind })).toEqual([]);
+    }
+  });
+
+  test("both recovery surfaces name a command the CLI actually has", () => {
+    // Derived from the marker rather than restated, so renaming the command in one place and
+    // not the other fails here instead of shipping a config file that names nothing.
+    const named = /ocx ([a-z][a-z-]*)/.exec(OCX_ROUTING_MARKER_LINE)?.[1];
+    expect(named).toBeTruthy();
+    expect(findCommand(named!)).toBeDefined();
+    expect(deadProxyRoutingAdviceLines({ proxyUp: false, routingKind: "opencodex-local" }).join(" "))
+      .toContain(`ocx ${named}`);
+  });
+});
+
+describe("a Codex catalog pointer whose file is gone (#5261)", () => {
+  /** Builds a root config naming `catalogPath`, in the escaped form TOML actually stores. */
+  const configNaming = (catalogPath: string) =>
+    `model = "gpt-5.5"\nmodel_catalog_json = ${JSON.stringify(catalogPath)}\n`;
+
+  test("an owned catalog that is missing is reported, and one that exists is not", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ocx-catalog-pointer-"));
+    try {
+      // Ownership is by basename, which is what injection already uses. Pinned here so the
+      // detector cannot start disagreeing with the code that writes and strips the same line.
+      const present = join(dir, "opencodex-catalog.json");
+      writeFileSync(present, "{}");
+      const absent = join(dir, "gone", "opencodex-catalog.json");
+
+      expect(missingOwnedCatalogPath(configNaming(absent))).toBe(absent);
+      expect(missingOwnedCatalogPath(configNaming(present))).toBeNull();
+    } finally {
+      removeTreeWithRetry(dir);
+    }
+  });
+
+  test("a catalog the user named is theirs, present or not", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ocx-catalog-user-"));
+    try {
+      // Same missing file, a name we never write. Claiming it would put opencodex's recovery
+      // advice in front of a problem that is not opencodex's to explain.
+      const userOwned = join(dir, "gone", "my-catalog.json");
+      expect(missingOwnedCatalogPath(configNaming(userOwned))).toBeNull();
+      expect(missingOwnedCatalogPath('model = "gpt-5.5"\n')).toBeNull();
+    } finally {
+      removeTreeWithRetry(dir);
+    }
+  });
+
+  test("the report names the file and both ways out", () => {
+    const lines = missingCodexCatalogLines("/somewhere/opencodex-catalog.json");
+    expect(lines.length).toBeGreaterThan(0);
+    const joined = lines.join(" ");
+    expect(joined).toContain("/somewhere/opencodex-catalog.json");
+    // Regenerating and removing are different outcomes; the user picks, so both are offered.
+    expect(joined).toContain("ocx start");
+    expect(joined).toContain("ocx restore");
+    expect(missingCodexCatalogLines(null)).toEqual([]);
+  });
+
+  test("the commands it names are real", () => {
+    for (const name of ["start", "restore"]) expect(findCommand(name)).toBeDefined();
+  });
+});
diff --git a/tests/codex-integration/history-paginated-openai-compat.test.ts b/tests/codex-integration/history-paginated-openai-compat.test.ts
new file mode 100644
index 00000000000..7a7f10b8901
--- /dev/null
+++ b/tests/codex-integration/history-paginated-openai-compat.test.ts
@@ -0,0 +1,119 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { applyPaginatedOpenaiCompat } from "../../src/codex/inject/paginated-openai-compat";
+import {
+  HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE,
+  HISTORY_RELABEL_STANDS_DOWN,
+} from "../../src/codex/history-provider";
+import { OCX_ROUTING_MARKER_LINE } from "../../src/codex/injected-marker";
+import type { CodexRoutingTarget } from "../../src/codex/inject/routing-target";
+import { repoPath } from "../helpers/repo-root";
+
+const BASE_URL = "http://127.0.0.1:10100/v1";
+const loopback: CodexRoutingTarget = {
+  baseUrl: BASE_URL,
+  requiresAdmissionToken: false,
+  tokenEnv: "OPENCODEX_API_AUTH_TOKEN",
+  desktopAuthless: true,
+};
+const admissionToken: CodexRoutingTarget = {
+  baseUrl: "https://proxy.example/v1",
+  requiresAdmissionToken: true,
+  tokenEnv: "OPENCODEX_API_AUTH_TOKEN",
+};
+
+// The provider-table candidate as the injector hands it over: root model_provider plus the
+// table, and no root openai_base_url, because a table transition takes that key out.
+const TABLE_CANDIDATE = [
+  'model_provider = "opencodex"',
+  'model = "vendor/routed-model"',
+  "",
+  "[model_providers.opencodex]",
+  `base_url = "${BASE_URL}"`,
+  "",
+].join("\n");
+
+describe("paginated openai compatibility (#5321)", () => {
+  test("a loopback table transition retains the root override and stands the relabel down", () => {
+    const decision = applyPaginatedOpenaiCompat(
+      HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE, loopback, TABLE_CANDIDATE, "\n",
+    );
+    // Standing down rather than clearing the reason is what keeps the caller from starting the
+    // relabel unit at all: the paginated row must not be rewritten, only kept resolvable.
+    expect(decision.refusal).toBe(HISTORY_RELABEL_STANDS_DOWN);
+    expect(decision.retainedRootOverride).toBe(true);
+    expect(decision.content).toContain(`${OCX_ROUTING_MARKER_LINE}\nopenai_base_url = "${BASE_URL}"`);
+    // The table has to survive alongside it, or new authless threads lose their provider.
+    expect(decision.content).toContain("[model_providers.opencodex]");
+    expect(decision.content).toContain('model_provider = "opencodex"');
+  });
+
+  test("the retained override is written before the first table, where Codex reads root keys", () => {
+    const decision = applyPaginatedOpenaiCompat(
+      HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE, loopback, TABLE_CANDIDATE, "\n",
+    );
+    const lines = decision.content.split("\n");
+    expect(lines.findIndex(line => line.startsWith("openai_base_url")))
+      .toBeLessThan(lines.findIndex(line => line.startsWith("[")));
+  });
+
+  test("CRLF config keeps its line endings through the retention", () => {
+    const decision = applyPaginatedOpenaiCompat(
+      HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE, loopback, TABLE_CANDIDATE.replace(/\n/g, "\r\n"), "\r\n",
+    );
+    expect(decision.content).toContain("\r\n");
+    expect(decision.content.replace(/\r\n/g, "")).not.toContain("\n");
+  });
+
+  test("a root line the user owns is left alone and never journaled as ours", () => {
+    const userOwned = `openai_base_url = "https://my-gateway.example/v1"\n${TABLE_CANDIDATE}`;
+    const decision = applyPaginatedOpenaiCompat(
+      HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE, loopback, userOwned, "\n",
+    );
+    // The transition still completes — the conversation follows the destination the user chose,
+    // which is the same guarantee the injector makes everywhere else about a line it does not own.
+    expect(decision.refusal).toBe(HISTORY_RELABEL_STANDS_DOWN);
+    expect(decision.retainedRootOverride).toBe(false);
+    expect(decision.content).toBe(userOwned);
+  });
+
+  test("an admission-token form keeps the refusal and names both ways out", () => {
+    const decision = applyPaginatedOpenaiCompat(
+      HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE, admissionToken, TABLE_CANDIDATE, "\n",
+    );
+    expect(decision.refusal).toBe(HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE);
+    expect(decision.retainedRootOverride).toBe(false);
+    expect(decision.content).toBe(TABLE_CANDIDATE);
+    // The regression was not the refusal, it was "do not retry" with nowhere to go. Both named
+    // remedies must be real configuration keys, so they are asserted against the config type.
+    const configSource = readFileSync(repoPath("src", "types", "config.ts"), "utf8");
+    for (const key of ["syncResumeHistory", "unauthenticatedLoopbackListener"]) {
+      expect(decision.message).toContain(key);
+      expect(configSource).toContain(`${key}?:`);
+    }
+    expect(decision.message).not.toContain("do not run legacy recovery");
+  });
+
+  test("every other reason passes through with the refusal text it always had", () => {
+    const decision = applyPaginatedOpenaiCompat("history_rollout_identity_changed", loopback, TABLE_CANDIDATE, "\n");
+    expect(decision.refusal).toBe("history_rollout_identity_changed");
+    expect(decision.retainedRootOverride).toBe(false);
+    expect(decision.content).toBe(TABLE_CANDIDATE);
+    expect(decision.message).toContain("do not run legacy recovery or retry this transition blindly");
+    // A plain stand-down is not this resolver's business and must reach the caller untouched.
+    expect(applyPaginatedOpenaiCompat(HISTORY_RELABEL_STANDS_DOWN, loopback, TABLE_CANDIDATE, "\n"))
+      .toMatchObject({ refusal: HISTORY_RELABEL_STANDS_DOWN, retainedRootOverride: false, content: TABLE_CANDIDATE });
+    expect(applyPaginatedOpenaiCompat(null, loopback, TABLE_CANDIDATE, "\n"))
+      .toMatchObject({ refusal: null, retainedRootOverride: false, content: TABLE_CANDIDATE });
+  });
+
+  test("the refusal code is defined once and read from that definition", () => {
+    // The pair drifted once already between apply and restore. A literal in a second file is
+    // how it drifts again, so the only occurrences allowed are the constant and its consumers.
+    const provider = readFileSync(repoPath("src", "codex", "history-provider.ts"), "utf8");
+    const occurrences = provider.split(HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE).length - 1;
+    expect(occurrences).toBe(1);
+    expect(readFileSync(repoPath("src", "codex", "inject", "paginated-openai-compat.ts"), "utf8"))
+      .not.toContain(`"${HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE}"`);
+  });
+});
diff --git a/tests/codex-integration/history-paginated-transition-destinations.test.ts b/tests/codex-integration/history-paginated-transition-destinations.test.ts
new file mode 100644
index 00000000000..6ff4f56db66
--- /dev/null
+++ b/tests/codex-integration/history-paginated-transition-destinations.test.ts
@@ -0,0 +1,332 @@
+/**
+ * What the paginated-history transition leaves behind, judged by destination.
+ *
+ * #5321 made the provider-table transition complete on a home Codex has already migrated to
+ * paginated history. Completing it is not the property that matters to the operator: a
+ * transition that succeeds while quietly moving the conversations a home already had onto
+ * Codex's own OpenAI endpoint is worse than the refusal it replaced. Every case below reads
+ * the state AFTER the write and resolves, for each conversation the home already had and for
+ * the one it will create next, which destination Codex would actually use.
+ *
+ * Nothing here starts the proxy or any service. The injector runs in a child process against a
+ * temporary CODEX_HOME so its module-level path constants bind to the fixture, which is the
+ * isolation the neighbouring integration file already uses.
+ */
+import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Database } from "bun:sqlite";
+
+import {
+  HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE,
+  HISTORY_RELABEL_STANDS_DOWN,
+} from "../../src/codex/history-provider";
+import { OCX_ROUTING_MARKER_LINE } from "../../src/codex/injected-marker";
+import { standaloneCodexRoutingTarget } from "../../src/codex/inject/routing-target";
+import { validHistoryBackupFixture } from "../helpers/codex-history-manifest-fixtures";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { repoRoot as resolveRepoRoot } from "../helpers/repo-root";
+import { SPAWN_BUDGET_MS } from "../helpers/test-budget";
+
+const repoRoot = resolveRepoRoot();
+setDefaultTimeout(SPAWN_BUDGET_MS);
+
+const PORT = 10100;
+
+/** Derived from the injector's own target builder, so the URL under test is never a literal. */
+const PROXY_BASE_URL = standaloneCodexRoutingTarget(PORT, { codexDesktopAuthless: true }).baseUrl;
+
+/**
+ * Where a conversation ends up when nothing this project wrote applies to it: Codex's built-in
+ * `openai` entry with no root override, or a `model_provider` id whose table is absent. Both are
+ * "not this proxy", which is the outcome these cases exist to rule out.
+ */
+const CODEX_OWN_ENDPOINT = "codex-built-in-openai-endpoint";
+
+/**
+ * The resolution Codex performs, applied to the config that was actually written.
+ *
+ * An `openai`-tagged conversation reads the built-in entry, whose base URL is the root
+ * `openai_base_url` when one is present. Any other tag reads its own provider table. Asserting
+ * on key presence would have passed for a config that names a provider it never defines.
+ */
+function destinationOf(config: Record<string, unknown>, modelProvider: string): string {
+  if (modelProvider === "openai") {
+    const override = config.openai_base_url;
+    return typeof override === "string" ? override : CODEX_OWN_ENDPOINT;
+  }
+  const tables = config.model_providers;
+  const table = tables && typeof tables === "object"
+    ? (tables as Record<string, unknown>)[modelProvider]
+    : undefined;
+  const baseUrl = table && typeof table === "object"
+    ? (table as Record<string, unknown>).base_url
+    : undefined;
+  return typeof baseUrl === "string" ? baseUrl : CODEX_OWN_ENDPOINT;
+}
+
+interface ThreadRow {
+  id: string;
+  model_provider: string;
+  history_mode: string;
+}
+
+function paginatedRollout(id: string, modelProvider: string): string {
+  return JSON.stringify({
+    ordinal: 0,
+    type: "session_meta",
+    payload: { id, history_mode: "paginated", model_provider: modelProvider },
+  }) + "\n";
+}
+
+/** Seed one home: the config bytes, plus a paginated row and rollout per conversation. */
+function seedHome(
+  codexHome: string,
+  configText: string,
+  conversations: readonly { id: string; provider: string }[],
+): Map<string, string> {
+  writeFileSync(join(codexHome, "config.toml"), configText);
+  const db = new Database(join(codexHome, "state_5.sqlite"));
+  db.run("CREATE TABLE threads (id TEXT PRIMARY KEY, rollout_path TEXT, model_provider TEXT, history_mode TEXT)");
+  const rollouts = new Map<string, string>();
+  for (const conversation of conversations) {
+    const path = join(codexHome, conversation.id + ".jsonl");
+    const bytes = paginatedRollout(conversation.id, conversation.provider);
+    writeFileSync(path, bytes);
+    rollouts.set(path, bytes);
+    db.run(
+      "INSERT INTO threads VALUES (?, ?, ?, 'paginated')",
+      conversation.id,
+      path,
+      conversation.provider,
+    );
+  }
+  db.close();
+  return rollouts;
+}
+
+function readThreads(codexHome: string): ThreadRow[] {
+  const db = new Database(join(codexHome, "state_5.sqlite"), { readonly: true });
+  const rows = db
+    .query<ThreadRow, []>("SELECT id, model_provider, history_mode FROM threads ORDER BY id")
+    .all();
+  db.close();
+  return rows;
+}
+
+function readConfig(codexHome: string): Record<string, unknown> {
+  return Bun.TOML.parse(readFileSync(join(codexHome, "config.toml"), "utf8")) as Record<string, unknown>;
+}
+
+function runChild(
+  codexHome: string,
+  ocxHome: string,
+  script: string,
+  extraEnv: Record<string, string> = {},
+): { stdout: string; stderr: string; status: number } {
+  const result = spawnSync(process.execPath, ["--eval", script], {
+    cwd: repoRoot,
+    env: { ...process.env, ...extraEnv, CODEX_HOME: codexHome, CODEX_SQLITE_HOME: "", OPENCODEX_HOME: ocxHome },
+    encoding: "utf8",
+    timeout: SPAWN_BUDGET_MS - 5_000,
+  });
+  return {
+    stdout: result.stdout?.trim() ?? "",
+    stderr: result.stderr?.trim() ?? "",
+    status: result.status ?? 1,
+  };
+}
+
+const INJECT_SCRIPT = [
+  'const { injectCodexConfig } = require("./src/codex/inject");',
+  'const result = await injectCodexConfig(' + PORT + ', JSON.parse(process.env.TEST_OCX_CONFIG));',
+  "console.log(JSON.stringify(result));",
+].join("\n");
+
+const RESTORE_SCRIPT = [
+  'const { restoreNativeCodex } = require("./src/codex/inject");',
+  "console.log(JSON.stringify(restoreNativeCodex()));",
+].join("\n");
+
+/** Run a child and parse its single JSON line, reporting the child's stderr when it failed. */
+function runJson(
+  codexHome: string,
+  ocxHome: string,
+  script: string,
+  extraEnv: Record<string, string> = {},
+): Record<string, unknown> {
+  const child = runChild(codexHome, ocxHome, script, extraEnv);
+  expect(child.status, child.stderr).toBe(0);
+  return JSON.parse(child.stdout) as Record<string, unknown>;
+}
+
+describe("paginated transition destinations (#5321)", () => {
+  let codexHome: string;
+  let ocxHome: string;
+
+  beforeEach(() => {
+    codexHome = realpathSync.native(mkdtempSync(join(tmpdir(), "ocx-l4-codex-")));
+    ocxHome = realpathSync.native(mkdtempSync(join(tmpdir(), "ocx-l4-home-")));
+  });
+
+  afterEach(() => {
+    removeTreeWithRetry(codexHome);
+    removeTreeWithRetry(ocxHome);
+  });
+
+  test("enabling on a paginated openai home keeps every conversation reaching this proxy", () => {
+    const catalogPath = join(codexHome, "opencodex-catalog.json");
+    writeFileSync(catalogPath, JSON.stringify({ models: [{ slug: "vendor/routed-model" }] }));
+    const rollouts = seedHome(codexHome, 'model = "gpt-5.5"\n', [
+      { id: "already-openai", provider: "openai" },
+      { id: "already-routed", provider: "opencodex" },
+    ]);
+    const before = readThreads(codexHome);
+
+    const applied = runJson(codexHome, ocxHome, INJECT_SCRIPT, {
+      TEST_OCX_CONFIG: JSON.stringify({ codexDesktopAuthless: true }),
+    });
+    expect(applied).toMatchObject({
+      success: true,
+      historyPreflightFailureReason: HISTORY_RELABEL_STANDS_DOWN,
+    });
+
+    const config = readConfig(codexHome);
+    // Each conversation the home already had, resolved through whichever entry its own tag
+    // names. The openai-tagged one is the case #5321 was about: it is never relabeled, so the
+    // retained root override is the only thing keeping it off Codex's own endpoint.
+    for (const row of readThreads(codexHome)) {
+      expect(destinationOf(config, row.model_provider)).toBe(PROXY_BASE_URL);
+    }
+    // The conversation created next reads the root model_provider, so the id it names has to
+    // exist as a table and that table has to point here.
+    expect(config.model_provider).toBe("opencodex");
+    expect(destinationOf(config, config.model_provider as string)).toBe(PROXY_BASE_URL);
+    expect(config.model_catalog_json).toBe(catalogPath);
+    expect(existsSync(config.model_catalog_json as string)).toBe(true);
+    // Preserving those destinations may not cost a history byte or a row: the ordinals in a
+    // paginated rollout belong to Codex's own writer.
+    for (const [path, bytes] of rollouts) expect(readFileSync(path, "utf8")).toBe(bytes);
+    expect(readThreads(codexHome)).toEqual(before);
+  });
+
+  test("a root override the operator owns is neither taken over nor removed by the restore", () => {
+    const operatorUrl = "https://gateway.operator.example/v1";
+    const rollouts = seedHome(codexHome, [
+      'openai_base_url = "' + operatorUrl + '"',
+      'user_owned = "keep-me"',
+      'model = "gpt-5.5"',
+      "",
+    ].join("\n"), [{ id: "already-openai", provider: "openai" }]);
+
+    const applied = runJson(codexHome, ocxHome, INJECT_SCRIPT, {
+      TEST_OCX_CONFIG: JSON.stringify({ codexDesktopAuthless: true }),
+    });
+    expect(applied.success).toBe(true);
+
+    const written = readFileSync(join(codexHome, "config.toml"), "utf8");
+    const config = Bun.TOML.parse(written) as Record<string, unknown>;
+    // Their line, their destination. The marker that would claim the line as ours is never
+    // written above it, which is what stops a later restore from deleting their setting.
+    expect(config.openai_base_url).toBe(operatorUrl);
+    expect(written).not.toContain(OCX_ROUTING_MARKER_LINE + "\nopenai_base_url");
+    expect(destinationOf(config, "openai")).toBe(operatorUrl);
+    // The transition is still a transition: new threads reach this proxy through the table.
+    expect(destinationOf(config, config.model_provider as string)).toBe(PROXY_BASE_URL);
+
+    expect(runJson(codexHome, ocxHome, RESTORE_SCRIPT).success).toBe(true);
+    const afterRestore = readConfig(codexHome);
+    expect(afterRestore.openai_base_url).toBe(operatorUrl);
+    expect(afterRestore.user_owned).toBe("keep-me");
+    expect(afterRestore.model_provider).toBeUndefined();
+    for (const [path, bytes] of rollouts) expect(readFileSync(path, "utf8")).toBe(bytes);
+  });
+
+  test("an admission-token home is refused rather than reported as supported", () => {
+    const original = 'model = "gpt-5.5"\n';
+    const rollouts = seedHome(codexHome, original, [{ id: "already-openai", provider: "openai" }]);
+    const before = readThreads(codexHome);
+
+    const script = [
+      'const { injectCodexConfig } = require("./src/codex/inject");',
+      'const result = await injectCodexConfig(' + PORT + ', {}, { routingTarget: {',
+      '  baseUrl: "https://hub.example.test/v1",',
+      "  requiresAdmissionToken: true,",
+      '  tokenEnv: "OPENCODEX_API_AUTH_TOKEN",',
+      "} });",
+      "console.log(JSON.stringify(result));",
+    ].join("\n");
+    expect(runJson(codexHome, ocxHome, script)).toMatchObject({
+      success: false,
+      historyPreflightFailureReason: HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE,
+    });
+    // Codex's built-in openai entry carries no admission header, so there is no root override
+    // this form can own. Refusing has to mean nothing was written: a refusal reported beside a
+    // half-applied config is the state an operator cannot diagnose without reading the file.
+    expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
+    expect(existsSync(join(codexHome, "opencodex.config.toml"))).toBe(false);
+    expect(readThreads(codexHome)).toEqual(before);
+    for (const [path, bytes] of rollouts) expect(readFileSync(path, "utf8")).toBe(bytes);
+  });
+
+  test("a missing database and an unreadable manifest stay their own failure class", () => {
+    const original = 'model = "gpt-5.5"\n';
+    writeFileSync(join(codexHome, "config.toml"), original);
+    const rolloutPath = join(codexHome, "manifest-owned.jsonl");
+    writeFileSync(rolloutPath, JSON.stringify({
+      type: "session_meta",
+      payload: { id: "manifest-owned", model_provider: "openai", source: "cli" },
+    }) + "\n");
+
+    // No state database at all, and a manifest that still owns restore work. The manifest name
+    // is derived inside the child, because it binds to the path spelling the runtime resolves.
+    const script = [
+      'const fs = require("node:fs");',
+      'const { dirname, join } = require("node:path");',
+      'const { historyBackupPathFor, preflightCodexHistoryInjection } = require("./src/codex/history-provider");',
+      'const { resolveCodexStateDbPath } = require("./src/codex/paths");',
+      'const { injectCodexConfig } = require("./src/codex/inject");',
+      "const dbPath = resolveCodexStateDbPath();",
+      "const manifestPath = historyBackupPathFor(dbPath);",
+      "const manifest = JSON.parse(process.env.TEST_OCX_MANIFEST);",
+      "manifest.stateDbPath = dbPath;",
+      "fs.mkdirSync(dirname(manifestPath), { recursive: true });",
+      "fs.writeFileSync(manifestPath, JSON.stringify(manifest));",
+      "const missing = {",
+      "  preflight: preflightCodexHistoryInjection(false, true),",
+      '  inject: await injectCodexConfig(' + PORT + ', {}),',
+      "};",
+      'fs.writeFileSync(manifestPath, "{ not json");',
+      "const unreadable = {",
+      "  preflight: preflightCodexHistoryInjection(false, true),",
+      '  inject: await injectCodexConfig(' + PORT + ', {}),',
+      "};",
+      'const config = fs.readFileSync(join(process.env.CODEX_HOME, "config.toml"), "utf8");',
+      "console.log(JSON.stringify({ missing, unreadable, config, dbAbsent: !fs.existsSync(dbPath) }));",
+    ].join("\n");
+    const observed = runJson(codexHome, ocxHome, script, {
+      TEST_OCX_MANIFEST: JSON.stringify(validHistoryBackupFixture("", rolloutPath)),
+    }) as {
+      dbAbsent: boolean;
+      config: string;
+      missing: { preflight: string; inject: { success: boolean; historyPreflightFailureReason?: string } };
+      unreadable: { preflight: string; inject: { success: boolean; historyPreflightFailureReason?: string } };
+    };
+
+    expect(observed.dbAbsent).toBe(true);
+    // Neither condition may be folded into the path that completes a transition. The two
+    // stand-down reasons are the supported path; these are not, they are distinct from each
+    // other, and each one stops the injector before it writes.
+    const standDown = [HISTORY_RELABEL_STANDS_DOWN, HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE];
+    for (const observation of [observed.missing, observed.unreadable]) {
+      expect(typeof observation.preflight).toBe("string");
+      expect(standDown).not.toContain(observation.preflight);
+      expect(observation.inject.success).toBe(false);
+      expect(observation.inject.historyPreflightFailureReason).toBe(observation.preflight);
+    }
+    expect(observed.unreadable.preflight).not.toBe(observed.missing.preflight);
+    expect(observed.config).toBe(original);
+  });
+});
diff --git a/tests/codex-integration/native-claude-desktop-toggle.test.ts b/tests/codex-integration/native-claude-desktop-toggle.test.ts
index bc579cdffbf..56c28ca34da 100644
--- a/tests/codex-integration/native-claude-desktop-toggle.test.ts
+++ b/tests/codex-integration/native-claude-desktop-toggle.test.ts
@@ -14,12 +14,16 @@ let root = "";
 let library = "";
 let previousHome: string | undefined;
 let previousLibrary: string | undefined;
+let previousClaudeConfigDir: string | undefined;
 
+// These tests pin the gateway (third-party profile) path; first-party is covered by
+// tests/claude-integration/claude-desktop-first-party.test.ts.
 function config(): OcxConfig {
   return {
     port: 10100,
     providers: {},
     defaultProvider: "openai",
+    claudeCode: { desktopMode: "gateway" },
   } as OcxConfig;
 }
 
@@ -84,8 +88,10 @@ beforeEach(() => {
   library = join(root, "desktop-library");
   previousHome = process.env.OPENCODEX_HOME;
   previousLibrary = process.env.OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR;
+  previousClaudeConfigDir = process.env.CLAUDE_CONFIG_DIR;
   process.env.OPENCODEX_HOME = root;
   process.env.OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR = library;
+  process.env.CLAUDE_CONFIG_DIR = join(root, "claude");
   writeFileSync(join(root, "config.json"), JSON.stringify(config()));
 });
 
@@ -94,6 +100,8 @@ afterEach(() => {
   else process.env.OPENCODEX_HOME = previousHome;
   if (previousLibrary === undefined) delete process.env.OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR;
   else process.env.OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR = previousLibrary;
+  if (previousClaudeConfigDir === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+  else process.env.CLAUDE_CONFIG_DIR = previousClaudeConfigDir;
   removeTreeWithRetry(root);
 });
 
@@ -237,7 +245,7 @@ test("auto-apply re-reads desired state after catalog fetch and skips a concurre
     assignments: {},
     defaults: { opus: null, fable: null, sonnet: null, haiku: null },
   };
-  const persisted = { ...config(), claudeCode: { desktopProfile: profile, injectAgents: false } };
+  const persisted = { ...config(), claudeCode: { desktopMode: "gateway" as const, desktopProfile: profile, injectAgents: false } };
   writeFileSync(join(root, "config.json"), JSON.stringify(persisted));
   writeFileSync(join(root, "config.json.bak"), JSON.stringify(persisted));
   writeFileSync(join(root, "config.json"), JSON.stringify(persisted));
@@ -302,7 +310,7 @@ test("explicit enable re-reads desired state after catalog fetch and skips a con
 });
 
 test("explicit enable honors the Claude Desktop native-model opt-out", async () => {
-  const persisted = { ...config(), claudeCode: { desktopNativeModels: false } };
+  const persisted = { ...config(), claudeCode: { desktopMode: "gateway" as const, desktopNativeModels: false } };
   writeFileSync(join(root, "config.json"), JSON.stringify(persisted));
   let nativeSlugs: string[] | undefined;
 
diff --git a/tests/codex-integration/parallel-tool-calls-optin.test.ts b/tests/codex-integration/parallel-tool-calls-optin.test.ts
index 689fd207f80..d62920f9e04 100644
--- a/tests/codex-integration/parallel-tool-calls-optin.test.ts
+++ b/tests/codex-integration/parallel-tool-calls-optin.test.ts
@@ -1,8 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import { createOpenAIChatAdapter } from "../../src/adapters/openai-chat";
+import { buildOpenAIChatPassthroughRequest, createOpenAIChatAdapter } from "../../src/adapters/openai-chat";
 import { applyProviderConfigHints, normalizeRoutedCatalogEntry } from "../../src/codex/catalog";
 import { routeModel } from "../../src/router";
-import type { OcxConfig, OcxParsedRequest, OcxTool } from "../../src/types";
+import type { OcxConfig, OcxParsedRequest, OcxProviderConfig, OcxTool } from "../../src/types";
 
 const tools: OcxTool[] = [{ name: "shell", description: "run", parameters: { type: "object" } }];
 
@@ -62,6 +62,73 @@ describe("parallel tool calls provider opt-in (request body)", () => {
   });
 });
 
+/**
+ * #5211 case 2. The provider knob has three states and the call site only branched on two, so
+ * the default state — a provider that never configured it — dropped the caller's own explicit
+ * `parallel_tool_calls: false` on the way to the wire while still answering normally. The
+ * assertions read the request body because a successful tool call cannot tell the difference.
+ */
+describe("caller-specified parallel_tool_calls on a provider that expresses no preference", () => {
+  const unsetProvider: OcxProviderConfig = { adapter: "openai-chat", baseUrl: "https://gateway.example.internal/v1", apiKey: "k" };
+
+  test("an explicit request-level false reaches the outbound request", () => {
+    const adapter = createOpenAIChatAdapter(unsetProvider);
+    const body = JSON.parse(adapter.buildRequest(parsedRequest({ parallelToolCalls: false })).body) as Record<string, unknown>;
+    expect(body.parallel_tool_calls).toBe(false);
+  });
+
+  test("an explicit request-level true still omits the knob strict hosts never had to accept", () => {
+    const adapter = createOpenAIChatAdapter(unsetProvider);
+    const body = JSON.parse(adapter.buildRequest(parsedRequest({ parallelToolCalls: true })).body) as Record<string, unknown>;
+    expect(body).not.toHaveProperty("parallel_tool_calls");
+  });
+
+  test("a request that says nothing leaves the key absent", () => {
+    const adapter = createOpenAIChatAdapter(unsetProvider);
+    const body = JSON.parse(adapter.buildRequest(parsedRequest()).body) as Record<string, unknown>;
+    expect(body).not.toHaveProperty("parallel_tool_calls");
+  });
+
+  test("a toolless request never grows the key", () => {
+    const adapter = createOpenAIChatAdapter(unsetProvider);
+    const toolless = { ...parsedRequest({ parallelToolCalls: false }), context: { messages: [{ role: "user", content: "hi", timestamp: 0 }] } } as never;
+    const body = JSON.parse(adapter.buildRequest(toolless).body) as Record<string, unknown>;
+    expect(body).not.toHaveProperty("parallel_tool_calls");
+  });
+
+  // The native Chat route never projects the body, so it read the same three provider states
+  // from its own copy of the branch and lost the caller's false in exactly the same way.
+  describe("native Chat passthrough", () => {
+    function passthroughBody(provider: OcxProviderConfig, raw: Record<string, unknown>): Record<string, unknown> {
+      const request = buildOpenAIChatPassthroughRequest(provider, {
+        messages: [{ role: "user", content: "hi" }],
+        tools: [{ type: "function", function: { name: "shell", parameters: { type: "object" } } }],
+        ...raw,
+      }, "grok-4.5", false);
+      return JSON.parse(request.body) as Record<string, unknown>;
+    }
+
+    test("an explicit request-level false reaches the outbound request", () => {
+      expect(passthroughBody(unsetProvider, { parallel_tool_calls: false }).parallel_tool_calls).toBe(false);
+    });
+
+    test("an explicit true and an absent value both leave the key off", () => {
+      expect(passthroughBody(unsetProvider, { parallel_tool_calls: true })).not.toHaveProperty("parallel_tool_calls");
+      expect(passthroughBody(unsetProvider, {})).not.toHaveProperty("parallel_tool_calls");
+    });
+
+    test("the configured states keep their existing wire values", () => {
+      const optedIn = { ...unsetProvider, parallelToolCalls: true };
+      expect(passthroughBody(optedIn, {}).parallel_tool_calls).toBe(true);
+      expect(passthroughBody(optedIn, { parallel_tool_calls: false }).parallel_tool_calls).toBe(false);
+      const optedOut = { ...unsetProvider, parallelToolCalls: false };
+      expect(passthroughBody(optedOut, { parallel_tool_calls: true })).not.toHaveProperty("parallel_tool_calls");
+      expect(passthroughBody({ ...optedOut, pinParallelToolCallsFalse: true }, { parallel_tool_calls: true }).parallel_tool_calls)
+        .toBe(false);
+    });
+  });
+});
+
 describe("stale persisted config backfill (router)", () => {
   test("persisted xai config without the flag inherits registry parallelToolCalls:true", () => {
     const config: OcxConfig = {
diff --git a/tests/codex-integration/reasoning-metadata.test.ts b/tests/codex-integration/reasoning-metadata.test.ts
index 02e8d16c5ed..5c702cd71e1 100644
--- a/tests/codex-integration/reasoning-metadata.test.ts
+++ b/tests/codex-integration/reasoning-metadata.test.ts
@@ -16,6 +16,7 @@ import type { OcxProviderConfig } from "../../src/types";
 const ZEN_GO: OcxProviderConfig = {
   adapter: "openai-chat",
   baseUrl: "https://opencode.ai/zen/go/v1",
+  apiKey: "test-zen-go-key",
 } as OcxProviderConfig;
 
 const MUSE_SPARK = "muse-spark-1.3-contributor";
@@ -63,8 +64,8 @@ function metadataFileV2(providers: Record<string, unknown>, apis: Record<string,
   };
 }
 
-function supportFile(rows: Record<string, unknown>): Record<string, string> {
-  return { "reasoning-support-cache.json": JSON.stringify({ version: 1, rows }) };
+function supportFile(rows: Record<string, unknown>, version = 2): Record<string, string> {
+  return { "reasoning-support-cache.json": JSON.stringify({ version, rows }) };
 }
 
 afterEach(() => {
@@ -130,25 +131,136 @@ describe("models.dev reasoning metadata", () => {
 });
 
 describe("learned rung refusals", () => {
-  const refused = () => ({
-    ["opencode-go|" + DEEPSEEK_FLASH + "|max"]: { effort: "max", at: Date.now() },
-  });
-
   test("drops a refused rung from a metadata-derived ladder", async () => {
-    const { effort } = await load({
+    const { effort, metadata } = await load({
       ...metadataFile({ "opencode-go": { [DEEPSEEK_FLASH]: { reasoning: true, options: [{ type: "effort", values: ["low", "high", "max"] }] } } }),
-      ...supportFile(refused()),
     });
+    expect(metadata.recordUnsupportedReasoningEffort(ZEN_GO, DEEPSEEK_FLASH, "max")).toBe(true);
     expect(effort.configuredReasoningEfforts(ZEN_GO, DEEPSEEK_FLASH)).toEqual(["low", "high"]);
     expect(effort.mapReasoningEffort(ZEN_GO, DEEPSEEK_FLASH, "max")).toBe("high");
   });
 
   test("drops a refused rung from a ladder pinned in the registry too", async () => {
-    const { effort } = await load(supportFile(refused()));
+    const { effort, metadata } = await load();
+    expect(metadata.recordUnsupportedReasoningEffort(ZEN_GO, DEEPSEEK_FLASH, "max")).toBe(true);
     const pinned = { ...ZEN_GO, modelReasoningEfforts: { [DEEPSEEK_FLASH]: ["low", "high", "max"] } } as OcxProviderConfig;
     expect(effort.configuredReasoningEfforts(pinned, DEEPSEEK_FLASH)).toEqual(["low", "high"]);
   });
 
+  test("keeps learned refusals isolated between credentials at the same destination", async () => {
+    const { effort, metadata } = await load(metadataFile({
+      "opencode-go": { [DEEPSEEK_FLASH]: { reasoning: true, options: [{ type: "effort", values: ["low", "high", "max"] }] } },
+    }));
+    const lowEntitlement = { ...ZEN_GO, apiKey: "low-entitlement-key" } as OcxProviderConfig;
+    const highEntitlement = { ...ZEN_GO, apiKey: "high-entitlement-key" } as OcxProviderConfig;
+    expect(metadata.recordUnsupportedReasoningEffort(lowEntitlement, DEEPSEEK_FLASH, "max")).toBe(true);
+    expect(effort.configuredReasoningEfforts(lowEntitlement, DEEPSEEK_FLASH)).toEqual(["low", "high"]);
+    expect(effort.configuredReasoningEfforts(highEntitlement, DEEPSEEK_FLASH)).toEqual(["low", "high", "max"]);
+  });
+
+  // The catalog path carries the configured expression in apiKey; the request path carries the
+  // resolved secret in apiKey and the configured expression in _apiKeyAttempt.reference. Both
+  // must hash the same wire credential, or a refusal learned at request time never clamps the
+  // advertised ladder for env/keychain users.
+  test("a refusal learned under the resolved request key applies to the catalog's env reference", async () => {
+    const { effort, metadata } = await load(metadataFile({
+      "opencode-go": { [DEEPSEEK_FLASH]: { reasoning: true, options: [{ type: "effort", values: ["low", "high", "max"] }] } },
+    }));
+    process.env["OCX_REASONING_METADATA_TEST_KEY"] = "resolved-env-secret";
+    try {
+      const catalogSide = { ...ZEN_GO, apiKey: "${OCX_REASONING_METADATA_TEST_KEY}" } as OcxProviderConfig;
+      const requestSide = {
+        ...ZEN_GO,
+        apiKey: "resolved-env-secret",
+        _apiKeyAttempt: { reference: "${OCX_REASONING_METADATA_TEST_KEY}" },
+      } as OcxProviderConfig;
+      expect(metadata.recordUnsupportedReasoningEffort(requestSide, DEEPSEEK_FLASH, "max")).toBe(true);
+      expect(effort.configuredReasoningEfforts(catalogSide, DEEPSEEK_FLASH)).toEqual(["low", "high"]);
+    } finally {
+      delete process.env["OCX_REASONING_METADATA_TEST_KEY"];
+    }
+  });
+
+  test("a refusal learned under the catalog's env reference applies to the resolved request key", async () => {
+    const { effort, metadata } = await load(metadataFile({
+      "opencode-go": { [DEEPSEEK_FLASH]: { reasoning: true, options: [{ type: "effort", values: ["low", "high", "max"] }] } },
+    }));
+    process.env["OCX_REASONING_METADATA_TEST_KEY"] = "resolved-env-secret";
+    try {
+      const catalogSide = { ...ZEN_GO, apiKey: "${OCX_REASONING_METADATA_TEST_KEY}" } as OcxProviderConfig;
+      const requestSide = {
+        ...ZEN_GO,
+        apiKey: "resolved-env-secret",
+        _apiKeyAttempt: { reference: "${OCX_REASONING_METADATA_TEST_KEY}" },
+      } as OcxProviderConfig;
+      expect(metadata.recordUnsupportedReasoningEffort(catalogSide, DEEPSEEK_FLASH, "max")).toBe(true);
+      expect(effort.configuredReasoningEfforts(requestSide, DEEPSEEK_FLASH)).toEqual(["low", "high"]);
+    } finally {
+      delete process.env["OCX_REASONING_METADATA_TEST_KEY"];
+    }
+  });
+
+  test("a keychain-referenced key scopes refusals to the resolved secret on both paths", async () => {
+    const { effort, metadata } = await load(metadataFile({
+      "opencode-go": { [DEEPSEEK_FLASH]: { reasoning: true, options: [{ type: "effort", values: ["low", "high", "max"] }] } },
+    }));
+    const keyStore = await import("../../src/providers/api-key-resolve");
+    const store = new Map<string, string>();
+    store.set("opencodex.provider-api-key.v1 zen-go", "resolved-keychain-secret");
+    keyStore.setProviderKeychainEntryFactoryForTests((service, account) => ({
+      getPassword: () => store.get(service + " " + account) ?? null,
+      setPassword: (password) => { store.set(service + " " + account, password); },
+      deletePassword: () => store.delete(service + " " + account),
+    }));
+    try {
+      const catalogSide = { ...ZEN_GO, apiKey: "keychain:zen-go" } as OcxProviderConfig;
+      const requestSide = {
+        ...ZEN_GO,
+        apiKey: "resolved-keychain-secret",
+        _apiKeyAttempt: { reference: "keychain:zen-go" },
+      } as OcxProviderConfig;
+      expect(metadata.recordUnsupportedReasoningEffort(requestSide, DEEPSEEK_FLASH, "max")).toBe(true);
+      expect(effort.configuredReasoningEfforts(catalogSide, DEEPSEEK_FLASH)).toEqual(["low", "high"]);
+    } finally {
+      keyStore.setProviderKeychainEntryFactoryForTests(null);
+    }
+  });
+
+  // The request path must hash the credential that served the request, not a live re-read of
+  // the reference: a rotation between routing and refusal recording would otherwise bind the
+  // learned refusal to the rotated credential and leave the refused one unclamped.
+  test("a refusal learned at request time stays bound to the serving credential after rotation", async () => {
+    const { effort, metadata } = await load(metadataFile({
+      "opencode-go": { [DEEPSEEK_FLASH]: { reasoning: true, options: [{ type: "effort", values: ["low", "high", "max"] }] } },
+    }));
+    process.env["OCX_REASONING_METADATA_TEST_KEY"] = "serving-secret";
+    const requestSide = {
+      ...ZEN_GO,
+      apiKey: "serving-secret",
+      _apiKeyAttempt: { reference: "${OCX_REASONING_METADATA_TEST_KEY}" },
+    } as OcxProviderConfig;
+    // Rotate behind the stable reference after routing but before the refusal is recorded.
+    process.env["OCX_REASONING_METADATA_TEST_KEY"] = "rotated-secret";
+    try {
+      expect(metadata.recordUnsupportedReasoningEffort(requestSide, DEEPSEEK_FLASH, "max")).toBe(true);
+      const served = { ...ZEN_GO, apiKey: "serving-secret" } as OcxProviderConfig;
+      const rotated = { ...ZEN_GO, apiKey: "rotated-secret" } as OcxProviderConfig;
+      expect(effort.configuredReasoningEfforts(served, DEEPSEEK_FLASH)).toEqual(["low", "high"]);
+      expect(effort.configuredReasoningEfforts(rotated, DEEPSEEK_FLASH)).toEqual(["low", "high", "max"]);
+    } finally {
+      delete process.env["OCX_REASONING_METADATA_TEST_KEY"];
+    }
+  });
+
+  test("ignores legacy destination-wide support rows", async () => {
+    const legacyRows = { ["opencode-go|" + DEEPSEEK_FLASH + "|max"]: { effort: "max", at: Date.now() } };
+    const { effort } = await load({
+      ...metadataFile({ "opencode-go": { [DEEPSEEK_FLASH]: { reasoning: true, options: [{ type: "effort", values: ["low", "high", "max"] }] } } }),
+      ...supportFile(legacyRows, 1),
+    });
+    expect(effort.configuredReasoningEfforts(ZEN_GO, DEEPSEEK_FLASH)).toEqual(["low", "high", "max"]);
+  });
+
   test("records the refusal and plans the next lower published rung once", async () => {
     const { metadata } = await load({
       ...metadataFile({ "opencode-go": { [DEEPSEEK_FLASH]: { reasoning: true, options: [{ type: "effort", values: ["low", "high", "max"] }] } } }),
diff --git a/tests/fixtures/test-layout-expected.json b/tests/fixtures/test-layout-expected.json
index d8a39f76b8b..38e3a733c72 100644
--- a/tests/fixtures/test-layout-expected.json
+++ b/tests/fixtures/test-layout-expected.json
@@ -1,10 +1,21 @@
 {
+  "release-desktop-scripts.test.ts": "ci-workflows",
+  "installed-gate-drivers.test.ts": "ci-workflows",
+  "gui-desktop-sidecar-script.test.ts": "gui",
+  "standalone-build-script.test.ts": "gui",
+  "standalone-service.test.ts": "service",
+  "standalone.test.ts": "lib",
   "server-combo-held-response.test.ts": "server",
   "key-attribution.test.ts": "usage",
   "provider-send-path-import.test.ts": "server",
   "socks5-fetch.test.ts": "lib",
   "socks5-upload-lifecycle.test.ts": "lib",
+  "provider-egress.test.ts": "lib",
+  "provider-egress-outbound.test.ts": "providers",
+  "provider-egress-fetch.test.ts": "responses",
+  "provider-egress-management-validation.test.ts": "server",
   "start-args.test.ts": "cli",
+  "start-ownership-publication.test.ts": "cli",
   "responses-core-modules.test.ts": "responses",
   "responses-passthrough-transient-policy.test.ts": "responses",
   "responses-spend-ledger-wiring.test.ts": "responses",
@@ -13,10 +24,12 @@
   "chat-responses-control-integration.test.ts": "responses",
   "coding-agent-tool-result-images.test.ts": "adapters",
   "cold-spawn-warmup.test.ts": "ci-workflows",
+  "stepfun-provider.test.ts": "providers",
   "warmup-registration.test.ts": "ci-workflows",
   "hub-usage.test.ts": "server",
   "client-hub-usage.test.ts": "clients",
   "cli-usage-hub.test.ts": "cli",
+  "cli-companion.test.ts": "cli",
   "abort-idle-deadline.test.ts": "lib",
   "abort-race.test.ts": "adapters",
   "account-import.test.ts": "server",
@@ -123,10 +136,13 @@
   "bridge-terminal-singleness.test.ts": "adapters",
   "bridge.test.ts": "adapters",
   "buffered-response-shape-guards.test.ts": "adapters",
+  "brand-favicons.test.ts": "ci-workflows",
+  "build-desktop-icon-set.test.ts": "ci-workflows",
   "build-release-changelog.test.ts": "ci-workflows",
   "bump-dev-version.test.ts": "ci-workflows",
   "bun-runtime.test.ts": "ci-workflows",
   "bun-stream-caps.test.ts": "lib",
+  "cache-diagnostic.test.ts": "usage",
   "cancel-body-on-abort.test.ts": "server",
   "catalog-auto-refresh-scheduler.test.ts": "codex-integration",
   "catalog-cursor-search.test.ts": "codex-integration",
@@ -154,6 +170,7 @@
   "chat-inbound-reasoning-none.test.ts": "responses",
   "chat-inbound-reasoning-replay.test.ts": "responses",
   "chat-json-sse-fallback.test.ts": "responses",
+  "chat-native-developer-role.test.ts": "responses",
   "chat-native-image-normalization.test.ts": "responses",
   "chat-refusal.test.ts": "responses",
   "chat-refusal-scope.test.ts": "responses",
@@ -239,6 +256,8 @@
   "cli-ready-subprocess.test.ts": "cli",
   "cli-ready.test.ts": "cli",
   "cli-registry.test.ts": "cli",
+  "cli-resolve-subprocess.test.ts": "cli",
+  "cli-resolve.test.ts": "cli",
   "cli-restart-health.test.ts": "cli",
   "cli-restore-back.test.ts": "cli",
   "cli-start-auxiliary-bind.test.ts": "cli",
@@ -246,6 +265,7 @@
   "cli-status-hub-state.test.ts": "cli",
   "cli-status-json.test.ts": "cli",
   "cli-status-oauth-health.test.ts": "cli",
+  "cli-stop-json.test.ts": "cli",
   "cli-storage-inspect.test.ts": "cli",
   "cli-transport-honesty.test.ts": "cli",
   "cli-usage-report.test.ts": "cli",
@@ -353,6 +373,8 @@
   "codex-management-convergence.test.ts": "codex-integration",
   "codex-metadata-integrity.test.ts": "codex-integration",
   "codex-model-entitlements.test.ts": "codex-integration",
+  "codex-model-entitlement-admission.test.ts": "codex-integration",
+  "codex-routing-cache-affinity-detour.test.ts": "codex-integration",
   "codex-model-denial-evidence.test.ts": "codex-integration",
   "codex-model-availability-error.test.ts": "codex-integration",
   "codex-models-cache-invalidate.test.ts": "codex-integration",
@@ -391,8 +413,11 @@
   "codex-service-manager-probe-hardening.test.ts": "codex-integration",
   "codex-service-manager-probe.test.ts": "codex-integration",
   "codex-shim-autorestore.test.ts": "codex-integration",
+  "codex-shim-ensure-failure.test.ts": "codex-integration",
   "codex-shim-readiness.test.ts": "codex-integration",
   "codex-shim.test.ts": "codex-integration",
+  "codex-signin-lockout.test.ts": "codex-integration",
+  "server-gui-bundle-freshness.test.ts": "server",
   "codex-spark-visibility.test.ts": "codex-integration",
   "codex-sqlite-home.test.ts": "codex-integration",
   "codex-sync-api.test.ts": "codex-integration",
@@ -447,6 +472,7 @@
   "credential-redirect-guard.test.ts": "lib",
   "crusoe-provider.test.ts": "providers",
   "cursor-adapter.test.ts": "providers/cursor",
+  "cursor-roster-account-scope.test.ts": "providers/cursor",
   "cursor-continuity-retention.test.ts": "providers/cursor",
   "cursor-arg-normalize.test.ts": "providers/cursor",
   "cursor-blob-integrity.test.ts": "providers/cursor",
@@ -526,8 +552,16 @@
   "desktop-3p-removal.test.ts": "clients",
   "desktop-3p.test.ts": "clients",
   "desktop-app-restart.test.ts": "clients",
+  "desktop-cli-contracts.test.ts": "clients",
+  "desktop-exit-ownership.test.ts": "clients",
+  "desktop-install-identity.test.ts": "clients",
   "desktop-profile.test.ts": "clients",
+  "desktop-startup-surface.test.ts": "clients",
+  "desktop-tray-availability.test.ts": "clients",
+  "desktop-widget-entry.test.ts": "clients",
   "desktop-remote-store.test.ts": "clients",
+  "desktop-runtime-identity.test.ts": "clients",
+  "desktop-start-at-login-default.test.ts": "clients",
   "destination-policy-resolved.test.ts": "routing",
   "devin-adapter.test.ts": "providers",
   "devin-effort-ladder.test.ts": "providers",
@@ -633,6 +667,8 @@
   "health-scoring.test.ts": "server",
   "history-migration-guardian.test.ts": "codex-integration",
   "history-ocx-compaction-recovery.test.ts": "codex-integration",
+  "history-paginated-openai-compat.test.ts": "codex-integration",
+  "history-paginated-transition-destinations.test.ts": "codex-integration",
   "hub-gated-local-clients.test.ts": "cli",
   "hub-invite.test.ts": "cli",
   "hyperbolic-provider.test.ts": "providers",
@@ -644,11 +680,13 @@
   "injection-model-api.test.ts": "codex-integration",
   "input-admission.test.ts": "server",
   "install-scripts.test.ts": "ci-workflows",
+  "integrations-current-store.test.ts": "clients",
   "integrations-invariants.test.ts": "gui",
   "integrations-journal.test.ts": "clients",
   "integrations-merge.test.ts": "clients",
   "integrations-serialize.test.ts": "clients",
   "integrations-state.test.ts": "clients",
+  "integrations-superseded-store.test.ts": "clients",
   "integrations-writer-frozen-config.test.ts": "clients",
   "integrations-writer.test.ts": "clients",
   "interactive-confirm.test.ts": "cli",
@@ -838,11 +876,13 @@
   "oauth-first-add-hint.test.ts": "gui",
   "oauth-health.test.ts": "oauth",
   "oauth-log.test.ts": "oauth",
+  "oauth-login-cli-browser-launch.test.ts": "oauth",
   "oauth-login-cli-live-update.test.ts": "oauth",
   "oauth-login-open-browser.test.ts": "oauth",
   "oauth-login-summary.test.ts": "oauth",
   "oauth-manual-code.test.ts": "oauth",
   "oauth-open-browser-choice.test.ts": "oauth",
+  "oauth-open-url-result.test.ts": "oauth",
   "oauth-provider-reconcile.test.ts": "oauth",
   "oauth-public-surface.test.ts": "oauth",
   "oauth-reauth-bind.test.ts": "oauth",
@@ -878,6 +918,7 @@
   "openai-chat-native-policy.test.ts": "adapters/openai",
   "openai-chat-parallel-stream.test.ts": "adapters/openai",
   "openai-chat-path-override.test.ts": "adapters/openai",
+  "openai-chat-reasoning-wire-policy.test.ts": "adapters/openai",
   "openai-chat-system-order.test.ts": "adapters/openai",
   "openai-chat-tool-result-images.test.ts": "adapters/openai",
   "openai-chat-url.test.ts": "adapters/openai",
@@ -888,6 +929,7 @@
   "openai-provider-option-tooling.test.ts": "adapters/openai",
   "openai-provider-option.test.ts": "adapters/openai",
   "openai-responses-passthrough.test.ts": "responses",
+  "opaque-blob-wrapped-rejection.test.ts": "responses",
   "opencode-cli.test.ts": "providers",
   "opencode-management-transport.test.ts": "providers",
   "opencode-free-provider.test.ts": "providers",
@@ -930,6 +972,7 @@
   "ports.test.ts": "server",
   "prime-client.test.ts": "clients",
   "privacy-mask-account.test.ts": "lib",
+  "privacy-scan-asset-names.test.ts": "ci-workflows",
   "privacy-scan-meta-key.test.ts": "ci-workflows",
   "privacy-scan-ssh-endpoint.test.ts": "ci-workflows",
   "probe-lease.test.ts": "routing",
@@ -993,6 +1036,8 @@
   "reasoning-replay-robustness.test.ts": "adapters",
   "reasoning-replay-scope-source.test.ts": "lib",
   "redact.test.ts": "lib",
+  "failure-stage-model.test.ts": "lib",
+  "failure-attribution.test.ts": "lib",
   "relay-eager.test.ts": "server",
   "release-helper.test.ts": "ci-workflows",
   "release-notes.test.ts": "ci-workflows",
@@ -1023,6 +1068,7 @@
   "remote-workspace-protocol.test.ts": "clients",
   "remote-workspace-rpc-framing.test.ts": "clients",
   "remove-tree-helper.test.ts": "lib",
+  "replay-refusal-parity.test.ts": "server",
   "repo-hygiene.test.ts": "ci-workflows",
   "request-decompress.test.ts": "usage",
   "request-evidence.test.ts": "usage",
@@ -1030,6 +1076,11 @@
   "request-log-conversation.test.ts": "usage",
   "request-log-estimate-cap.test.ts": "usage",
   "request-log.test.ts": "usage",
+  "request-outcome-agreement.test.ts": "usage",
+  "usage-failure-fingerprint.test.ts": "usage",
+  "usage-failure-projection.test.ts": "usage",
+  "usage-attempt-delivery.test.ts": "usage",
+  "usage-ledger-retention.test.ts": "usage",
   "request-pacing.test.ts": "usage",
   "reserve-auth-context.test.ts": "codex-integration",
   "reserve-availability.test.ts": "codex-integration",
@@ -1090,6 +1141,7 @@
   "responses-show-thinking-summary.test.ts": "responses",
   "responses-snapshot-repair-server.test.ts": "responses",
   "responses-snapshot-repair.test.ts": "responses",
+  "responses-sparse-terminal-tool-scope.test.ts": "responses",
   "responses-spill-shutdown-clock.test.ts": "responses",
   "responses-state-write-amplification.test.ts": "responses",
   "responses-state.test.ts": "responses",
@@ -1157,6 +1209,9 @@
   "server-xai-header-parity.test.ts": "server",
   "server-xai-oauth-401-replay.test.ts": "server",
   "server-xai-responses-streaming.test.ts": "server",
+  "service-ownership-compatibility.test.ts": "service",
+  "service-ownership-handover.test.ts": "service",
+  "service-ownership-state.test.ts": "service",
   "service-probe-docker.test.ts": "service",
   "service-secrets.test.ts": "service",
   "service-sqlite-home.test.ts": "service",
@@ -1260,6 +1315,7 @@
   "umans-provider.test.ts": "providers",
   "uninstall.test.ts": "cli",
   "update-badge.test.ts": "update",
+  "update-desktop-owner.test.ts": "update",
   "update-job.test.ts": "update",
   "update-notify.test.ts": "update",
   "update-npm-cache-preflight.test.ts": "update",
@@ -1350,6 +1406,7 @@
   "ws-upstream.test.ts": "responses",
   "ws-upstream-socks5.test.ts": "responses",
   "xai-client.test.ts": "images",
+  "xai-empty-catalog-tool-choice.test.ts": "providers/xai",
   "xai-oauth-retry.test.ts": "providers/xai",
   "xai-refresh-lock.test.ts": "providers/xai",
   "xai-responses-adjacency.test.ts": "providers/xai",
@@ -1398,5 +1455,34 @@
   "gui-codex-usage-score-parity.test.ts": "gui",
   "web-search-sidecar-429.test.ts": "web-search",
   "codex-shim-destroyed-probe.test.ts": "codex-integration",
-  "client-runtime.test.ts": "clients"
+  "client-runtime.test.ts": "clients",
+  "usage-timeline.test.ts": "usage",
+  "companion-settings.test.ts": "server",
+  "chat-tool-choice-allowed-tools.test.ts": "responses",
+  "anthropic-tool-declaration-constraints.test.ts": "adapters/anthropic",
+  "google-strict-tool-validated-mode.test.ts": "adapters/google",
+  "openai-chat-developer-position.test.ts": "adapters/openai",
+  "chat-inline-document-bytes.test.ts": "responses",
+  "devin-output-budget.test.ts": "providers",
+  "api-key-model-scope.test.ts": "server",
+  "docs-provider-discovery-limits.test.ts": "ci-workflows",
+  "api-key-scope-images.test.ts": "server",
+  "api-key-scope-audio.test.ts": "server",
+  "api-key-scope-live.test.ts": "server",
+  "api-key-scope-alpha-search.test.ts": "server",
+  "claude-intercept-local-ca.test.ts": "claude-integration",
+  "claude-intercept-proxy.test.ts": "claude-integration",
+  "claude-intercept-settings.test.ts": "claude-integration",
+  "claude-desktop-first-party.test.ts": "claude-integration",
+  "claude-desktop-mode-explanation.test.ts": "claude-integration",
+  "claude-intercept-integration.test.ts": "server",
+  "management-provider-reset-replay.test.ts": "server",
+  "responses-reset-replay.test.ts": "responses",
+  "ambiguous-resend-gate.test.ts": "lib",
+  "docs-developer-role-policy.test.ts": "ci-workflows",
+  "ambiguous-resend-composition.test.ts": "lib",
+  "chat-inbound-developer-position.test.ts": "responses",
+  "release-pipeline-contract.test.ts": "ci-workflows",
+  "desktop-proxy-direct-transport.test.ts": "clients",
+  "platform-dialog-guard.test.ts": "gui"
 }
diff --git a/tests/gui/gui-desktop-sidecar-script.test.ts b/tests/gui/gui-desktop-sidecar-script.test.ts
new file mode 100644
index 00000000000..413e155f566
--- /dev/null
+++ b/tests/gui/gui-desktop-sidecar-script.test.ts
@@ -0,0 +1,18 @@
+import { expect, test } from "bun:test";
+import { repoPath } from "../helpers/repo-root";
+
+const script = await Bun.file(repoPath("desktop", "scripts", "prepare-sidecar.ts")).text();
+
+test("desktop sidecar preparation maps supported Rust targets", () => {
+  for (const value of [
+    "aarch64-apple-darwin",
+    "x86_64-apple-darwin",
+    "x86_64-pc-windows-msvc",
+    "x86_64-unknown-linux-gnu",
+    "aarch64-unknown-linux-gnu",
+  ]) expect(script).toContain(value);
+  expect(script).toContain("build:standalone");
+  expect(script).toContain("binaries");
+  expect(script).toContain("resources");
+  expect(script).toContain("ocx-${triple}");
+});
diff --git a/tests/gui/gui-static.test.ts b/tests/gui/gui-static.test.ts
index 43c8c1887e9..b8808f9af7d 100644
--- a/tests/gui/gui-static.test.ts
+++ b/tests/gui/gui-static.test.ts
@@ -6,11 +6,24 @@ import { serveGuiFile } from "../../src/server/gui-static";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
 
 const temporaryDirectories: string[] = [];
+const previousGuiDist = process.env.OPENCODEX_GUI_DIST;
 
 afterEach(() => {
   for (const directory of temporaryDirectories.splice(0)) {
     removeTreeWithRetry(directory);
   }
+  if (previousGuiDist === undefined) delete process.env.OPENCODEX_GUI_DIST;
+  else process.env.OPENCODEX_GUI_DIST = previousGuiDist;
+});
+
+test("serves the dashboard from OPENCODEX_GUI_DIST when no explicit root is supplied", async () => {
+  const guiDist = mkdtempSync(join(tmpdir(), "ocx-gui-static-override-"));
+  temporaryDirectories.push(guiDist);
+  writeFileSync(join(guiDist, "index.html"), "<!doctype html><title>standalone</title>");
+  process.env.OPENCODEX_GUI_DIST = guiDist;
+  const response = serveGuiFile("/");
+  expect(response).not.toBeNull();
+  expect(await response!.text()).toContain("standalone");
 });
 
 test("#2792 snapshots a static asset before server framing can outlive the file", async () => {
diff --git a/tests/gui/integrations-invariants.test.ts b/tests/gui/integrations-invariants.test.ts
index 78e0d20f2c8..eb7ee32ae56 100644
--- a/tests/gui/integrations-invariants.test.ts
+++ b/tests/gui/integrations-invariants.test.ts
@@ -7,6 +7,12 @@ import { createClineIO } from "../../src/integrations/cline-io";
 import { parseClineDocument } from "../../src/integrations/cline-document";
 import { parseConfig } from "../../src/integrations/config-io";
 import { INTEGRATION_CLIENTS, INTEGRATION_CLIENT_IDS, type IntegrationClientId } from "../../src/integrations/registry";
+import {
+  MANAGED_PATH_TEMPLATES,
+  PLAN_UNBOUND_FINGERPRINT,
+  orderPlanChanges,
+  previewIntegration,
+} from "../../src/integrations/mutation-plan";
 import { createIntegrationStateStore, type IntegrationStateStore } from "../../src/integrations/store";
 import { readIntegrationState, readPath } from "../../src/integrations/state";
 import { applyIntegration, disableIntegration, restoreIntegration } from "../../src/integrations/writer";
@@ -111,6 +117,92 @@ describe("the client registries cannot drift apart", () => {
     expect(routedFileClients).toEqual(expected);
   });
 
+  test("a plan the server produces is one the dashboard accepts", async () => {
+    const guiIntegrations = await import("../../gui/src/pages/integrations/integration-api");
+    installClient("zcode");
+    const input = { clientId: "zcode" as const, models: MODELS, config: CONFIG, port: 10100, env: TEST_ENV, home, store };
+
+    /*
+     * The parser re-declares the plan vocabulary by hand for the same reason
+     * the client list above is re-declared: it cannot import the backend. So
+     * the token format and the refusal names are two more hand-maintained
+     * copies, and nothing but a real plan crossing the boundary catches one of
+     * them going stale. It has: a fingerprint version bump once became a
+     * client-side rejection of every preview, silently, because the parser
+     * matched the previous version as a literal.
+     */
+    const applied = previewIntegration(input, { operation: "apply" });
+    expect(guiIntegrations.parseIntegrationMutationPlan(JSON.parse(JSON.stringify(applied)))).toMatchObject({
+      clientId: "zcode",
+      fingerprint: applied.fingerprint,
+    });
+
+    // And a refusal, so the reason vocabulary crosses too rather than only the
+    // shape of a plan that can apply.
+    const storePath = INTEGRATION_CLIENTS.zcode.currentStore!.path(TEST_ENV, home);
+    mkdirSync(dirname(storePath), { recursive: true });
+    writeFileSync(storePath, "{}\n");
+    const refused = previewIntegration(input, { operation: "apply" });
+    expect(refused.canApply).toBe(false);
+    const parsed = guiIntegrations.parseIntegrationMutationPlan(JSON.parse(JSON.stringify(refused)));
+    expect(parsed.refusalReason).toBe(refused.refusalReason);
+
+    /*
+     * The mutation itself, shaped as the route sends it. A reason missing from
+     * the parser's own set is not recognised as a refusal at all, so the user
+     * would see a bare server error instead of the sentence that names the file
+     * their client actually reads.
+     */
+    const mutation = applyIntegration(input);
+    expect(mutation.ok).toBe(false);
+    if (mutation.ok) return;
+    expect(guiIntegrations.isIntegrationRefusalEnvelope({
+      error: "integration mutation failed",
+      code: "integration_mutation_failed",
+      clientId: mutation.clientId,
+      state: mutation.state,
+      reason: mutation.reason,
+      message: mutation.message,
+    })).toBe(true);
+  });
+
+  test("every managed path the server can publish is one the dashboard accepts", async () => {
+    const guiIntegrations = await import("../../gui/src/pages/integrations/integration-api");
+    /*
+     * The parser keeps its own set of managed schema paths, by hand, for the
+     * same reason it keeps its own client list. A template the server can put in
+     * a plan and the parser has never heard of is not a cosmetic mismatch: the
+     * dashboard answers `invalid_integration_preview_response` and the page
+     * shows nothing. Crossing every template rather than one plan is what makes
+     * a client that writes a second file visible here the day it is added.
+     */
+    for (const clientId of INTEGRATION_CLIENT_IDS) {
+      const changes = orderPlanChanges(MANAGED_PATH_TEMPLATES[clientId].map(template => ({
+        kind: "add" as const,
+        path: template.join("."),
+      })));
+      expect(changes.length, clientId).toBe(MANAGED_PATH_TEMPLATES[clientId].length);
+      const parsed = guiIntegrations.parseIntegrationMutationPlan({
+        version: 1,
+        clientId,
+        operation: "apply",
+        state: "absent",
+        foreignEdit: "none",
+        changes: changes.map(change => ({ ...change })),
+        // A plan that carries changes and could apply is bound by definition, so the
+        // sentinel cannot stand in for it here: the parser refuses an unbound
+        // fingerprint beside `canApply`, and that refusal is the contract, not the
+        // thing under test. The version prefix is taken from the sentinel so a
+        // version bump moves this fixture with it.
+        fingerprint: `${PLAN_UNBOUND_FINGERPRINT.split(":")[0]}:${"0".repeat(32)}`,
+        canApply: true,
+        willChange: true,
+      });
+      expect(parsed.changes.map(change => change.path), clientId)
+        .toEqual(changes.map(change => change.path));
+    }
+  });
+
   test("source preservation and cross-process locking are registry capabilities", () => {
     expect(INTEGRATION_CLIENTS.omp.sourcePreservingYaml?.path).toEqual(["providers", "opencodex"]);
     expect(INTEGRATION_CLIENTS.hermes.sourcePreservingYaml?.path).toEqual(["providers", "opencodex"]);
diff --git a/tests/gui/platform-dialog-guard.test.ts b/tests/gui/platform-dialog-guard.test.ts
new file mode 100644
index 00000000000..c7aa293c0f7
--- /dev/null
+++ b/tests/gui/platform-dialog-guard.test.ts
@@ -0,0 +1,161 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { findPlatformDialogCalls } from "../helpers/platform-dialog-scan";
+import { repoPath, repoRoot } from "../helpers/repo-root";
+
+/**
+ * The dashboard must not call `confirm`, `alert` or `prompt`.
+ *
+ * Inside the desktop app those three draw nothing: wry implements no `WKUIDelegate`
+ * JavaScript panel methods, so WKWebView suppresses the panel entirely. Thirteen consent
+ * gates and seven result reports were inoperative there — including the sidebar stop and
+ * refresh orbs — while the same dashboard worked in a browser.
+ * See devlog/_plan/260921_app_runtime_ownership/050_webview_dialogs.md.
+ *
+ * CI could not have caught the original defect because the GUI tests encoded browser
+ * dialogs as available: they stubbed `confirm()` to true and `alert()` to a no-op. A
+ * regression test for this has to assert the ABSENCE of the platform dialogs, which is what
+ * this file does for the source and what gui/tests/action-dialogs.test.ts does at runtime.
+ */
+function dashboardSources(): string[] {
+  return execFileSync("git", ["ls-files", "gui/src"], { cwd: repoRoot(), encoding: "utf8" })
+    .split("\n")
+    .filter(file => file.endsWith(".ts") || file.endsWith(".tsx"));
+}
+
+describe("dashboard platform-dialog guard", () => {
+  test("no dashboard source calls confirm, alert or prompt", () => {
+    const files = dashboardSources();
+    // A scan that found nothing because it read nothing would pass silently.
+    expect(files.length).toBeGreaterThan(200);
+
+    const offenders: string[] = [];
+    for (const file of files) {
+      for (const call of findPlatformDialogCalls(readFileSync(repoPath(file), "utf8"))) {
+        offenders.push(`${file}:${call.line} ${call.form}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  test("the guard reports every global call form", () => {
+    const reported = (source: string) => findPlatformDialogCalls(source).map(call => call.form);
+
+    expect(reported("if (!confirm(message)) return;")).toEqual(["confirm("]);
+    expect(reported("alert(outcome.message);")).toEqual(["alert("]);
+    expect(reported("const entered = window.prompt(label, current);")).toEqual(["window.prompt("]);
+    expect(reported("window.confirm(question)")).toEqual(["window.confirm("]);
+    expect(reported("globalThis.alert(text)")).toEqual(["globalThis.alert("]);
+    expect(reported("self.confirm(question)")).toEqual(["self.confirm("]);
+    // Whitespace and optional chaining are the same call.
+    expect(reported("window ?. confirm ( question )")).toEqual(["window?.confirm("]);
+    // Call position after a keyword is still a call.
+    expect(reported("return confirm(question);")).toEqual(["confirm("]);
+    expect(reported("const answer = await confirm(question);")).toEqual(["confirm("]);
+    expect(reported("void alert(message);")).toEqual(["alert("]);
+  });
+
+  test("the guard leaves the legitimate shapes alone", () => {
+    // A confirm() method on a session object.
+    expect(findPlatformDialogCalls("await session.confirm();")).toEqual([]);
+    expect(findPlatformDialogCalls("class S {\n  async confirm(): Promise<void> {}\n}")).toEqual([]);
+    // The admin-token helper, whose name merely contains one of the words.
+    expect(findPlatformDialogCalls("const token = await promptForAdminToken(verify);")).toEqual([]);
+    // An executable sample string that contains the word.
+    expect(findPlatformDialogCalls("const sample = `const key = prompt(label);`;")).toEqual([]);
+    expect(findPlatformDialogCalls('const sample = "confirm(question)";')).toEqual([]);
+    expect(findPlatformDialogCalls("// the refresh orb used to call confirm(message)")).toEqual([]);
+    expect(findPlatformDialogCalls("/* alert(message) drew nothing */")).toEqual([]);
+    // A property named for one of them, and a regular expression that mentions one.
+    expect(findPlatformDialogCalls("const request = { confirm: true, prompt: text };")).toEqual([]);
+    expect(findPlatformDialogCalls("const pattern = /confirm\\(/;")).toEqual([]);
+  });
+
+  test("code inside a template hole is still code", () => {
+    // The mask must not swallow an interpolation: that is how a scanner stops reporting.
+    expect(findPlatformDialogCalls("const url = `${confirm(question)}`;").map(c => c.form)).toEqual(["confirm("]);
+    expect(findPlatformDialogCalls("const url = `/api/${id}`; alert(done);").map(c => c.form)).toEqual(["alert("]);
+  });
+
+  /*
+   * A template literal is two different things at once, and the difference decides whether a
+   * dialog can come back. Its TEXT is prose — the dashboard ships an executable sample that
+   * spells out a prompt call on purpose — while a hole is executable code. Skipping backtick
+   * strings wholesale would make the second invisible.
+   */
+  test("a template hole is code even when the call names a global receiver", () => {
+    const reported = (source: string) => findPlatformDialogCalls(source).map(call => call.form);
+
+    expect(reported('const message = `${window.confirm("continue?")}`;')).toEqual(["window.confirm("]);
+    expect(reported("const n = `${globalThis.alert(message)}`;")).toEqual(["globalThis.alert("]);
+    // The surrounding text of the same literal stays prose.
+    expect(reported('const doc = `Call window.confirm("continue?") in a browser.`;')).toEqual([]);
+    expect(reported("const sample = `const key = prompt(label);`;")).toEqual([]);
+  });
+
+  test("a regular expression holding a quote does not mask the rest of the file", () => {
+    // An unmasked /['"]/ reads as the start of a string literal and hides everything after
+    // it, which would turn this guard green by blinding it.
+    const source = "const quoted = /['\"]/;\nalert(message);";
+    expect(findPlatformDialogCalls(source).map(call => call.form)).toEqual(["alert("]);
+  });
+
+  /*
+   * Shapes an earlier revision of the scanner missed. Each one is a way of writing or
+   * neighbouring a real global call that the lexer or the call pattern failed to see, and a
+   * missed call is the failure mode that matters: a false positive is loud, a false
+   * negative is a guard that has quietly stopped guarding.
+   */
+  test("the guard is not blinded by neighbouring syntax", () => {
+    const reported = (source: string) => findPlatformDialogCalls(source).map(call => call.form);
+
+    // A JSX closing tag is not a regular expression, and an apostrophe in JSX body text is
+    // not a string. Either reading masked the rest of the line.
+    expect(reported("const view = <div>don't</div>; alert(message);")).toEqual(["alert("]);
+    // A newline says nothing about whether the next slash divides.
+    expect(reported("const ratio = numerator\n/ alert(message);")).toEqual(["alert("]);
+    // A slash inside a character class does not close the pattern.
+    expect(reported("function f() { return /['/]/; } alert(message);")).toEqual(["alert("]);
+    // An arrow's => still opens a regular expression, so this one stays masked.
+    expect(reported("const f = x => /confirm\\(/.test(x);")).toEqual([]);
+  });
+
+  test("the guard reads the less obvious call spellings", () => {
+    const reported = (source: string) => findPlatformDialogCalls(source).map(call => call.form);
+
+    expect(reported("confirm?.(question);")).toEqual(["confirm?.("]);
+    // The match starts at the name, so the wrapping parenthesis is not part of the form.
+    expect(reported("(confirm)(question);")).toEqual(["confirm)("]);
+    // A line continuation keeps the string open; the call after it is still code.
+    expect(reported('const s = "continued\\\r\ntext"; alert(message);')).toEqual(["alert("]);
+  });
+
+  /*
+   * Shapes a static review demonstrated the scanner missed. Every one is a real call that
+   * reaches the undrawable platform dialog, so each was a hole in the barrier rather than a
+   * stylistic gap.
+   */
+  test("the guard reads optional, wrapped and computed calls on a global receiver", () => {
+    const reported = (source: string) => findPlatformDialogCalls(source).map(call => call.form);
+
+    expect(reported('window.confirm?.("continue?");')).toEqual(["window.confirm?.("]);
+    expect(reported('(window.confirm)("continue?");')).toEqual(["window.confirm)("]);
+    expect(reported('((confirm))("continue?");')).toEqual(["confirm))("]);
+    // Quotes are what make computed access work, so it is matched before masking.
+    expect(reported('globalThis["alert"](message);')).toEqual(['globalThis["alert"](']);
+  });
+
+  test("a statement start is a call position whatever ended the previous line", () => {
+    const reported = (source: string) => findPlatformDialogCalls(source).map(call => call.form);
+
+    // Automatic semicolon insertion: `ready` ends its own statement, so this is a call and
+    // not a declaration the preceding word introduced.
+    expect(reported("ready\nalert(message);")).toEqual(["alert("]);
+    expect(reported('export default prompt("name");')).toEqual(["prompt("]);
+    // Postfix increment makes the next slash a division, not a regular expression.
+    expect(reported("const n = count++ / alert(message) / 2;")).toEqual(["alert("]);
+    // The declaration forms must still be left alone.
+    expect(reported("class S {\n  async confirm(): Promise<void> {}\n}")).toEqual([]);
+  });
+});
diff --git a/tests/gui/standalone-build-script.test.ts b/tests/gui/standalone-build-script.test.ts
new file mode 100644
index 00000000000..7dab243ae2e
--- /dev/null
+++ b/tests/gui/standalone-build-script.test.ts
@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test";
+import { repoPath } from "../helpers/repo-root";
+
+const script = await Bun.file(repoPath("scripts", "build-standalone.ts")).text();
+const targets = await Bun.file(repoPath("scripts", "standalone-targets.ts")).text();
+
+test("standalone build script exposes supported targets and packaging contract", () => {
+  // The target list lives in the shared module the release verifier also reads;
+  // the build script consumes it rather than restating it.
+  expect(script).toContain("./standalone-targets");
+  for (const target of [
+    "bun-darwin-arm64",
+    "bun-darwin-x64",
+    "bun-windows-x64",
+    "bun-linux-x64",
+    "bun-linux-arm64",
+  ]) expect(targets).toContain(target);
+  expect(script).toContain("--compile");
+  expect(script).toContain("--outfile");
+  expect(script).toContain("gui/dist");
+  expect(script).toContain("SHA256SUMS");
+});
diff --git a/tests/helpers/platform-dialog-scan.ts b/tests/helpers/platform-dialog-scan.ts
new file mode 100644
index 00000000000..f07dc6ea628
--- /dev/null
+++ b/tests/helpers/platform-dialog-scan.ts
@@ -0,0 +1,278 @@
+/**
+ * Finds calls to the three JavaScript platform dialogs the desktop app cannot draw.
+ *
+ * wry implements no `WKUIDelegate` JavaScript panel methods, so inside the app
+ * `confirm()` returns false without drawing anything, `alert()` draws nothing, and
+ * `prompt()` cannot collect input. The dashboard has replaced all three with in-page
+ * dialogs; this is what stops them coming back.
+ *
+ * The rule is the CALL FORM, not the identifier, because the identifier is legitimate in
+ * several places this repository actually uses: a `confirm()` method on a session object,
+ * the `promptForAdminToken` helper, a `confirm` prop, and an executable sample string that
+ * contains the word. Banning the word would reject all four; banning the call form rejects
+ * only what cannot work.
+ */
+
+export interface PlatformDialogCall {
+  /** 1-based, so it pastes straight into an editor. */
+  line: number;
+  /** The matched text with whitespace removed, e.g. `window.confirm(` or `alert(`. */
+  form: string;
+}
+
+const DIALOGS = ["confirm", "alert", "prompt"] as const;
+
+/** Receivers that reach the same undrawable platform dialog as a bare call. */
+const GLOBAL_RECEIVERS = ["window", "globalThis", "self", "top", "parent"] as const;
+
+/**
+ * Keywords after which an identifier is being CALLED. Anything else immediately before the
+ * name means it is being declared or named — `async confirm()` is a method declaration,
+ * `await confirm()` is a call — so an unrecognised preceding word is allowed rather than
+ * reported.
+ */
+const CALL_POSITION_KEYWORDS = new Set([
+  "return", "await", "void", "typeof", "delete", "yield", "new",
+  "case", "in", "of", "do", "else", "throw", "default", "export",
+]);
+
+/**
+ * A `/` after one of these punctuation marks opens a regular expression rather than dividing.
+ *
+ * `<` and `>` are deliberately absent. A JSX closing tag is spelled `</div>`, so treating
+ * `/` after `<` as a regular expression masked everything between that tag and the end of
+ * the line — which in dense JSX is exactly where a handler calling a dialog would sit. The
+ * one case worth keeping is the arrow function `=> /pattern/`, handled by looking at the
+ * character before the `>`.
+ */
+const REGEX_PRECEDING_PUNCTUATION = new Set([
+  "(", ",", "=", ":", "[", "!", "&", "|", "?", "{", "}", ";", "+", "-", "*", "%", "~", "^",
+]);
+
+/**
+ * Words after which a quote opens a string literal and a slash opens a regular expression.
+ *
+ * The distinction matters because JSX body text is not a string: in `<div>don't</div>` the
+ * apostrophe follows the word `don`, and treating it as a quote would mask the rest of the
+ * line — including a platform-dialog call sitting on it. A word that is not a keyword
+ * therefore means "prose", and the scanner declines to mask.
+ *
+ * A word missing from this set fails SAFE: the text is left unmasked, so at worst its
+ * contents are reported as a call that has to be looked at, rather than a real call going
+ * unreported.
+ */
+const VALUE_PRECEDING_KEYWORDS = new Set([
+  "return", "typeof", "case", "in", "of", "do", "else", "void", "await", "yield", "new",
+  "delete", "throw", "instanceof", "from", "import", "export", "default", "as", "extends",
+  "satisfies", "keyof", "readonly", "let", "const", "var",
+]);
+
+function isIdentifierChar(character: string): boolean {
+  return /[A-Za-z0-9_$]/.test(character);
+}
+
+/**
+ * Replaces comment, string, template-text and regular-expression characters with spaces,
+ * keeping every newline so line numbers survive.
+ *
+ * Template interpolations are deliberately NOT masked: `${confirm(x)}` is executable code
+ * and has to stay visible. Regular expressions are masked for the opposite reason — an
+ * unmasked `/['"]/` would look like the start of a string literal and silently swallow the
+ * rest of the file, which is how a scanner quietly stops reporting anything at all.
+ */
+export function maskNonCode(source: string): string {
+  const out = source.split("");
+  const blank = (from: number, to: number): void => {
+    for (let i = from; i < to && i < out.length; i += 1) {
+      if (out[i] !== "\n") out[i] = " ";
+    }
+  };
+
+  /** Masks template text from `start`, stopping after a hole or the closing backtick. */
+  const maskTemplateText = (start: number): number => {
+    let cursor = start;
+    while (cursor < source.length) {
+      const current = source[cursor];
+      if (current === "\\") { blank(cursor, cursor + 2); cursor += 2; continue; }
+      if (current === "`") { out[cursor] = " "; templates.pop(); return cursor + 1; }
+      if (current === "$" && source[cursor + 1] === "{") { blank(cursor, cursor + 2); return cursor + 2; }
+      if (current !== "\n") out[cursor] = " ";
+      cursor += 1;
+    }
+    return cursor;
+  };
+
+  /**
+   * The last significant token. A word carries its text so a keyword can be told from an
+   * ordinary identifier; punctuation carries the character. It deliberately survives line
+   * breaks — a newline says nothing about whether the next `/` divides or opens a regular
+   * expression, and resetting on one made `numerator\n/ alert(x)` read as a regex and mask
+   * the call.
+   */
+  let previousWord = "";
+  let previousPunctuation = "";
+  /** The punctuation before that, so `=>` can be told from a bare `>`. */
+  let punctuationBefore = "";
+  const opensValue = (): boolean => {
+    if (previousWord) return VALUE_PRECEDING_KEYWORDS.has(previousWord);
+    if (previousPunctuation === ">") return punctuationBefore === "=";
+    // `count++ / x` divides. Reading that slash as a regular expression masked the rest of
+    // the line, which is where the call would be.
+    if (previousPunctuation === "+" || previousPunctuation === "-") {
+      if (punctuationBefore === previousPunctuation) return false;
+    }
+    return previousPunctuation === "" || REGEX_PRECEDING_PUNCTUATION.has(previousPunctuation);
+  };
+  const noteValue = (): void => { previousWord = ""; punctuationBefore = ""; previousPunctuation = "x"; };
+  /** Open template literals, each counting the brace depth of the hole it is inside. */
+  const templates: number[] = [];
+  let index = 0;
+
+  while (index < source.length) {
+    const character = source[index];
+    const next = source[index + 1];
+
+    if (character === "/" && next === "/") {
+      const end = source.indexOf("\n", index);
+      const stop = end === -1 ? source.length : end;
+      blank(index, stop);
+      index = stop;
+      continue;
+    }
+    if (character === "/" && next === "*") {
+      const end = source.indexOf("*/", index + 2);
+      const stop = end === -1 ? source.length : end + 2;
+      blank(index, stop);
+      index = stop;
+      continue;
+    }
+    // A quote after an ordinary word is prose, not a string opener: `don't` inside JSX.
+    if ((character === "'" || character === '"') && opensValue()) {
+      let cursor = index + 1;
+      while (cursor < source.length && source[cursor] !== character) {
+        // A line continuation keeps the string open, including the CRLF spelling.
+        if (source[cursor] === "\\") cursor += source[cursor + 1] === "\r" && source[cursor + 2] === "\n" ? 2 : 1;
+        else if (source[cursor] === "\n") break;
+        cursor += 1;
+      }
+      blank(index, cursor + 1);
+      noteValue();
+      index = cursor + 1;
+      continue;
+    }
+    if (character === "/" && opensValue()) {
+      let cursor = index + 1;
+      let inClass = false;
+      while (cursor < source.length) {
+        const current = source[cursor];
+        if (current === "\\") { cursor += 2; continue; }
+        if (current === "\n") break;
+        if (current === "[") inClass = true;
+        else if (current === "]") inClass = false;
+        else if (current === "/" && !inClass) break;
+        cursor += 1;
+      }
+      blank(index, cursor + 1);
+      noteValue();
+      index = cursor + 1;
+      continue;
+    }
+    if (character === "`") {
+      templates.push(0);
+      out[index] = " ";
+      index = maskTemplateText(index + 1);
+      noteValue();
+      continue;
+    }
+    if (templates.length > 0 && character === "{") {
+      templates[templates.length - 1] += 1;
+    } else if (templates.length > 0 && character === "}") {
+      if (templates[templates.length - 1] === 0) {
+        out[index] = " ";
+        index = maskTemplateText(index + 1);
+        noteValue();
+        continue;
+      }
+      templates[templates.length - 1] -= 1;
+    }
+    if (isIdentifierChar(character)) {
+      previousWord += character;
+      previousPunctuation = "";
+      punctuationBefore = "";
+    } else if (!/\s/.test(character)) {
+      previousWord = "";
+      punctuationBefore = previousPunctuation;
+      previousPunctuation = character;
+    }
+    index += 1;
+  }
+
+  return out.join("");
+}
+
+/** Reads the identifier ending at `end` (exclusive), or the empty string when there is none. */
+function identifierBefore(text: string, end: number): string {
+  let start = end;
+  while (start > 0 && isIdentifierChar(text[start - 1])) start -= 1;
+  return text.slice(start, end);
+}
+
+function lineOf(text: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index; i += 1) if (text[i] === "\n") line += 1;
+  return line;
+}
+
+/** Every global platform-dialog call in one source file, in source order. */
+export function findPlatformDialogCalls(source: string): PlatformDialogCall[] {
+  const code = maskNonCode(source);
+  const found: PlatformDialogCall[] = [];
+
+  // `window.confirm(`, `window?.confirm(`, `window.confirm?.(` and `(window.confirm)(`
+  // all reach the same undrawable dialog.
+  const receiverPattern = new RegExp(
+    `(?<![A-Za-z0-9_$.])(?:${GLOBAL_RECEIVERS.join("|")})\\s*\\??\\s*\\.\\s*(?:${DIALOGS.join("|")})\\s*\\)*\\s*(?:\\?\\.)?\\s*\\(`,
+    "g",
+  );
+  for (const match of code.matchAll(receiverPattern)) {
+    found.push({ line: lineOf(code, match.index), form: match[0].replace(/\s+/g, "") });
+  }
+
+  // The bare forms, including any number of wrapping parentheses and an optional call.
+  const barePattern = new RegExp(
+    `(?<![A-Za-z0-9_$.])(?:${DIALOGS.join("|")})\\s*\\)*\\s*(?:\\?\\.)?\\s*\\(`,
+    "g",
+  );
+  for (const match of code.matchAll(barePattern)) {
+    // Step back over whitespace and any wrapping `(` so the preceding-token test sees the
+    // real context. A line break on the way means the call starts a statement, which is a
+    // call position whatever word ended the previous one.
+    let before = match.index;
+    let crossedLine = false;
+    while (before > 0 && (/\s/.test(code[before - 1]) || code[before - 1] === "(")) {
+      if (code[before - 1] === "\n") crossedLine = true;
+      before -= 1;
+    }
+    // A member access reaches the receiver's own method, not the global.
+    if (before > 0 && code[before - 1] === ".") continue;
+    const preceding = identifierBefore(code, before);
+    if (!crossedLine && preceding.length > 0 && !CALL_POSITION_KEYWORDS.has(preceding)) continue;
+    found.push({ line: lineOf(code, match.index), form: match[0].replace(/\s+/g, "") });
+  }
+
+  /*
+   * Computed access is matched against the RAW source, because the quotes that make it work
+   * are exactly what the mask removes. A string that merely contains this shape is reported
+   * too, which is the safe direction: a false positive is one line to look at, a false
+   * negative is a guard that has quietly stopped guarding.
+   */
+  const computedPattern = new RegExp(
+    `(?<![A-Za-z0-9_$.])(?:${GLOBAL_RECEIVERS.join("|")})\\s*\\??\\s*\\[\\s*["'](?:${DIALOGS.join("|")})["']\\s*\\]\\s*(?:\\?\\.)?\\s*\\(`,
+    "g",
+  );
+  for (const match of source.matchAll(computedPattern)) {
+    found.push({ line: lineOf(source, match.index), form: match[0].replace(/\s+/g, "") });
+  }
+
+  return found.sort((a, b) => a.line - b.line);
+}
diff --git a/tests/helpers/responses-core-source.ts b/tests/helpers/responses-core-source.ts
index 6b1aa1e5d63..36b44511c96 100644
--- a/tests/helpers/responses-core-source.ts
+++ b/tests/helpers/responses-core-source.ts
@@ -37,6 +37,7 @@ export const RESPONSES_CORE_MODULES = [
   "request-spend.ts",
   "passthrough-execution.ts",
   "passthrough-dispatch.ts",
+  "reset-replay.ts",
   "passthrough-delivery.ts",
   "sidecar-execution.ts",
   "completion-policy.ts",
diff --git a/tests/helpers/windows-tray-probe-lifecycle-driver.ps1 b/tests/helpers/windows-tray-probe-lifecycle-driver.ps1
new file mode 100644
index 00000000000..394b20a8352
--- /dev/null
+++ b/tests/helpers/windows-tray-probe-lifecycle-driver.ps1
@@ -0,0 +1,178 @@
+# Behavioral driver for the tray startup-health probe lifecycle.
+#
+# Loads the REAL probe functions out of src/tray/windows-tray.ps1 via the
+# PowerShell AST (function definitions only - the top-level tray UI never runs),
+# stubs the WinForms controls with plain objects, stages a real hung child
+# process through the real Start-StartupHealthProbe, backdates its start past
+# the real timeout, then invokes the real Update-TrayState ticks and reports
+# observable process facts as JSON.
+#
+# Backdating the clock instead of sleeping 30s is deliberate: elapsed time is an
+# input to the maintenance branch, not the logic under test. What IS under test
+# is that the branch observes a timed-out child and terminates it.
+#
+# Scenarios:
+#   Offline - nothing answers /healthz, so the tray must stay offline AND still
+#     terminate the hung probe outside the online-only UI branch.
+#   Online  - the caller serves a fake /healthz and points runtime-port.json at
+#     it, so the first tick launches the probe through the real cameOnline gate;
+#     later ticks must kill the hung child and must not stack a replacement
+#     before the refresh interval (the pid file proves launches == 1).
+
+param(
+  [Parameter(Mandatory = $true)][string]$TrayScriptPath,
+  [Parameter(Mandatory = $true)][string]$ChildEnginePath,
+  [Parameter(Mandatory = $true)][string]$HangChildPath,
+  [Parameter(Mandatory = $true)][string]$CodexHome,
+  [Parameter(Mandatory = $true)][string]$OpenCodexHome,
+  [Parameter(Mandatory = $true)][string]$ResultPath,
+  [ValidateSet("Offline", "Online")][string]$Scenario = "Offline"
+)
+$ErrorActionPreference = "Stop"
+
+$tokens = $null
+$parseErrors = $null
+$ast = [System.Management.Automation.Language.Parser]::ParseFile($TrayScriptPath, [ref]$tokens, [ref]$parseErrors)
+if ($parseErrors.Count -gt 0) { throw "tray script parse failed: $($parseErrors[0].Message)" }
+$wanted = @(
+  "Write-ActionLog",
+  "ConvertTo-NativeArgument",
+  "Parse-StartupHealthText",
+  "Start-StartupHealthProbe",
+  "Complete-StartupHealthProbe",
+  "Read-ListenTarget",
+  "Read-JsonUrl",
+  "Update-TrayState"
+)
+$definitions = $ast.FindAll({ param($node) $node -is [System.Management.Automation.Language.FunctionDefinitionAst] }, $true)
+$loaded = @()
+foreach ($fn in $definitions) {
+  if ($wanted -contains $fn.Name) {
+    # Dot-source the full definition extent: several probe functions declare
+    # parentheses-style params (function F([string]$X) {...}), which live on
+    # the definition AST rather than the body. Installing only the body would
+    # silently drop those params ($X binds $null and the call misbehaves),
+    # while installing the raw extent as a body would make every call a
+    # silent no-op that merely redefines the function. Dot-sourcing defines
+    # each function exactly as the tray script declares it.
+    . ([ScriptBlock]::Create($fn.Extent.Text))
+    $loaded += $fn.Name
+  }
+}
+$missing = @($wanted | Where-Object { $loaded -notcontains $_ })
+if ($missing.Count -gt 0) { throw "tray script is missing functions: $($missing -join ', ')" }
+
+# Production-shaped inputs (normally the script params and top-level state).
+$BunPath = $ChildEnginePath
+$CliPath = $HangChildPath
+$BunRuntimeSource = "process"
+$CodexHome = $CodexHome
+$OpenCodexHome = $OpenCodexHome
+$HostPid = 0
+$heartbeatPath = Join-Path $OpenCodexHome "tray-heartbeat.json"
+$actionLogPath = Join-Path $OpenCodexHome "tray-actions.log"
+
+# WinForms stand-ins: Update-TrayState only sets plain properties on these.
+$statusItem = [PSCustomObject]@{ Text = ""; Enabled = $false }
+$safetyItem = [PSCustomObject]@{ Text = "" }
+$notify = [PSCustomObject]@{ Text = ""; Icon = $null }
+$startItem = [PSCustomObject]@{ Enabled = $true }
+$stopItem = [PSCustomObject]@{ Enabled = $false }
+$restartItem = [PSCustomObject]@{ Enabled = $false }
+$onlineIcon = $null
+$warningIcon = $null
+$offlineIcon = $null
+
+# Mirror the tray's script-state initialization.
+$script:online = $false
+$script:port = 10100
+$script:proxyPid = $null
+$script:wasOnline = $false
+$script:startupHealth = $null
+$script:startupHealthCheckedAt = 0
+$script:startupRefreshMs = 20000
+$script:startupProbeProcess = $null
+$script:startupProbeOutputTask = $null
+$script:startupProbeErrorTask = $null
+$script:startupProbeStarted = 0
+$script:startupProbeTimeoutMs = 30000
+$script:pendingAction = $null
+$script:pendingStarted = 0
+$script:pendingDeadline = 0
+$script:pendingOldProxyPid = $null
+$script:pendingProcess = $null
+
+$childPid = 0
+try {
+  if ($Scenario -eq "Online") {
+    # First tick settles wasOnline and launches the probe through the real
+    # cameOnline gate against the fake /healthz the caller serves.
+    Update-TrayState
+    if (-not $script:online) { throw "online scenario never came online" }
+    if ($null -eq $script:startupProbeProcess) { throw "cameOnline gate did not launch a probe" }
+  } else {
+    # Stage the exact state the maintenance branch must handle: a probe in flight
+    # while the proxy is down.
+    Start-StartupHealthProbe
+    if ($null -eq $script:startupProbeProcess) { throw "probe did not start" }
+  }
+  $childPid = $script:startupProbeProcess.Id
+  Start-Sleep -Milliseconds 500
+  # The timeout branch is only proven while the child is still alive here: an
+  # already-exited child would take the exited-probe path and every assertion
+  # below would pass without the Kill() ever running.
+  if ($script:startupProbeProcess.HasExited) { throw "probe child exited before maintenance; the timeout path was not exercised" }
+  $script:startupProbeStarted = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds() - $script:startupProbeTimeoutMs - 5000
+
+  $watch = [System.Diagnostics.Stopwatch]::StartNew()
+  Update-TrayState
+  $maintenanceMs = $watch.ElapsedMilliseconds
+  $onlineObserved = $script:online
+  $probeAfterMaintenance = $script:startupProbeProcess
+  Update-TrayState
+  $watch.Stop()
+
+  # Liveness is evaluated BEFORE the safety cleanup in finally, so the verdict
+  # reports what the maintenance branch did, not what the driver cleaned up.
+  $childGone = $false
+  try {
+    $live = Get-Process -Id $childPid -ErrorAction Stop
+    $childGone = $live.HasExited
+  } catch {
+    $childGone = $true
+  }
+
+  $pidFile = $env:OCX_PROBE_TEST_PID_FILE
+  $launches = 0
+  if ($pidFile -and (Test-Path -LiteralPath $pidFile)) {
+    $launches = @((Get-Content -LiteralPath $pidFile | Where-Object { $_.Trim() -ne "" })).Count
+  }
+
+  $verdict = [PSCustomObject]@{
+    scenario = $Scenario
+    onlineObserved = [bool]$onlineObserved
+    maintenanceMs = $maintenanceMs
+    totalMs = $watch.ElapsedMilliseconds
+    childPid = $childPid
+    childTerminated = [bool]$childGone
+    probeCleared = ($null -eq $probeAfterMaintenance) -and ($null -eq $script:startupProbeProcess)
+    launches = $launches
+  }
+  $verdictJson = $verdict | ConvertTo-Json -Compress
+  # Set-Content -Encoding UTF8 emits a BOM on Windows PowerShell 5.1; write raw
+  # BOM-less UTF-8 the way the tray writes its heartbeat file.
+  [System.IO.File]::WriteAllText($ResultPath, $verdictJson, (New-Object System.Text.UTF8Encoding($false)))
+} finally {
+  # Process.Start returns before the fake CLI writes its pid file, so a throw
+  # above (before that write) would leave the outer cleanup with no pid and a
+  # 120s sleeper behind. The in-hand pid closes that race.
+  if ($childPid -gt 0) {
+    try {
+      $leftover = Get-Process -Id $childPid -ErrorAction Stop
+      if (-not $leftover.HasExited) { Stop-Process -Id $childPid -Force -ErrorAction Stop }
+    } catch {
+      # Already exited or reaped; the verdict above already recorded the outcome.
+      $null = $_
+    }
+  }
+}
diff --git a/tests/lab/core-lab-boundary.test.ts b/tests/lab/core-lab-boundary.test.ts
index 32a5a9758fc..3f928d27a83 100644
--- a/tests/lab/core-lab-boundary.test.ts
+++ b/tests/lab/core-lab-boundary.test.ts
@@ -1021,6 +1021,7 @@ describe("activation window stays synchronous", () => {
     "(...).then()": "Promise.then on the fire-and-forget `import('../codex/plan-from-token')` chain. then() registers a callback and returns immediately; the callback is a nested function this scan skips. Awaiting the import would already fail Guard 3.",
     "(...).catch()": "Promise.catch on that same dynamic-import chain. Same fire-and-forget: it cannot suspend startServer.",
     "backgroundLifecycle.scheduleStartupRun()": "src/server/background-lifecycle.ts owns this object method. The call site cannot resolve the declaration statically; scheduleStartupRun is declared `(): void` and is documented as never blocking listen.",
+    "claudeIntercept.start()": "Instance method on the lifecycle from createClaudeInterceptLifecycle in src/server/index/claude-intercept-lifecycle.ts. Declared `(options): void`; it stores the fire-and-forget promise from startClaudeIntercept and never awaits it, so the intercept pair binding late (or failing) cannot suspend startServer. Its stop() runs inside the async stop wrapper, which this scan skips.",
     "spendLedgerLifecycle.track()": "Instance method on the lifecycle from acquireSpendLedgerServerLifecycle in src/server/index/spend-ledger-lifecycle.ts, called on each listener as it is created. It binds the listener's stop, records a rollback closure and returns the same server; it is declared `<T>(server: T): T` and contains no await. An `await spendLedgerLifecycle.track(...)` would already fail Guard 3. The lifecycle's release() is not here because it is called inside the async stop wrapper, which this scan skips as a nested function.",
   };
 
diff --git a/tests/lib/ambiguous-resend-composition.test.ts b/tests/lib/ambiguous-resend-composition.test.ts
new file mode 100644
index 00000000000..f9dd56e9bec
--- /dev/null
+++ b/tests/lib/ambiguous-resend-composition.test.ts
@@ -0,0 +1,291 @@
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  CODEX_TEXT_GUARDED_BUDGET_POLICY,
+  createRequestExecutionBudget,
+  deriveRequestExecutionBudget,
+  type RequestExecutionBudget,
+  type SendClass,
+} from "../../src/lib/request-execution-budget";
+import { authorizeResendForRecovery, type ResendDecision } from "../../src/lib/request-resend-gate";
+import type { RequestFailureStage } from "../../src/lib/request-failure-model";
+import {
+  fetchWithResetRetry,
+  isNonReplayableResponse,
+  refetchAfterProtocolSafeReset,
+  TRANSIENT_RETRY_MAX_ATTEMPTS,
+} from "../../src/lib/upstream-retry";
+import { ambiguousResendAllowanceFor } from "../../src/server/responses/reset-replay";
+import { resetReplayPolicyFor } from "../../src/providers/key-failover";
+import { repoPath } from "../helpers/repo-root";
+import type { OcxProviderConfig } from "../../src/types";
+
+/*
+ * Holds INV-RESEND-02 from structure/overview.md across a COMPOSITION of legs.
+ *
+ * tests/lib/ambiguous-resend-gate.test.ts asks the gate one question at a time and
+ * tests/lib/execution-budget-permits.test.ts asks the budget one claim at a time. Neither can
+ * see what this file is about: a request that reaches upstream through five layers, where
+ * every layer is correct on its own and the request as a whole still duplicates a turn.
+ */
+
+type ProviderRow = Pick<OcxProviderConfig, "retryOnReset">;
+
+/** The bare opt-in, and whatever one of it means to the operator today. */
+const OPTED_IN: ProviderRow = { retryOnReset: {} };
+const GRANT = resetReplayPolicyFor(OPTED_IN)?.replacements ?? 0;
+/**
+ * A row an operator tuned above the bare opt-in. Derived rather than written as a number: what
+ * matters is that it grants MORE than the row this request started on, not that it grants two.
+ */
+const MORE_PERMISSIVE: ProviderRow = { retryOnReset: { replacements: GRANT + 1 } };
+
+function reset(): Error {
+  const err = new Error("The socket connection was closed unexpectedly.");
+  (err as Error & { code: string }).code = "ECONNRESET";
+  return err;
+}
+
+const warnSpies: Array<ReturnType<typeof spyOn>> = [];
+function silenceWarn(): void {
+  warnSpies.push(spyOn(console, "warn").mockImplementation(() => {}));
+}
+afterEach(() => {
+  for (const spy of warnSpies.splice(0)) spy.mockRestore();
+});
+
+/**
+ * One logical request, watched through the two numbers that have to be watched apart.
+ *
+ * `physicalSends` is every send that left this proxy. `ambiguousSends` is the subset that carried a
+ * turn the origin may already have run -- the number an operator consents to when they set
+ * `retryOnReset`, and the only one that counts duplicate inferences. A composition can hold the
+ * first bound and break the second: four sends is within budget whether one of them replaces a
+ * possibly-executed turn or three of them do.
+ */
+function oneLogicalRequest() {
+  const budget = createRequestExecutionBudget(CODEX_TEXT_GUARDED_BUDGET_POLICY);
+  const counts = { physical: 0, ambiguous: 0 };
+
+  /** Every leg asks the gate, and the gate is what tells us the send duplicates a turn. */
+  const authorize = (stage: RequestFailureStage, row: ProviderRow): ResendDecision => {
+    const decision = authorizeResendForRecovery(
+      stage,
+      "connection-reset",
+      // The allowance a leg builds from the provider row it is CURRENTLY running against,
+      // which rotation, refresh, transport resolution and a combo target each reassign.
+      ambiguousResendAllowanceFor(row, () => true, limit => budget.claimAmbiguousResend?.(limit) === true),
+    );
+    if (decision.allowed && decision.spentOperatorAllowance) counts.ambiguous += 1;
+    return decision;
+  };
+
+  const dispatcher = (outcomes: Array<Response | Error>) => {
+    let index = 0;
+    return async (): Promise<Response> => {
+      counts.physical += 1;
+      const next = outcomes[index] ?? outcomes[outcomes.length - 1];
+      index += 1;
+      if (next instanceof Error) throw next;
+      return next ?? new Response("answer");
+    };
+  };
+
+  /**
+   * What src/server/responses/request-send-budget.ts hands a recovery leg: the base allowance
+   * while it lasts, then the single final-recovery reserve, and nothing after that.
+   */
+  const recoveryAttempts = (sendClass: SendClass, targetKey: string): number => {
+    const base = budget.remainingBaseSends(TRANSIENT_RETRY_MAX_ATTEMPTS);
+    if (base > 0) return base;
+    const decision = budget.reserveDispatch({ sendClass, targetKey, countedExternally: true });
+    return decision.allowed ? 1 : 0;
+  };
+
+  return {
+    budget,
+    get physicalSends(): number { return counts.physical; },
+    get ambiguousSends(): number { return counts.ambiguous; },
+    recoveryAttempts,
+    /** A leg that fails before any response head, through the real reset ladder. */
+    preHeader: (outcomes: Array<Response | Error>, row: ProviderRow, attempts?: number): Promise<Response> =>
+      fetchWithResetRetry(dispatcher(outcomes), {
+        attempts: attempts ?? budget.remainingBaseSends(TRANSIENT_RETRY_MAX_ATTEMPTS),
+        onSendsConsumed: sends => { budget.used += sends; },
+        claimAmbiguousResend: () => authorize("pre-header", row).allowed,
+      }),
+    /** A stream that died after the head while carrying only control events. */
+    postHeader: (outcomes: Array<Response | Error>, row: ProviderRow): Promise<Response | null> => {
+      const send = dispatcher(outcomes);
+      return refetchAfterProtocolSafeReset(
+        async () => { const response = await send(); budget.used += 1; return response; },
+        reset(),
+        {
+          attempts: budget.remainingBaseSends(TRANSIENT_RETRY_MAX_ATTEMPTS),
+          authorize: () => authorize("protocol-prelude", row).allowed,
+        },
+      );
+    },
+  };
+}
+
+describe("one resend budget across composed recovery legs", () => {
+  test("the whole chain spends the grant once, whatever each leg was separately entitled to", async () => {
+    silenceWarn();
+    const request = oneLogicalRequest();
+
+    // 1. The first send dies before any head. The operator's replacement is spent here, and
+    //    the replacement answers.
+    const first = await request.preHeader([reset(), new Response("first answer")], OPTED_IN);
+    expect(await first.text()).toBe("first answer");
+    expect(request.physicalSends).toBe(2);
+    expect(request.ambiguousSends).toBe(GRANT);
+
+    // 2. That stream then dies after the head with only control events on it -- the other side
+    //    of the same question. Nothing was observed, so this stage would be entitled to a
+    //    replacement of its own; the request has none left, and no send leaves.
+    const secondChance = await request.postHeader([new Response("second answer")], OPTED_IN);
+    expect(secondChance).toBeNull();
+    expect(request.physicalSends).toBe(2);
+
+    // 3. A combo candidate derives its own scope, with its own reserve and target ledgers. The
+    //    grant is not one of them, at either row's ceiling.
+    const comboChild = deriveRequestExecutionBudget(request.budget, CODEX_TEXT_GUARDED_BUDGET_POLICY);
+    expect(comboChild.claimAmbiguousResend?.(GRANT)).toBe(false);
+    expect(comboChild.claimAmbiguousResend?.(MORE_PERMISSIVE.retryOnReset?.replacements ?? 0)).toBe(false);
+
+    // 4. A credential refresh replays the turn on a new token and resets before the head. The
+    //    leg settles as the refusal rather than sending again, and the client is handed a
+    //    response no retry policy will replay.
+    const afterRefresh = await request.preHeader([reset(), new Response("duplicate")], OPTED_IN);
+    expect(isNonReplayableResponse(afterRefresh)).toBe(true);
+    expect(request.physicalSends).toBe(3);
+
+    // 5. The 429 leg finds the base allowance gone. The grant is never consulted, which is the
+    //    ordering that keeps a spent send budget from draining it.
+    expect(request.budget.remainingBaseSends(TRANSIENT_RETRY_MAX_ATTEMPTS)).toBe(0);
+
+    // 6. The last send this request is entitled to is the single final-recovery reserve, and
+    //    the account it moves to is a row the operator tuned HIGHER. A ceiling read from the
+    //    asking leg let that row buy a second duplicate inference on the way out; the ceiling
+    //    is the smallest any leg presented, so it buys nothing.
+    const attempts = request.recoveryAttempts("account-failover", "other-account");
+    expect(attempts).toBe(1);
+    const lastSend = await request.preHeader([reset(), new Response("duplicate")], MORE_PERMISSIVE, attempts);
+    expect(isNonReplayableResponse(lastSend)).toBe(true);
+
+    expect(request.ambiguousSends).toBe(GRANT);
+    expect(request.physicalSends).toBe(CODEX_TEXT_GUARDED_BUDGET_POLICY.maxTotalModelSends);
+    // The two numbers describe the same sends, so the request's own ledger has to agree with
+    // what the transport actually dispatched. A leg that books a send it never made, or makes
+    // one it never booked, shows up here rather than as a ceiling that quietly stopped firing.
+    expect(request.budget.used).toBe(request.physicalSends);
+  });
+
+  test("a later leg on a more permissive row cannot raise this request's ceiling", () => {
+    const budget = createRequestExecutionBudget(CODEX_TEXT_GUARDED_BUDGET_POLICY);
+    const strict = resetReplayPolicyFor(OPTED_IN)?.replacements ?? 0;
+    const permissive = resetReplayPolicyFor(MORE_PERMISSIVE)?.replacements ?? 0;
+    expect(permissive).toBeGreaterThan(strict);
+
+    // A leg that cannot state a grant refuses on its own terms and does not narrow the
+    // request either: a malformed ceiling must not cancel what an opted-in row really gave.
+    expect(budget.claimAmbiguousResend?.(0)).toBe(false);
+
+    for (let spent = 0; spent < strict; spent += 1) {
+      expect(budget.claimAmbiguousResend?.(strict)).toBe(true);
+    }
+    // route.provider is reassigned by rotation, refresh and transport resolution, so the row a
+    // leg reads its ceiling from is not necessarily the row the request started on.
+    expect(budget.claimAmbiguousResend?.(permissive)).toBe(false);
+  });
+
+  test("a request that starts permissive is still held to the strictest row that asks", () => {
+    const budget = createRequestExecutionBudget(CODEX_TEXT_GUARDED_BUDGET_POLICY);
+    const strict = resetReplayPolicyFor(OPTED_IN)?.replacements ?? 0;
+    const permissive = resetReplayPolicyFor(MORE_PERMISSIVE)?.replacements ?? 0;
+
+    for (let spent = 0; spent < strict; spent += 1) {
+      expect(budget.claimAmbiguousResend?.(permissive)).toBe(true);
+    }
+    // The permissive row had more to give, and the strict row is what this request is held to
+    // from the moment it asks -- the direction the pre-existing ordering already failed closed.
+    expect(budget.claimAmbiguousResend?.(strict)).toBe(false);
+    expect(budget.claimAmbiguousResend?.(permissive)).toBe(false);
+  });
+
+  test("a scope derived from a budget this factory did not build shares the request's grant", () => {
+    // The bridge exists because `isRequestExecutionBudget` is a shape test: a hand-built view
+    // reaches derivation, and refusing it would turn a routing request into a 500. What it may
+    // not do is hand that request a second grant -- `claimAmbiguousResend` is public on the
+    // parent, so unlike a pending booking there is nothing private stopping it being asked.
+    const owner = createRequestExecutionBudget(CODEX_TEXT_GUARDED_BUDGET_POLICY);
+    const view: RequestExecutionBudget = {
+      get used(): number { return owner.used; },
+      set used(next: number) { owner.used = next; },
+      logicalRequestId: owner.logicalRequestId,
+      policyVersion: owner.policyVersion,
+      policy: owner.policy,
+      get reserveSpent(): boolean { return owner.reserveSpent; },
+      get alternateTargetSends(): number { return owner.alternateTargetSends; },
+      get targetTransitions(): number { return owner.targetTransitions; },
+      get lastTargetKey(): string | undefined { return owner.lastTargetKey; },
+      remainingBaseSends: (cap: number): number => owner.remainingBaseSends(cap),
+      claimAmbiguousResend: (limit: number): boolean => owner.claimAmbiguousResend?.(limit) === true,
+      reserveDispatch: intent => owner.reserveDispatch(intent),
+    };
+
+    const first = deriveRequestExecutionBudget(view, CODEX_TEXT_GUARDED_BUDGET_POLICY);
+    const second = deriveRequestExecutionBudget(view, CODEX_TEXT_GUARDED_BUDGET_POLICY);
+    expect(first.claimAmbiguousResend?.(GRANT)).toBe(true);
+    expect(second.claimAmbiguousResend?.(GRANT)).toBe(false);
+    expect(view.claimAmbiguousResend?.(GRANT)).toBe(false);
+    expect(owner.claimAmbiguousResend?.(GRANT)).toBe(false);
+  });
+
+  test("a parent that grants nothing cannot be bridged into a grant", () => {
+    const stub: RequestExecutionBudget = {
+      used: 0,
+      logicalRequestId: "stub",
+      policyVersion: "stub",
+      policy: CODEX_TEXT_GUARDED_BUDGET_POLICY,
+      reserveSpent: false,
+      alternateTargetSends: 0,
+      targetTransitions: 0,
+      lastTargetKey: undefined,
+      remainingBaseSends: () => 0,
+      reserveDispatch: () => ({ allowed: false, reason: "total-exhausted" }),
+    };
+    // Fail closed: a budget that predates the grant has no operator override to share, and an
+    // unknown upstream state is not made replayable by the scope that asked.
+    expect(deriveRequestExecutionBudget(stub, CODEX_TEXT_GUARDED_BUDGET_POLICY).claimAmbiguousResend?.(GRANT))
+      .toBe(false);
+  });
+
+  test("every post-header replacement in the tree is authorized before it sends", async () => {
+    // `authorize` is optional on the helper, so this is the property that keeps a call site from
+    // becoming a resend of a possibly-executed turn that no gate ever weighed. Scanned rather
+    // than listed: the hazard is the call site nobody remembered to add to a list.
+    const srcDir = repoPath("src");
+    const unauthorized: string[] = [];
+    let callSites = 0;
+    for await (const relative of new Bun.Glob("**/*.ts").scan({ cwd: srcDir })) {
+      const source = readFileSync(join(srcDir, relative), "utf8");
+      for (const match of source.matchAll(/refetchAfterProtocolSafeReset\(/g)) {
+        const start = match.index ?? 0;
+        // The declaration itself is not a call site, and the import names it without one.
+        if (/\bfunction\s+$/.test(source.slice(Math.max(0, start - 24), start))) continue;
+        callSites += 1;
+        // The options object is the last argument of the call, so the window has to cover the
+        // whole call expression; these are long ones.
+        if (!source.slice(start, start + 8000).includes("authorize:")) {
+          unauthorized.push(relative + ":" + (source.slice(0, start).split("\n").length));
+        }
+      }
+    }
+    expect(unauthorized).toEqual([]);
+    // The scan is only evidence while it still finds the call it was written for.
+    expect(callSites).toBeGreaterThan(0);
+  });
+});
diff --git a/tests/lib/ambiguous-resend-gate.test.ts b/tests/lib/ambiguous-resend-gate.test.ts
new file mode 100644
index 00000000000..8f8bd7dea45
--- /dev/null
+++ b/tests/lib/ambiguous-resend-gate.test.ts
@@ -0,0 +1,172 @@
+import { describe, expect, test } from "bun:test";
+import {
+  authorizeResend,
+  authorizeResendForRecovery,
+  RESEND_REFUSALS,
+  type AmbiguousResendAllowance,
+} from "../../src/lib/request-resend-gate";
+import {
+  causeDisposition,
+  causeForRecoveryKind,
+  permitsResend,
+  REQUEST_FAILURE_CAUSES,
+  REQUEST_FAILURE_STAGES,
+  resendPermission,
+  resendSendClass,
+  stageCommitment,
+} from "../../src/lib/request-failure-model";
+import { ATTEMPT_RECOVERY_KIND_ROSTER } from "../../src/usage/telemetry-contract";
+
+/*
+ * Holds INV-RESEND-02 from structure/overview.md.
+ */
+
+/**
+ * A grant with a counted `claim`. `limit` is the number of replacements the whole logical
+ * request may make, which is the property every test below is really about.
+ */
+function allowance(options: { selfContained?: boolean; limit?: number } = {}): AmbiguousResendAllowance & {
+  claims: () => number;
+} {
+  let claimed = 0;
+  const limit = options.limit ?? 1;
+  return {
+    selfContained: options.selfContained ?? true,
+    claim: () => {
+      if (claimed >= limit) return false;
+      claimed += 1;
+      return true;
+    },
+    claims: () => claimed,
+  };
+}
+
+describe("authorizeResend over the whole stage-by-cause cross product", () => {
+  test("agrees with the table wherever the table already answers", () => {
+    for (const stage of REQUEST_FAILURE_STAGES) {
+      for (const cause of REQUEST_FAILURE_CAUSES) {
+        const permission = resendPermission(stage, cause);
+        const decision = authorizeResend(stage, cause);
+        expect(decision.permission).toBe(permission);
+        expect(decision.stage).toBe(stage);
+        expect(decision.cause).toBe(cause);
+        // The gate adds an override for exactly one answer and changes none of the others.
+        if (permission !== "refused-ambiguous") {
+          expect(decision.allowed).toBe(permitsResend(permission));
+        }
+        if (decision.allowed) expect(decision.sendClass).toBe(resendSendClass(cause));
+      }
+    }
+  });
+
+  test("a stage the caller observed something at refuses whatever the operator granted", () => {
+    const grant = allowance({ limit: 5 });
+    for (const stage of REQUEST_FAILURE_STAGES) {
+      if (stageCommitment(stage) === "nothing-observed") continue;
+      for (const cause of REQUEST_FAILURE_CAUSES) {
+        const decision = authorizeResend(stage, cause, grant);
+        expect(decision.allowed).toBe(false);
+        if (!decision.allowed) expect(decision.refusal).toBe("committed");
+      }
+    }
+    // Nothing committed may drain the grant a later ambiguous failure is entitled to.
+    expect(grant.claims()).toBe(0);
+  });
+
+  test("a futile cause refuses without spending the grant", () => {
+    const grant = allowance({ limit: 5 });
+    for (const cause of REQUEST_FAILURE_CAUSES) {
+      if (causeDisposition(cause) !== "resend-is-futile") continue;
+      const decision = authorizeResend("pre-header", cause, grant);
+      expect(decision.allowed).toBe(false);
+      if (!decision.allowed) expect(decision.refusal).toBe("futile");
+    }
+    expect(grant.claims()).toBe(0);
+  });
+
+  test("every refusal the gate can produce is a declared member", () => {
+    const produced = new Set<string>();
+    const cases: Array<AmbiguousResendAllowance | undefined> = [
+      undefined,
+      allowance({ selfContained: false }),
+      allowance({ limit: 0 }),
+    ];
+    for (const stage of REQUEST_FAILURE_STAGES) {
+      for (const cause of REQUEST_FAILURE_CAUSES) {
+        for (const grant of cases) {
+          const decision = authorizeResend(stage, cause, grant);
+          if (!decision.allowed) produced.add(decision.refusal);
+        }
+      }
+    }
+    for (const refusal of produced) expect(RESEND_REFUSALS).toContain(refusal);
+    // Every declared member is reachable, so the roster is not carrying a dead name.
+    expect([...RESEND_REFUSALS].sort()).toEqual([...produced].sort());
+  });
+});
+
+describe("the ambiguous override", () => {
+  const ambiguous = REQUEST_FAILURE_STAGES.filter(stage => stageCommitment(stage) === "nothing-observed");
+
+  test("refuses with no operator policy and never claims", () => {
+    for (const stage of ambiguous) {
+      const decision = authorizeResend(stage, "transport-ambiguous");
+      expect(decision.allowed).toBe(false);
+      if (!decision.allowed) expect(decision.refusal).toBe("ambiguous-no-policy");
+    }
+  });
+
+  test("refuses a request it cannot judge replayable, without spending the grant", () => {
+    const grant = allowance({ selfContained: false, limit: 3 });
+    for (const stage of ambiguous) {
+      const decision = authorizeResend(stage, "transport-ambiguous", grant);
+      expect(decision.allowed).toBe(false);
+      if (!decision.allowed) expect(decision.refusal).toBe("ambiguous-request-not-replayable");
+    }
+    expect(grant.claims()).toBe(0);
+  });
+
+  test("one logical request buys one replacement, whichever stage asks first", () => {
+    // The defect this gate exists to prevent: #4942 asked before the response head and #4989
+    // asked after it, and two separate grants would let one turn be sent twice more.
+    const grant = allowance({ limit: 1 });
+    const first = authorizeResend("pre-header", "transport-ambiguous", grant);
+    expect(first.allowed).toBe(true);
+    if (first.allowed) expect(first.spentOperatorAllowance).toBe(true);
+
+    for (const stage of ambiguous) {
+      const later = authorizeResend(stage, "transport-ambiguous", grant);
+      expect(later.allowed).toBe(false);
+      if (!later.allowed) expect(later.refusal).toBe("ambiguous-allowance-spent");
+    }
+    expect(grant.claims()).toBe(1);
+  });
+
+  test("a grant of two is spent exactly twice", () => {
+    const grant = allowance({ limit: 2 });
+    expect(authorizeResend("pre-header", "transport-ambiguous", grant).allowed).toBe(true);
+    expect(authorizeResend("protocol-prelude", "transport-ambiguous", grant).allowed).toBe(true);
+    expect(authorizeResend("headers-only", "transport-ambiguous", grant).allowed).toBe(false);
+    expect(grant.claims()).toBe(2);
+  });
+});
+
+describe("authorizeResendForRecovery", () => {
+  test("derives the cause from the kind it will be recorded as, for every kind", () => {
+    for (const kind of ATTEMPT_RECOVERY_KIND_ROSTER) {
+      const decision = authorizeResendForRecovery("pre-header", kind, allowance({ limit: 99 }));
+      expect(decision.cause).toBe(causeForRecoveryKind(kind));
+      expect(decision.recoveryKind).toBe(kind);
+      // The answer is the table's, asked in the other vocabulary.
+      expect(decision.permission).toBe(resendPermission("pre-header", causeForRecoveryKind(kind)));
+    }
+  });
+
+  test("a connection reset is the ambiguous row at both observable-nothing stages", () => {
+    for (const stage of ["pre-header", "headers-only", "protocol-prelude"] as const) {
+      expect(authorizeResendForRecovery(stage, "connection-reset").permission).toBe("refused-ambiguous");
+      expect(authorizeResendForRecovery(stage, "connection-reset", allowance()).allowed).toBe(true);
+    }
+    expect(authorizeResendForRecovery("semantic-output", "connection-reset", allowance()).allowed).toBe(false);
+  });
+});
diff --git a/tests/lib/execution-budget-permits.test.ts b/tests/lib/execution-budget-permits.test.ts
index 3f784e3c145..916304accad 100644
--- a/tests/lib/execution-budget-permits.test.ts
+++ b/tests/lib/execution-budget-permits.test.ts
@@ -482,3 +482,42 @@ describe("derived scopes and the durable spend observer", () => {
     expect(parent.used).toBe(0);
   });
 });
+
+describe("the ambiguous-resend allowance", () => {
+  test("one logical request holds one grant, and a derived scope shares it", () => {
+    // The reason the grant lives here rather than beside the policy that issues it: a combo
+    // child derives its own budget, and two grants would let one turn replace an
+    // unknown-state send twice -- once on the parent leg, once on the child's.
+    const parent = createRequestExecutionBudget(CODEX_TEXT_GUARDED_BUDGET_POLICY);
+    const child = deriveRequestExecutionBudget(parent, CODEX_TEXT_GUARDED_BUDGET_POLICY);
+
+    expect(parent.claimAmbiguousResend?.(1)).toBe(true);
+    expect(child.claimAmbiguousResend?.(1)).toBe(false);
+    expect(parent.claimAmbiguousResend?.(1)).toBe(false);
+    // A later leg cannot raise the ceiling, either. Each leg reads its number from the
+    // provider row it is running against, and that row is reassigned mid-request by rotation,
+    // refresh, transport resolution and each combo target -- so releasing the difference meant
+    // the count of duplicate inferences depended on which row happened to ask last. The
+    // request keeps the smallest ceiling any leg presented.
+    expect(child.claimAmbiguousResend?.(2)).toBe(false);
+    expect(parent.claimAmbiguousResend?.(2)).toBe(false);
+  });
+
+  test("a grant is not a send, and a spent send budget is not a spent grant", () => {
+    const budget = createRequestExecutionBudget(ONE_SEND_LEFT);
+    expect(budget.reserveDispatch({ sendClass: "initial", targetKey: "t" }).allowed).toBe(true);
+    expect(budget.remainingBaseSends(5)).toBe(0);
+    // The grant survives, because it authorises nothing by itself: the send it would fund
+    // still has to fit in the allowance, which is the caller's check.
+    expect(budget.claimAmbiguousResend?.(1)).toBe(true);
+    expect(budget.used).toBe(1);
+  });
+
+  test("a ceiling of zero or a nonsense ceiling grants nothing", () => {
+    const budget = createRequestExecutionBudget(CODEX_TEXT_GUARDED_BUDGET_POLICY);
+    expect(budget.claimAmbiguousResend?.(0)).toBe(false);
+    expect(budget.claimAmbiguousResend?.(Number.NaN)).toBe(false);
+    expect(budget.claimAmbiguousResend?.(Number.POSITIVE_INFINITY)).toBe(false);
+    expect(budget.claimAmbiguousResend?.(1)).toBe(true);
+  });
+});
diff --git a/tests/lib/failure-attribution.test.ts b/tests/lib/failure-attribution.test.ts
new file mode 100644
index 00000000000..8b8b438d2a7
--- /dev/null
+++ b/tests/lib/failure-attribution.test.ts
@@ -0,0 +1,209 @@
+import { describe, expect, test } from "bun:test";
+import {
+  deriveRequestFailureAttribution,
+  deriveRequestFailureCause,
+  deriveRequestFailureStage,
+  type RequestFailureFacts,
+} from "../../src/lib/request-failure-attribution";
+import {
+  REQUEST_FAILURE_CAUSES,
+  REQUEST_FAILURE_STAGES,
+  permitsResend,
+  resendPermission,
+  stageCommitment,
+} from "../../src/lib/request-failure-model";
+import { ATTEMPT_RECOVERY_KIND_ROSTER } from "../../src/usage/telemetry-contract";
+import {
+  REQUEST_CLOSE_REASONS,
+  REQUEST_OUTCOME_CLASSES,
+  REQUEST_TERMINAL_STATUSES,
+  classifyRequestOutcome,
+} from "../../src/usage/request-outcome";
+import { REQUEST_TRANSPORT_PHASES } from "../../src/usage/telemetry-contract";
+
+/**
+ * The fact space this derivation is total over.
+ *
+ * Holds INV-ATTRIBUTION-01 from structure/overview.md.
+ *
+ * Every axis is read from the module that declares it rather than restated, so a member added to
+ * a roster widens this cross product instead of leaving a case nobody wrote. The status list is
+ * the one axis that cannot be derived -- HTTP statuses are not a roster this repository owns --
+ * so it enumerates one representative per branch the derivation distinguishes, plus the two
+ * boundary values (`0`, no head at all, and `499`) that decide a branch on their own.
+ */
+const STATUSES = [0, 101, 200, 400, 401, 403, 413, 429, 451, 499, 500, 502, 503] as const;
+// Read from the modules that declare them, so a member added later widens this space instead of
+// leaving a case nobody wrote. Restating them is what let the recovery roster drift to nine of
+// thirteen while every test stayed green.
+const TERMINAL_STATUSES = [undefined, ...REQUEST_TERMINAL_STATUSES] as const;
+const CLOSE_REASONS = [undefined, ...REQUEST_CLOSE_REASONS] as const;
+const TRANSPORT_PHASES = [undefined, ...REQUEST_TRANSPORT_PHASES] as const;
+
+function* factSpace(): Generator<RequestFailureFacts> {
+  for (const status of STATUSES) {
+    for (const terminalStatus of TERMINAL_STATUSES) {
+      for (const closeReason of CLOSE_REASONS) {
+        for (const transportPhase of TRANSPORT_PHASES) {
+          for (const outputObserved of [false, true]) {
+            for (const sideEffectObserved of [false, true]) {
+              yield {
+                status,
+                ...(terminalStatus ? { terminalStatus } : {}),
+                ...(closeReason ? { closeReason } : {}),
+                ...(transportPhase ? { transportPhase } : {}),
+                outputObserved,
+                sideEffectObserved,
+              };
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+describe("request failure attribution", () => {
+  test("every derived stage and cause is a member of the landed rosters", () => {
+    let seen = 0;
+    for (const facts of factSpace()) {
+      seen += 1;
+      expect(REQUEST_FAILURE_STAGES).toContain(deriveRequestFailureStage(facts));
+      const cause = deriveRequestFailureCause(facts);
+      if (cause !== undefined) expect(REQUEST_FAILURE_CAUSES).toContain(cause);
+    }
+    // The generator is the oracle: an axis added above must actually widen the space.
+    expect(seen).toBe(
+      STATUSES.length * TERMINAL_STATUSES.length * CLOSE_REASONS.length * TRANSPORT_PHASES.length * 4,
+    );
+  });
+
+  test("attribution is recorded for exactly the outcomes that are not completed", () => {
+    const outcomesWithAttribution = new Set<string>();
+    for (const facts of factSpace()) {
+      const outcome = classifyRequestOutcome(facts);
+      const attribution = deriveRequestFailureAttribution(facts);
+      if (outcome === "completed") {
+        expect(attribution).toBeUndefined();
+        continue;
+      }
+      expect(attribution).toBeDefined();
+      outcomesWithAttribution.add(outcome);
+    }
+    expect([...outcomesWithAttribution].toSorted())
+      .toEqual(REQUEST_OUTCOME_CLASSES.filter(outcome => outcome !== "completed").toSorted());
+  });
+
+  test("a cause is recorded for a failure and withheld from an incomplete turn", () => {
+    for (const facts of factSpace()) {
+      const outcome = classifyRequestOutcome(facts);
+      const cause = deriveRequestFailureCause(facts);
+      if (outcome === "completed" || outcome === "incomplete") expect(cause).toBeUndefined();
+      else expect(cause).toBeDefined();
+    }
+  });
+
+  test("an aborted request is attributed to the caller, whichever way it was signalled", () => {
+    expect(deriveRequestFailureCause({ status: 499 })).toBe("client-cancelled");
+    expect(deriveRequestFailureCause({ status: 502, closeReason: "client_cancel" })).toBe("client-cancelled");
+  });
+
+  test("a stage never claims more than the caller observed", () => {
+    for (const facts of factSpace()) {
+      const stage = deriveRequestFailureStage(facts);
+      if (facts.outputObserved !== true) {
+        // Nothing reached the caller, so no stage may report an irreversible observation.
+        expect(stageCommitment(stage)).not.toBe("output-observed");
+        expect(stageCommitment(stage)).not.toBe("answer-delivered");
+      }
+    }
+  });
+
+  test("an observed side effect refuses a resend for every cause", () => {
+    const facts: RequestFailureFacts = { status: 502, sideEffectObserved: true };
+    const stage = deriveRequestFailureStage(facts);
+    for (const cause of REQUEST_FAILURE_CAUSES) {
+      expect(permitsResend(resendPermission(stage, cause))).toBe(false);
+    }
+  });
+
+  test("a 400 is refined by the recovery kind that identifies which rejection it was", () => {
+    const base = { status: 400 } as const;
+    expect(deriveRequestFailureCause(base)).toBe("payload-rejected");
+    expect(deriveRequestFailureCause({ ...base, recoveryKinds: ["opaque-blob-rejection"] }))
+      .toBe("ciphertext-refusal");
+    expect(deriveRequestFailureCause({ ...base, recoveryKinds: ["reasoning-effort-downgrade"] }))
+      .toBe("parameter-rejected");
+  });
+
+  test("a recovery kind does not become the cause when the request ended on another status", () => {
+    // The attempt recovered from a rejected reasoning parameter and then died on a 500. The
+    // request failed for the 500, and reporting the earlier rejection would send an operator
+    // after a problem that was already worked around.
+    for (const kind of ATTEMPT_RECOVERY_KIND_ROSTER) {
+      expect(deriveRequestFailureCause({ status: 500, recoveryKinds: [kind] })).toBe("upstream-fault");
+    }
+  });
+
+  test("a turn that settled with no output is empty output rather than an upstream fault", () => {
+    expect(deriveRequestFailureCause({ status: 200, terminalStatus: "failed", outputObserved: false }))
+      .toBe("empty-output");
+    expect(deriveRequestFailureCause({ status: 200, terminalStatus: "failed", outputObserved: true }))
+      .toBe("upstream-fault");
+  });
+
+  test("a stream that died mid-flight is ambiguous, not an upstream fault", () => {
+    // The production shape: the relay reports a SYNTHETIC 502 after a mid-stream read failure
+    // and marks the attempt aborted. Reading the 502 in status order would claim the origin
+    // answered when it did not.
+    expect(deriveRequestFailureCause({
+      status: 502, transportPhase: "mid_stream", terminalSource: "synthetic",
+    })).toBe("transport-ambiguous");
+    expect(deriveRequestFailureCause({ status: 502, streamAborted: true })).toBe("transport-ambiguous");
+    // An upstream 502 that is genuinely upstream stays an upstream fault.
+    expect(deriveRequestFailureCause({ status: 502, terminalSource: "upstream" })).toBe("upstream-fault");
+  });
+
+  test("an unknown execution state never reads as a proven unsent send", () => {
+    // `transport-unsent` permits an automatic resend, so it is reachable only from a site that
+    // classified a pre-connect failure and can prove it. Everything else answers ambiguously,
+    // which is the safe direction.
+    expect(deriveRequestFailureCause({ status: 0 })).toBe("transport-ambiguous");
+    expect(deriveRequestFailureCause({ status: 0, causeHint: "transport-unsent" })).toBe("transport-unsent");
+  });
+
+  test("payment required is a quota problem, not a bad payload", () => {
+    expect(deriveRequestFailureCause({ status: 402 })).toBe("quota-exhausted");
+  });
+
+  test("a local refusal is attributed to this proxy rather than to upstream", () => {
+    expect(deriveRequestFailureCause({ status: 502, locallyAnswered: true })).toBe("local-refusal");
+  });
+
+  test("a cause the finalizer proved outranks the status table", () => {
+    // The key-account rotation seals the previous attempt because a named recovery rejected it.
+    // That argument is evidence; reconstructing the cause from 502 would lose it.
+    expect(deriveRequestFailureCause({ status: 502, causeHint: "credential-rejected" }))
+      .toBe("credential-rejected");
+    // A client cancel is a fact about the caller and still outranks the hint.
+    expect(deriveRequestFailureCause({ status: 499, causeHint: "credential-rejected" }))
+      .toBe("client-cancelled");
+  });
+
+  test("only the last recovery refines a 400, and only on its own status", () => {
+    // The attempt recovered from a rejected ciphertext and then hit a rejected parameter.
+    expect(deriveRequestFailureCause({
+      status: 400,
+      recoveryKinds: ["opaque-blob-rejection", "reasoning-effort-downgrade"],
+    })).toBe("parameter-rejected");
+    // A recovery for a different status never refines this one.
+    expect(deriveRequestFailureCause({ status: 400, recoveryKinds: ["oauth-401"] }))
+      .toBe("payload-rejected");
+  });
+
+  test("a relayed side effect raises the stage above observed output", () => {
+    expect(deriveRequestFailureStage({ status: 502, outputObserved: true })).toBe("semantic-output");
+    expect(deriveRequestFailureStage({ status: 502, outputObserved: true, sideEffectObserved: true }))
+      .toBe("side-effect");
+  });
+});
diff --git a/tests/lib/failure-stage-model.test.ts b/tests/lib/failure-stage-model.test.ts
new file mode 100644
index 00000000000..501c6b9228e
--- /dev/null
+++ b/tests/lib/failure-stage-model.test.ts
@@ -0,0 +1,205 @@
+import { describe, expect, test } from "bun:test";
+import {
+  REQUEST_FAILURE_CAUSES,
+  REQUEST_FAILURE_STAGES,
+  causeDisposition,
+  causeEvidence,
+  causeForRecoveryKind,
+  permitsResend,
+  resendPermission,
+  resendSendClass,
+  stageCommitment,
+  stageRank,
+  type RequestFailureCause,
+  type RequestFailureStage,
+} from "../../src/lib/request-failure-model";
+import { ATTEMPT_RECOVERY_KIND_ROSTER } from "../../src/usage/log";
+
+/**
+ * Roadmap items 7 and 14. None of these cases can be satisfied by a request that returned 200:
+ * every one of them asks what the proxy would do NEXT after a specific failure, which is the
+ * question a success assertion cannot reach.
+ *
+ * They are written over the full cross product rather than over chosen examples on purpose. A
+ * table this shape is exactly where a merge of two individually correct branches goes wrong -- one
+ * adds a cause, the other adds a stage, and the cell neither author looked at is the defect. A
+ * loop over the declared rosters has no cell to miss and cannot go stale when a member is added.
+ *
+ * Holds INV-RESEND-01 from structure/overview.md.
+ */
+
+const STAGES: readonly RequestFailureStage[] = REQUEST_FAILURE_STAGES;
+const CAUSES: readonly RequestFailureCause[] = REQUEST_FAILURE_CAUSES;
+
+describe("request failure stage ordering", () => {
+  test("ranks are the declared positions, unique and gapless", () => {
+    expect(STAGES.map(stageRank)).toEqual(STAGES.map((_, index) => index));
+    expect(new Set(STAGES).size).toBe(STAGES.length);
+  });
+
+  test("exactly one stage observes output and exactly one observes an effect", () => {
+    const byCommitment = STAGES.filter(stage => stageCommitment(stage) === "output-observed");
+    const effects = STAGES.filter(stage => stageCommitment(stage) === "effect-observed");
+    expect(byCommitment).toEqual(["semantic-output"]);
+    expect(effects).toEqual(["side-effect"]);
+  });
+});
+
+describe("resend permission", () => {
+  test("an uncertain resend after output or a side effect is never automatically permitted", () => {
+    const permitted: string[] = [];
+    for (const stage of STAGES) {
+      const commitment = stageCommitment(stage);
+      if (commitment !== "output-observed" && commitment !== "effect-observed") continue;
+      for (const cause of CAUSES) {
+        const permission = resendPermission(stage, cause);
+        if (permission !== "refused-committed") permitted.push(`${stage}/${cause}=${permission}`);
+      }
+    }
+    expect(permitted).toEqual([]);
+  });
+
+  /**
+   * Stated as "neither output nor an effect" rather than "nothing at all", because a turn can
+   * settle without ever producing output. A terminal that failed on a rate limit committed nothing
+   * downstream and is safe to send again; forbidding it would be the same mistake as ranking
+   * `terminal` above `semantic-output` and calling that commitment.
+   */
+  test("no permitted resend follows observed output or an observed effect", () => {
+    const leaks: string[] = [];
+    for (const stage of STAGES) {
+      const commitment = stageCommitment(stage);
+      if (commitment !== "output-observed" && commitment !== "effect-observed") continue;
+      for (const cause of CAUSES) {
+        if (permitsResend(resendPermission(stage, cause))) leaks.push(`${stage}/${cause}`);
+      }
+    }
+    expect(leaks).toEqual([]);
+  });
+
+  /**
+   * The #4989 boundary. A stream that announced itself and produced nothing may be replaced; the
+   * first output-bearing event closes that door for every cause at once.
+   */
+  test("the prelude may still be replaced and the two observed stages may not", () => {
+    expect(resendPermission("protocol-prelude", "upstream-declined")).toBe("permitted");
+    for (const stage of ["semantic-output", "side-effect"] as const) {
+      for (const cause of CAUSES) expect(permitsResend(resendPermission(stage, cause))).toBe(false);
+    }
+  });
+
+  test("an ambiguous transport failure is refused at every stage, budget or not", () => {
+    for (const stage of STAGES) {
+      expect(permitsResend(resendPermission(stage, "transport-ambiguous"))).toBe(false);
+    }
+    expect(resendPermission("pre-header", "transport-ambiguous")).toBe("refused-ambiguous");
+    expect(resendPermission("semantic-output", "transport-ambiguous")).toBe("refused-committed");
+  });
+
+  /**
+   * Stated as a property rather than as a list of causes, because a list here would be one more
+   * hand-maintained restatement of the dictionary -- the thing these cases exist to prevent.
+   */
+  test("nothing is repeated at pre-header unless the origin provably did not run it", () => {
+    expect(resendPermission("pre-header", "transport-unsent")).toBe("permitted");
+    const unproven = CAUSES
+      .filter(cause => permitsResend(resendPermission("pre-header", cause)))
+      .filter(cause => causeEvidence(cause) !== "not-processed" && causeEvidence(cause) !== "declined");
+    expect(unproven).toEqual([]);
+  });
+
+  test("a refusal always says which kind of refusal it is", () => {
+    const refusals = new Set<string>();
+    for (const stage of STAGES) {
+      for (const cause of CAUSES) {
+        const permission = resendPermission(stage, cause);
+        if (!permitsResend(permission)) refusals.add(permission);
+      }
+    }
+    expect([...refusals].sort()).toEqual(["refused-ambiguous", "refused-committed", "refused-futile"]);
+  });
+});
+
+describe("the four refusals an operator has to tell apart", () => {
+  /**
+   * #5180 reported these arriving as one undifferentiated failure. Waiting, changing account,
+   * changing the prompt and dropping stale ciphertext are four different responses, so the
+   * decision each one produces has to differ somewhere a caller can read.
+   */
+  test("rate limit, quota exhaustion, policy refusal and ciphertext refusal never collapse", () => {
+    const quartet = ["rate-limit", "quota-exhausted", "policy-refusal", "ciphertext-refusal"] as const;
+    const decisions = quartet.map(cause => JSON.stringify([
+      causeEvidence(cause),
+      causeDisposition(cause),
+      resendSendClass(cause),
+      resendPermission("headers-only", cause),
+    ]));
+    expect(new Set(decisions).size).toBe(quartet.length);
+  });
+
+  test("each of the four keeps the decision its remedy implies", () => {
+    expect(resendPermission("headers-only", "rate-limit")).toBe("permitted");
+    expect(resendPermission("headers-only", "quota-exhausted")).toBe("refused-futile");
+    expect(resendPermission("headers-only", "policy-refusal")).toBe("refused-futile");
+    expect(resendPermission("headers-only", "ciphertext-refusal")).toBe("permitted-after-repair");
+  });
+
+  test("a rejected parameter is not a refused prompt", () => {
+    expect(causeDisposition("parameter-rejected")).toBe("resend-after-repair");
+    expect(causeDisposition("policy-refusal")).toBe("resend-is-futile");
+  });
+});
+
+describe("send funding agrees with the permission table", () => {
+  /**
+   * Funding follows the disposition, not the permission. A cause the table refuses to resend
+   * automatically may still be resent by a bounded opt-in recovery, and that send must still be
+   * bought from the request-wide budget -- an unfunded path is how a per-layer counter returns.
+   */
+  test("a budget class is named for every cause a resend could ever help", () => {
+    const disagreements: string[] = [];
+    for (const cause of CAUSES) {
+      const futile = causeDisposition(cause) === "resend-is-futile";
+      if (futile !== (resendSendClass(cause) === null)) disagreements.push(cause);
+    }
+    expect(disagreements).toEqual([]);
+  });
+
+  test("the bounded opt-in recoveries the proxy already performs are funded", () => {
+    // #4942's reset replay, the empty-completion rebuild and the transient 5xx ladder are all
+    // refused automatically and all really send, so all three need an allowance to draw on.
+    for (const cause of ["transport-ambiguous", "empty-output", "upstream-fault"] as const) {
+      expect(permitsResend(resendPermission("pre-header", cause))).toBe(false);
+      expect(resendSendClass(cause)).toBe("transient");
+    }
+  });
+});
+
+describe("recovery kinds speak the shared dictionary", () => {
+  test("every recorded recovery kind resolves to a declared cause", () => {
+    const unmapped = ATTEMPT_RECOVERY_KIND_ROSTER.filter(
+      kind => !CAUSES.includes(causeForRecoveryKind(kind)),
+    );
+    expect(unmapped).toEqual([]);
+  });
+
+  test("the kinds that drive different recoveries do not share one cause", () => {
+    expect(causeForRecoveryKind("opaque-blob-rejection")).toBe("ciphertext-refusal");
+    expect(causeForRecoveryKind("image-413")).toBe("payload-too-large");
+    expect(causeForRecoveryKind("connection-reset")).toBe("transport-ambiguous");
+    expect(causeForRecoveryKind("transient-5xx")).toBe("upstream-fault");
+    expect(causeForRecoveryKind("reasoning-effort-downgrade")).toBe("parameter-rejected");
+  });
+
+  /**
+   * Every kind in the roster names a recovery this proxy actually performs, so none of them may
+   * classify as futile. The first draft put the 413 image rebuild and the gateway upload replay
+   * under a futile cause, which would have had the shared model assert that recoveries visible in
+   * the durable log were forbidden and unfunded.
+   */
+  test("no recorded recovery classifies as a resend that cannot help", () => {
+    const futile = ATTEMPT_RECOVERY_KIND_ROSTER
+      .filter(kind => causeDisposition(causeForRecoveryKind(kind)) === "resend-is-futile");
+    expect(futile).toEqual([]);
+  });
+});
diff --git a/tests/lib/provider-egress.test.ts b/tests/lib/provider-egress.test.ts
new file mode 100644
index 00000000000..000b7b1a6a2
--- /dev/null
+++ b/tests/lib/provider-egress.test.ts
@@ -0,0 +1,183 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import {
+  InvalidProviderEgressError,
+  PROVIDER_EGRESS_DIRECT,
+  describeProviderEgressForLog,
+  providerEgressConfigError,
+  providerEgressFetchInit,
+  providerEgressIsExplicit,
+  resolveProviderEgress,
+  sanitizeProxyUrlForLog,
+} from "../../src/lib/provider-egress";
+import { PROXY_ENV_KEYS, configuredOutboundFetch } from "../../src/lib/proxy-env";
+
+const proxyKeys = PROXY_ENV_KEYS.flatMap(key => [key, key.toLowerCase()]);
+const originalProxyEnv = Object.fromEntries(proxyKeys.map(key => [key, process.env[key]]));
+
+afterEach(() => {
+  for (const key of proxyKeys) {
+    const previous = originalProxyEnv[key];
+    if (previous === undefined) delete process.env[key];
+    else process.env[key] = previous;
+  }
+});
+
+const TARGET = "https://api.provider.example/v1/responses";
+
+function resolve(provider: { proxy?: string | null; noProxy?: string | string[] }, url = TARGET) {
+  return resolveProviderEgress({ providerName: "vendor", provider, url });
+}
+
+describe("provider egress resolution", () => {
+  test("an absent field inherits the global decision rather than choosing a route", () => {
+    const egress = resolve({});
+    expect(egress).toEqual({ kind: "inherit" });
+    expect(providerEgressIsExplicit(egress)).toBe(false);
+    // Inheriting must contribute no request option at all: a provider that says nothing has to
+    // leave the global proxy decision byte-identical to what it was before this field existed.
+    expect(providerEgressFetchInit(egress)).toEqual({});
+  });
+
+  test("the direct keyword and null both refuse the global proxy", () => {
+    for (const value of [PROVIDER_EGRESS_DIRECT, PROVIDER_EGRESS_DIRECT.toUpperCase(), null] as const) {
+      const egress = resolve({ proxy: value });
+      expect(egress).toEqual({ kind: "direct", reason: "configured" });
+      expect(providerEgressIsExplicit(egress)).toBe(true);
+    }
+  });
+
+  test("an http(s) URL routes this provider through its own proxy", () => {
+    expect(resolve({ proxy: "http://egress.example:3128" })).toEqual({
+      kind: "proxy", proxyUrl: "http://egress.example:3128/", transport: "http",
+    });
+    // An https proxy is still the HTTP(S) CONNECT transport; `transport` names the transport
+    // family the request is handed to, not the proxy's own scheme.
+    expect(resolve({ proxy: "https://egress.example:3129" })).toEqual({
+      kind: "proxy", proxyUrl: "https://egress.example:3129/", transport: "http",
+    });
+  });
+
+  test("a socks5 URL is carried verbatim so the SOCKS transport can parse it", () => {
+    // Not normalized through URL.toString(): the SOCKS transport validates the original value,
+    // including credentials and the socks5h variant, and a reserialized URL is not guaranteed
+    // to round-trip the userinfo it was given.
+    for (const value of ["socks5://127.0.0.1:1080", "socks5h://127.0.0.1:1080"]) {
+      expect(resolve({ proxy: value })).toEqual({ kind: "proxy", proxyUrl: value, transport: "socks5" });
+    }
+  });
+
+  test("a provider noProxy match forces direct egress out of the provider's own proxy", () => {
+    const provider = { proxy: "http://egress.example:3128", noProxy: "internal.example" };
+    expect(resolve(provider, "https://internal.example/v1/models"))
+      .toEqual({ kind: "direct", reason: "noProxy" });
+    // A destination the list does not name still takes the provider's proxy.
+    expect(resolve(provider).kind).toBe("proxy");
+  });
+
+  test("a provider noProxy match also carves an exemption out of an inherited global proxy", () => {
+    // This is the case a provider-level proxy cannot express: the provider owns no route of its
+    // own and only needs one destination kept off the global one.
+    expect(resolve({ noProxy: ["internal.example", "10.0.0.1"] }, "https://internal.example/v1/models"))
+      .toEqual({ kind: "direct", reason: "noProxy" });
+    expect(resolve({ noProxy: ["internal.example"] })).toEqual({ kind: "inherit" });
+  });
+
+  test("an empty value is refused instead of being read as either neighbour", () => {
+    // The failure this prevents: a cleared dashboard field silently switching a provider from
+    // "inherit the global proxy" to "never use it", or the reverse. Both read as success.
+    for (const value of ["", "   "]) {
+      expect(() => resolve({ proxy: value })).toThrow(InvalidProviderEgressError);
+    }
+    const message = providerEgressConfigError({ proxy: "" });
+    expect(message).toContain(PROVIDER_EGRESS_DIRECT);
+  });
+
+  test("a malformed or unsupported value throws rather than degrading to a working route", () => {
+    for (const value of ["not a url", "ftp://egress.example", "://", "socks4://127.0.0.1:1080"]) {
+      expect(() => resolve({ proxy: value })).toThrow(InvalidProviderEgressError);
+      expect(providerEgressConfigError({ proxy: value })).not.toBeNull();
+    }
+    expect(() => resolve({ proxy: 42 as unknown as string })).toThrow(InvalidProviderEgressError);
+    expect(providerEgressConfigError({ noProxy: [7 as unknown as string] })).not.toBeNull();
+  });
+
+  test("configuration and request time share one definition of a valid value", () => {
+    // Two definitions would drift, and nothing would compare them. A value the loader accepts
+    // has to be one a request can actually leave by.
+    for (const value of [PROVIDER_EGRESS_DIRECT, "http://egress.example:3128", "socks5://127.0.0.1:1080"]) {
+      expect(providerEgressConfigError({ proxy: value })).toBeNull();
+      expect(() => resolve({ proxy: value })).not.toThrow();
+    }
+    expect(providerEgressConfigError({})).toBeNull();
+  });
+});
+
+describe("provider egress never reproduces a proxy credential", () => {
+  test("log output keeps scheme, host and port and drops everything else", () => {
+    // A `.test` host, because a credentialed proxy URL reads as `password@host` to the privacy
+    // scanner and that domain is on its allowed list for fixtures.
+    const secret = "http://operator:hunter2@egress.test:3128/path?token=abc";
+    const label = sanitizeProxyUrlForLog(secret);
+    expect(label).toBe("http://egress.test:3128");
+    for (const fragment of ["operator", "hunter2", "token", "abc"]) {
+      expect(label).not.toContain(fragment);
+    }
+  });
+
+  test("the described route carries no digest of the credential either", () => {
+    // A short hash over a known host is a guessable stand-in for the secret and a durable
+    // correlation key for the account behind it, so the description derives nothing from it.
+    const described = describeProviderEgressForLog(resolve({ proxy: "http://operator:hunter2@egress.test:3128" }));
+    expect(described).toBe("http(http://egress.test:3128)");
+    expect(described).not.toContain("hunter2");
+    expect(describeProviderEgressForLog({ kind: "inherit" })).toBe("inherit");
+    expect(describeProviderEgressForLog({ kind: "direct", reason: "noProxy" })).toBe("direct(noProxy)");
+  });
+
+  test("an unparseable value is labelled without being echoed", () => {
+    const label = sanitizeProxyUrlForLog("operator hunter2 not a url");
+    expect(label).toBe("<unparseable-proxy-url>");
+    expect(label).not.toContain("hunter2");
+  });
+});
+
+describe("direct egress overrides the installed SOCKS transport", () => {
+  test("a request pinned to direct is not sent through the global SOCKS proxy", async () => {
+    // The regression: `proxy: false` is not a string, so reading it as "no explicit proxy was
+    // supplied" fell through to ALL_PROXY and sent a request the caller pinned to direct egress
+    // through the global SOCKS proxy instead. The request would have succeeded, by the wrong exit.
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.ALL_PROXY = "socks5://127.0.0.1:1";
+    const base = mock(async (_input: RequestInfo | URL, init?: RequestInit) => {
+      return new Response(JSON.stringify({ proxy: (init as { proxy?: unknown }).proxy ?? null }), { status: 200 });
+    });
+    const response = await configuredOutboundFetch(
+      TARGET,
+      providerEgressFetchInit(resolve({ proxy: PROVIDER_EGRESS_DIRECT })) as RequestInit,
+      base as unknown as typeof globalThis.fetch,
+    );
+    expect(base).toHaveBeenCalledTimes(1);
+    // Bun reads `false` as "connect directly", overriding HTTP_PROXY, HTTPS_PROXY, ALL_PROXY
+    // and NO_PROXY alike. `undefined`, `null` and `""` all mean "no option" and fall back to
+    // the environment, so none of them can express this.
+    expect(await response.json()).toEqual({ proxy: false });
+  });
+
+  test("an inheriting provider still reaches the global SOCKS transport unchanged", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    // Port 0 is rejected by the SOCKS transport's own validation before any socket is opened,
+    // so the outcome does not depend on what happens to be listening on the test host. What is
+    // asserted is which transport took the request, not that it succeeded.
+    process.env.ALL_PROXY = "socks5://127.0.0.1:0";
+    const base = mock(async () => new Response(null, { status: 200 }));
+    // With no explicit option the SOCKS wrapper owns the request, so the base fetch below is
+    // never reached. Asserting that keeps this change from quietly disabling global SOCKS.
+    const outcome = await configuredOutboundFetch(
+      TARGET,
+      providerEgressFetchInit(resolve({})) as RequestInit,
+      base as unknown as typeof globalThis.fetch,
+    ).then(() => "base-fetch-used", () => "socks-transport-owned-the-request");
+    expect(outcome).toBe("socks-transport-owned-the-request");
+    expect(base).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/lib/standalone.test.ts b/tests/lib/standalone.test.ts
new file mode 100644
index 00000000000..d58c3a7aa0d
--- /dev/null
+++ b/tests/lib/standalone.test.ts
@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test";
+import { dirname } from "node:path";
+import { realpathSync } from "node:fs";
+import {
+  isStandaloneBinary,
+  isStandaloneModuleUrl,
+  standaloneRoot,
+} from "../../src/lib/standalone";
+
+test("source Bun processes are not identified as compiled binaries", () => {
+  expect(isStandaloneBinary()).toBe(false);
+});
+
+test("compiled module URL markers are recognized on POSIX and Windows", () => {
+  expect(isStandaloneModuleUrl("file:///$bunfs/root/src/cli/index.ts")).toBe(true);
+  expect(isStandaloneModuleUrl("file:///B:/~BUN/root/src/cli/index.ts")).toBe(true);
+  expect(isStandaloneModuleUrl("file:///Users/x/src/lib/standalone.ts")).toBe(false);
+});
+
+test("standaloneRoot follows the running executable", () => {
+  expect(standaloneRoot()).toBe(dirname(realpathSync(process.execPath)));
+});
diff --git a/tests/lib/upstream-retry.test.ts b/tests/lib/upstream-retry.test.ts
index e8d09b309e3..f55d8ecf300 100644
--- a/tests/lib/upstream-retry.test.ts
+++ b/tests/lib/upstream-retry.test.ts
@@ -509,6 +509,101 @@ describe("ambiguous reset safety", () => {
   });
 });
 
+describe("operator-granted replacement of an ambiguous reset", () => {
+  test("no claim callback keeps the refusal and never sends again", async () => {
+    const mock = mockDoFetch([bunResetError(), new Response("duplicate")]);
+    const response = await fetchWithResetRetry(mock.doFetch, { attempts: 3 });
+    expect(response.status).toBe(429);
+    expect(mock.calls).toHaveLength(1);
+  });
+
+  test("a granted claim buys exactly one more send and is asked exactly once", async () => {
+    silenceWarn();
+    const reports: number[] = [];
+    let asked = 0;
+    const mock = mockDoFetch([bunResetError(), new Response("ok")]);
+    const response = await fetchWithResetRetry(mock.doFetch, {
+      attempts: 3,
+      onSendsConsumed: count => reports.push(count),
+      claimAmbiguousResend: () => { asked += 1; return asked === 1; },
+    });
+    expect(await response.text()).toBe("ok");
+    expect(mock.calls).toHaveLength(2);
+    expect(asked).toBe(1);
+    expect(reports).toEqual([1, 1]);
+  });
+
+  test("a spent grant settles as the refusal rather than sending again", async () => {
+    silenceWarn();
+    const mock = mockDoFetch([bunResetError(), bunResetError(), new Response("duplicate")]);
+    const response = await fetchWithResetRetry(mock.doFetch, {
+      attempts: 3,
+      // The shape a request-wide allowance of one produces on its second question.
+      claimAmbiguousResend: (() => { let left = 1; return () => left-- > 0; })(),
+    });
+    expect(response.status).toBe(429);
+    expect(isNonReplayableResponse(response)).toBe(true);
+    expect((await response.json()).error.code).toBe(UPSTREAM_RESET_REPLAY_REFUSED_CODE);
+    expect(mock.calls).toHaveLength(2);
+  });
+
+  test("the grant never widens the send budget it was given", async () => {
+    const mock = mockDoFetch([bunResetError(), new Response("duplicate")]);
+    let asked = 0;
+    const response = await fetchWithResetRetry(mock.doFetch, {
+      attempts: 1,
+      claimAmbiguousResend: () => { asked += 1; return true; },
+    });
+    expect(response.status).toBe(429);
+    expect(mock.calls).toHaveLength(1);
+    // Asking would have spent the request's one replacement on a send there was no room for.
+    expect(asked).toBe(0);
+  });
+
+  test("a replay-safe operation never consults the grant", async () => {
+    silenceWarn();
+    let asked = 0;
+    const mock = mockDoFetch([bunResetError(), new Response("ok")]);
+    const response = await fetchWithResetRetry(mock.doFetch, {
+      attempts: 3, replaySafe: true, claimAmbiguousResend: () => { asked += 1; return true; },
+    });
+    expect(await response.text()).toBe("ok");
+    expect(asked).toBe(0);
+  });
+
+  test("a non-reset failure after a replacement settles as the refusal, not a rejection", async () => {
+    silenceWarn();
+    // The hazard the refusal exists for: a thrown transport error here becomes a 502 at the
+    // caller, and a 502 is what the Codex client retries -- so the turn whose first send may
+    // already have run would be sent again, four more times.
+    const mock = mockDoFetch([bunResetError(), new Error("upstream fetch failed")]);
+    const response = await fetchWithResetRetry(mock.doFetch, {
+      attempts: 3, claimAmbiguousResend: () => true,
+    });
+    expect(response.status).toBe(429);
+    expect(isNonReplayableResponse(response)).toBe(true);
+    expect((await response.json()).error.code).toBe(UPSTREAM_RESET_REPLAY_REFUSED_CODE);
+    expect(mock.calls).toHaveLength(2);
+  });
+
+  test("the transient layer carries the grant into its inner reset layer", async () => {
+    silenceWarn();
+    const reports: number[] = [];
+    const mock = mockDoFetch([
+      new Response("busy", { status: 503 }), bunResetError(), new Response("ok"),
+    ]);
+    const response = await fetchWithTransientRetry(mock.doFetch, {
+      attempts: 3,
+      onSendsConsumed: count => reports.push(count),
+      claimAmbiguousResend: () => true,
+    });
+    expect(await response.text()).toBe("ok");
+    expect(mock.calls).toHaveLength(3);
+    // One report, from the one layer that owns the budget: three sends, counted once each.
+    expect(reports).toEqual([3]);
+  });
+});
+
 describe("ambiguous reset safety through error formatting", () => {
   test("every terminal code survives formatting without advertising Retry-After", async () => {
     for (const code of ["upstream_no_response", "upstream_closed_before_response", "upstream_reset_replay_refused"]) {
diff --git a/tests/oauth/oauth-login-cli-browser-launch.test.ts b/tests/oauth/oauth-login-cli-browser-launch.test.ts
new file mode 100644
index 00000000000..1efad4b987b
--- /dev/null
+++ b/tests/oauth/oauth-login-cli-browser-launch.test.ts
@@ -0,0 +1,242 @@
+/**
+ * #5261 remainder: the two CLI logins that still discarded the launcher's answer.
+ *
+ * The landed half taught `openUrl` to say whether anything started, and the Codex account login
+ * to print it. `ocx login <oauth-provider>` and `ocx login <key-provider>` kept calling
+ * `void openUrl(...)`, so on a host with no browser both printed a URL, claimed to be opening
+ * it, and then asked a question that assumes it opened. The user waits at a prompt that looks
+ * like progress.
+ *
+ * What these assert is the ORDER, not merely the presence of a warning. The OAuth controller
+ * does not await `onAuth`, so the launcher answers after the login flow has moved on — on a
+ * callback-server provider, after it has already drawn a readline prompt. A warning that lands
+ * there is written over the line the user is typing on, which is why "it warns eventually" is
+ * not the contract.
+ *
+ * Nothing here opens a browser or attaches to stdin: both are injected, which is the only way
+ * two events can be observed in sequence at all.
+ */
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { saveConfig } from "../../src/config";
+import { handleKeyLogin, handleOAuthLogin, type LoginCliDeps } from "../../src/oauth/login-cli";
+import { KEY_LOGIN_PROVIDERS } from "../../src/oauth/key-providers";
+import { listOAuthProviders } from "../../src/oauth";
+import { BROWSER_LAUNCH_FAILED_NOTICE, createBrowserLaunchReport } from "../../src/lib/browser-launch-notice";
+import { BROWSER_LAUNCH_FAILED_HINT } from "../../src/cli/account-auth";
+import { repoPath } from "../helpers/repo-root";
+import { readFileSync } from "node:fs";
+import type { OpenUrlResult } from "../../src/lib/open-url";
+import type { OAuthCredentials } from "../../src/oauth/types";
+import type { OcxConfig } from "../../src/types";
+import { installIsolatedCodexHome, type IsolatedCodexHome } from "../helpers/isolated-codex-home";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+let testDir = "";
+let previousHome: string | undefined;
+let isolatedCodexHome: IsolatedCodexHome | null = null;
+let logSpy: { mockRestore(): void } | null = null;
+
+type FakeRunLogin = NonNullable<LoginCliDeps["runLogin"]>;
+
+/** Named from the roster rather than typed in, so a renamed provider cannot leave this passing. */
+function anyOAuthProvider(): string {
+  const [first] = listOAuthProviders();
+  if (!first) throw new Error("no OAuth providers are registered");
+  return first;
+}
+
+/** A key provider whose baseUrl needs no placeholder resolution, so one prompt ends the flow. */
+function anyDirectKeyProvider(): string {
+  const found = Object.entries(KEY_LOGIN_PROVIDERS).find(([, def]) => !/\{[^}]*\}/.test(def.baseUrl));
+  if (!found) throw new Error("no key-login provider has a resolved baseUrl");
+  return found[0];
+}
+
+beforeEach(() => {
+  previousHome = process.env.OPENCODEX_HOME;
+  isolatedCodexHome = installIsolatedCodexHome("ocx-login-launch-codex-");
+  testDir = mkdtempSync(join(tmpdir(), "ocx-login-launch-"));
+  process.env.OPENCODEX_HOME = testDir;
+  // The one row exists so the config validates; it is deliberately not the provider under test,
+  // which keeps the post-login live-reload notify from looking for a proxy. An empty table would
+  // fail validation and be silently replaced by the packaged default, whose contents this has no
+  // reason to depend on.
+  saveConfig({
+    port: 0,
+    hostname: "127.0.0.1",
+    defaultProvider: "login-launch-stub",
+    providers: {
+      "login-launch-stub": {
+        adapter: "openai-chat",
+        baseUrl: "https://stub.invalid/v1",
+        apiKey: "sk-login-launch-stub",
+      },
+    },
+  } as OcxConfig);
+  logSpy = spyOn(console, "log").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  logSpy?.mockRestore();
+  logSpy = null;
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  isolatedCodexHome?.restore();
+  isolatedCodexHome = null;
+  if (testDir) removeTreeWithRetry(testDir);
+  testDir = "";
+});
+
+describe("CLI OAuth login reports the browser launch (#5261)", () => {
+  test("a browser that never opened is on screen before the paste prompt", async () => {
+    const events: string[] = [];
+    let settleLaunch: (result: OpenUrlResult) => void = () => {};
+    const launch = new Promise<OpenUrlResult>(resolve => { settleLaunch = resolve; });
+    const login: FakeRunLogin = async (_provider, ctrl) => {
+      ctrl.onAuth?.({ url: "https://accounts.example.test/authorize?state=1" });
+      // The launcher answers only after onAuth has returned. That gap is the defect: the old
+      // code had already discarded the promise by this point.
+      settleLaunch({ status: "failed", reason: "launcher-exit" });
+      expect(await ctrl.onManualCodeInput?.()).toBe("pasted-code");
+      return {} as OAuthCredentials;
+    };
+
+    await handleOAuthLogin(anyOAuthProvider(), {
+      runLogin: login,
+      openUrl: () => launch,
+      warn: message => { events.push(`warn:${message}`); },
+      ask: async () => { events.push("ask"); return "pasted-code"; },
+    });
+
+    expect(events).toEqual([`warn:\n${BROWSER_LAUNCH_FAILED_NOTICE}`, "ask"]);
+  });
+
+  test("a browser that did open adds nothing to the prompt", async () => {
+    // A non-regression guard rather than proof of the fix: it passed before this change too, and
+    // it is here so the new warning cannot start firing on a launch that worked.
+    const events: string[] = [];
+    const login: FakeRunLogin = async (_provider, ctrl) => {
+      ctrl.onAuth?.({ url: "https://accounts.example.test/authorize?state=2" });
+      await ctrl.onManualCodeInput?.();
+      return {} as OAuthCredentials;
+    };
+
+    await handleOAuthLogin(anyOAuthProvider(), {
+      runLogin: login,
+      openUrl: async () => ({ status: "started" }),
+      warn: message => { events.push(`warn:${message}`); },
+      ask: async () => { events.push("ask"); return "pasted-code"; },
+    });
+
+    expect(events).toEqual(["ask"]);
+  });
+
+  test("a polling flow that never prompts is still told the launch failed", async () => {
+    // Device and polling providers publish a URL and then wait. Nothing asks a question, so
+    // nothing there would have waited on the launcher; the answer is still owed before the
+    // login claims to have worked.
+    const events: string[] = [];
+    const login: FakeRunLogin = async (_provider, ctrl) => {
+      ctrl.onAuth?.({ url: "https://device.example.test/activate", deviceCode: "WDJB-MJHT" });
+      ctrl.onProgress?.("Waiting for approval...");
+      return {} as OAuthCredentials;
+    };
+
+    await handleOAuthLogin(anyOAuthProvider(), {
+      runLogin: login,
+      openUrl: async () => ({ status: "failed", reason: "spawn-error" }),
+      warn: () => { events.push("warn"); },
+      ask: async () => { events.push("ask"); return ""; },
+    });
+
+    expect(events).toEqual(["warn"]);
+  });
+
+  test("a launcher that throws is reported, not turned into a failed login", async () => {
+    // openUrl documents that it never rejects, but this seam accepts any launcher. A rejection
+    // here used to travel out through settled(), which a polling flow does not await until the
+    // whole login has finished — so it would surface as an unhandled rejection and take down a
+    // login that could still have completed by hand.
+    const events: string[] = [];
+    const login: FakeRunLogin = async (_provider, ctrl) => {
+      ctrl.onAuth?.({ url: "https://accounts.example.test/authorize?state=3" });
+      ctrl.onProgress?.("Waiting for browser authentication...");
+      return {} as OAuthCredentials;
+    };
+
+    await handleOAuthLogin(anyOAuthProvider(), {
+      runLogin: login,
+      openUrl: async () => { throw new Error("launcher blew up"); },
+      warn: () => { events.push("warn"); },
+      ask: async () => { events.push("ask"); return ""; },
+    });
+
+    expect(events).toEqual(["warn"]);
+  });
+});
+
+describe("CLI key login reports the dashboard launch (#5261)", () => {
+  test("a dashboard that never opened is on screen before the key prompt", async () => {
+    const events: string[] = [];
+    const errors: string[] = [];
+    const errorSpy = spyOn(console, "error").mockImplementation((...parts: unknown[]) => {
+      errors.push(parts.join(" "));
+    });
+    const exitSpy = spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`process.exit:${code}`);
+    }) as never);
+
+    try {
+      await expect(handleKeyLogin(anyDirectKeyProvider(), {
+        openUrl: async () => ({ status: "failed", reason: "launcher-exit" }),
+        warn: () => { events.push("warn"); },
+        // An empty key ends the flow immediately after the prompt. The key path beyond it is
+        // already covered where it lives; what this case is about is what precedes the question.
+        ask: async () => { events.push("ask"); return ""; },
+      })).rejects.toThrow("process.exit:1");
+    } finally {
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+
+    expect(events).toEqual(["warn", "ask"]);
+    expect(errors).toContain("No key entered.");
+  });
+});
+
+describe("the launch report is one sentence and one order", () => {
+  test("settled() cannot resolve before the warning is written", async () => {
+    const events: string[] = [];
+    let settleLaunch: (result: OpenUrlResult) => void = () => {};
+    const launch = new Promise<OpenUrlResult>(resolve => { settleLaunch = resolve; });
+    const report = createBrowserLaunchReport(() => { events.push("warn"); });
+
+    report.track(launch);
+    const waited = report.settled().then(() => { events.push("prompt"); });
+    settleLaunch({ status: "failed", reason: "invalid-url" });
+    await waited;
+
+    expect(events).toEqual(["warn", "prompt"]);
+  });
+
+  test("a report with nothing tracked resolves rather than hanging", async () => {
+    const events: string[] = [];
+    await createBrowserLaunchReport(() => { events.push("warn"); }).settled();
+    expect(events).toEqual([]);
+  });
+
+  test("the Codex account hint extends the shared notice instead of holding its own copy", () => {
+    // Asserting only that the strings agree would pass on a second copy that happens to match
+    // today, which is the state this replaced. The source is read as well, so the sentence has
+    // exactly one home and a later edit to it cannot reach two thirds of the logins.
+    expect(BROWSER_LAUNCH_FAILED_HINT.startsWith(BROWSER_LAUNCH_FAILED_NOTICE)).toBe(true);
+    expect(BROWSER_LAUNCH_FAILED_HINT.length).toBeGreaterThan(BROWSER_LAUNCH_FAILED_NOTICE.length);
+
+    const accountAuth = readFileSync(repoPath("src", "cli", "account-auth.ts"), "utf8");
+    expect(accountAuth).toContain("BROWSER_LAUNCH_FAILED_NOTICE");
+    expect(accountAuth).not.toContain(BROWSER_LAUNCH_FAILED_NOTICE);
+  });
+});
diff --git a/tests/oauth/oauth-login-open-browser.test.ts b/tests/oauth/oauth-login-open-browser.test.ts
index 0b7928d2195..676641a305e 100644
--- a/tests/oauth/oauth-login-open-browser.test.ts
+++ b/tests/oauth/oauth-login-open-browser.test.ts
@@ -33,7 +33,7 @@ async function startLogin(flow: { url: string; instructions?: string; deviceCode
   const openUrlMod = await import("../../src/lib/open-url");
   const opened: string[] = [];
   const startSpy = spyOn(oauth, "startLoginFlow").mockResolvedValue(flow);
-  const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation((url: string) => { opened.push(url); });
+  const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(async (url: string) => { opened.push(url); return { status: "started" as const }; });
   try {
     const req = loginRequest("kimi");
     const response = await handleOauthAccountRoutes({
diff --git a/tests/oauth/oauth-open-browser-choice.test.ts b/tests/oauth/oauth-open-browser-choice.test.ts
index 48c7f542788..81c133bb028 100644
--- a/tests/oauth/oauth-open-browser-choice.test.ts
+++ b/tests/oauth/oauth-open-browser-choice.test.ts
@@ -49,7 +49,7 @@ async function startLogin(
   const openUrlMod = await import("../../src/lib/open-url");
   const opened: string[] = [];
   const startSpy = spyOn(oauth, "startLoginFlow").mockResolvedValue({ url: "https://accounts.x.ai/oauth/authorize?code_challenge=x" });
-  const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation((url: string) => { opened.push(url); });
+  const openSpy = spyOn(openUrlMod, "openUrl").mockImplementation(async (url: string) => { opened.push(url); return { status: "started" as const }; });
   try {
     const req = new Request("http://127.0.0.1/api/oauth/login", {
       method: "POST",
diff --git a/tests/oauth/oauth-open-url-result.test.ts b/tests/oauth/oauth-open-url-result.test.ts
new file mode 100644
index 00000000000..17ca2d97fdb
--- /dev/null
+++ b/tests/oauth/oauth-open-url-result.test.ts
@@ -0,0 +1,55 @@
+/**
+ * #5261: a browser that never opened must not look like a login that is working.
+ *
+ * The launcher used to swallow its own failure and return nothing, which is what left the Codex
+ * login route unable to tell a browser that opened from one that never did. These cover the
+ * launcher itself and the recovery line it feeds; the route and the CLI block that consume the
+ * result are covered where those live.
+ *
+ * Nothing here opens a real browser. The started case is deliberately untested rather than
+ * faked: the launcher command is fixed per platform, so proving it would mean actually
+ * launching one on the machine running the suite.
+ */
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { tmpdir } from "node:os";
+import { openUrl } from "../../src/lib/open-url";
+import { BROWSER_LAUNCH_FAILED_HINT } from "../../src/cli/account-auth";
+
+describe("browser launch is reported, not swallowed (#5261)", () => {
+  test("a URL we will not hand to a launcher is reported as such", async () => {
+    // Refusing a non-http scheme is the one failure that never reaches spawn, so it is also
+    // the one that must not silently look like a launch.
+    for (const url of ["", "not-a-url", "file:///etc/passwd", "javascript:alert(1)"]) {
+      expect(await openUrl(url)).toEqual({ status: "failed", reason: "invalid-url" });
+    }
+  });
+
+  test.skipIf(process.platform !== "linux")("a launcher that cannot be resolved reports a failure", async () => {
+    // Linux only, and on purpose: this empties PATH so the launcher cannot be found, and on a
+    // developer machine with a real browser any weaker setup risks actually opening one.
+    const priorPath = process.env.PATH;
+    let emptyDir: string | undefined;
+    try {
+      emptyDir = mkdtempSync(`${tmpdir()}/ocx-empty-path-`);
+      process.env.PATH = emptyDir;
+      expect(await openUrl("http://127.0.0.1:1455/auth/callback")).toEqual({
+        status: "failed",
+        reason: "spawn-error",
+      });
+    } finally {
+      if (priorPath === undefined) delete process.env.PATH;
+      else process.env.PATH = priorPath;
+      if (emptyDir) removeTreeWithRetry(emptyDir);
+    }
+  });
+
+  test("the CLI hint names the manual route and the reason the port cannot move", () => {
+    // ChatGPT supplies the redirect URI, so the callback cannot move to a free port. That is
+    // the part a user cannot work out alone, which is why the hint names it and --device.
+    expect(BROWSER_LAUNCH_FAILED_HINT).toContain("1455");
+    expect(BROWSER_LAUNCH_FAILED_HINT).toContain("--device");
+    expect(BROWSER_LAUNCH_FAILED_HINT.toLowerCase()).toContain("open the url");
+  });
+});
diff --git a/tests/oauth/oauth-provider-reconcile.test.ts b/tests/oauth/oauth-provider-reconcile.test.ts
index fe624a54f70..8e8a1b67afd 100644
--- a/tests/oauth/oauth-provider-reconcile.test.ts
+++ b/tests/oauth/oauth-provider-reconcile.test.ts
@@ -504,6 +504,43 @@ describe("OAuth provider reconciliation", () => {
     expect(config.providers.kimi.requiresReasoningPlaceholderModels).toEqual([]);
   });
 
+  test("preserves an operator output budget that no OAuth preset declares", () => {
+    // The devin preset declares neither output field, so the delete branch was
+    // the only branch either of them ever took: a hand-edited budget was gone
+    // before the next startup finished, leaving the adapter's own fallback as
+    // the only reachable cap (#5190). Reconciliation still owns the input-side
+    // catalog, which is why modelContextWindows is asserted alongside.
+    const preset = OAUTH_PROVIDERS.devin.providerConfig;
+    expect(preset.defaultMaxOutputTokens).toBeUndefined();
+    expect(preset.modelMaxOutputTokens).toBeUndefined();
+    const config = {
+      port: 10100,
+      defaultProvider: "devin",
+      googleAntigravityStaticCatalogVersion: 1,
+      providers: {
+        devin: {
+          ...structuredClone(preset),
+          defaultMaxOutputTokens: 64_000,
+          modelMaxOutputTokens: { "swe-2": 32_000 },
+          modelContextWindows: { "swe-2": 1 },
+        },
+      },
+    } satisfies OcxConfig;
+
+    reconcileOAuthProviders(config, false);
+
+    expect(config.providers.devin.defaultMaxOutputTokens).toBe(64_000);
+    expect(config.providers.devin.modelMaxOutputTokens).toEqual({ "swe-2": 32_000 });
+    expect(config.providers.devin.modelContextWindows).toEqual(preset.modelContextWindows!);
+
+    // A preset that does declare a budget still refreshes the saved row: this
+    // is a narrower delete branch, not an exemption from reconciliation.
+    config.providers.devin.defaultMaxOutputTokens = 1;
+    reconcileOAuthProviders(config, false);
+    expect(config.providers.devin.defaultMaxOutputTokens).toBe(1);
+    expect(OAUTH_PROVIDERS.anthropic.providerConfig.defaultMaxOutputTokens).toBeGreaterThan(0);
+  });
+
   test("refreshes Grok 4.6 levels while runtime fills the default without overwriting user intent", () => {
     const home = mkdtempSync(join(tmpdir(), "ocx-grok-46-reconcile-"));
     homes.push(home);
diff --git a/tests/providers/codebuddy-adapter.test.ts b/tests/providers/codebuddy-adapter.test.ts
index ea877f4a3eb..f68322752c5 100644
--- a/tests/providers/codebuddy-adapter.test.ts
+++ b/tests/providers/codebuddy-adapter.test.ts
@@ -252,6 +252,37 @@ describe("codebuddy runTurn streams a headless turn", () => {
     expect(JSON.stringify(events)).not.toContain("secret-command");
   });
 
+  test("the projected history ceiling follows the model context window", async () => {
+    const stdout = [
+      enc.encode('{"type":"system","subtype":"init"}\n'),
+      enc.encode('{"type":"result","subtype":"success","is_error":false,"usage":{"input_tokens":7,"output_tokens":2}}\n'),
+    ];
+    const history = Array.from({ length: 5 }, (_, index) => ({
+      role: "user" as const,
+      content: "EARLY-MARKER-" + String(index) + " " + "a".repeat(50_000),
+      timestamp: index,
+    }));
+    const messages = [...history, { role: "user", content: "final request", timestamp: 5 }];
+
+    const wide = fakeChild(stdout);
+    const wideAdapter = createCodeBuddyAdapter(
+      provider({ modelContextWindows: { "glm-5.3": 1_000_000 } }),
+      { spawn: () => wide as unknown as ChildProcess, which: () => "/usr/bin/codebuddy", killGraceMs: 20 },
+    );
+    await run(wideAdapter, parsed({ context: { messages } }));
+    expect(wide.written.join("")).toContain("EARLY-MARKER-0");
+    expect(wide.written.join("")).not.toContain("truncated for length");
+
+    const flat = fakeChild(stdout);
+    const flatAdapter = createCodeBuddyAdapter(
+      provider(),
+      { spawn: () => flat as unknown as ChildProcess, which: () => "/usr/bin/codebuddy", killGraceMs: 20 },
+    );
+    await run(flatAdapter, parsed({ context: { messages } }));
+    expect(flat.written.join("")).not.toContain("EARLY-MARKER-0");
+    expect(flat.written.join("")).toContain("truncated for length");
+  });
+
   test.each(["Bash", "exec", "shell", "apply_patch"])("refuses a bare %s DSML invoke", name => {
     const events: AdapterEvent[] = [];
     const guarded = guardCodeBuddyScaffolding(event => events.push(event));
diff --git a/tests/providers/codebuddy-protocol.test.ts b/tests/providers/codebuddy-protocol.test.ts
index a51cb1ea7b4..5c3b4c8db29 100644
--- a/tests/providers/codebuddy-protocol.test.ts
+++ b/tests/providers/codebuddy-protocol.test.ts
@@ -1,9 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import {
+  MAX_PROJECTED_HISTORY_CHARS,
   buildConversationInput,
   buildInputLines,
   buildSystemPrompt,
   mapStreamMessageToEvents,
+  projectedHistoryCharLimit,
   readJsonLines,
   usageFromResult,
 } from "../../src/adapters/coding-agent/protocol";
@@ -352,3 +354,41 @@ describe("codebuddy conversation input builder (Strategy C projection)", () => {
     });
   });
 });
+describe("projected history ceiling derives from the model context window", () => {
+  test("absent or invalid window metadata keeps the legacy flat cap", () => {
+    expect(projectedHistoryCharLimit(undefined)).toBe(MAX_PROJECTED_HISTORY_CHARS);
+    expect(projectedHistoryCharLimit(Number.NaN)).toBe(MAX_PROJECTED_HISTORY_CHARS);
+    expect(projectedHistoryCharLimit(0)).toBe(MAX_PROJECTED_HISTORY_CHARS);
+    expect(projectedHistoryCharLimit(-1)).toBe(MAX_PROJECTED_HISTORY_CHARS);
+  });
+
+  test("a small window never lowers the cap below the legacy default", () => {
+    expect(projectedHistoryCharLimit(64_000)).toBe(MAX_PROJECTED_HISTORY_CHARS);
+  });
+
+  test("a large window scales the cap until the hard ceiling", () => {
+    expect(projectedHistoryCharLimit(128_000)).toBe(384_000);
+    expect(projectedHistoryCharLimit(1_000_000)).toBe(3_000_000);
+    expect(projectedHistoryCharLimit(Number.MAX_SAFE_INTEGER)).toBe(4_000_000);
+  });
+
+  test("buildConversationInput keeps the history a derived ceiling admits", () => {
+    const history = Array.from({ length: 5 }, (_, index) => ({
+      role: "user" as const,
+      content: "EARLY-MARKER-" + String(index) + " " + "a".repeat(50_000),
+      timestamp: index,
+    }));
+    const messages = [...history, { role: "user", content: "current request", timestamp: 5 }];
+    const parsed = parsedRequest({ context: { messages } });
+
+    const wide = buildConversationInput(parsed, { maxHistoryChars: projectedHistoryCharLimit(1_000_000) })
+      .map(line => JSON.parse(line));
+    expect(wide[0].message.content[0].text).toContain("EARLY-MARKER-0");
+    expect(wide[0].message.content[0].text).not.toContain("truncated for length");
+
+    const flat = buildConversationInput(parsed).map(line => JSON.parse(line));
+    expect(flat[0].message.content[0].text).not.toContain("EARLY-MARKER-0");
+    expect(flat[0].message.content[0].text).toContain("truncated for length");
+    expect(flat[0].message.content[0].text).toContain("current request");
+  });
+});
diff --git a/tests/providers/cursor/cursor-catalog.test.ts b/tests/providers/cursor/cursor-catalog.test.ts
index 4d8a79e352f..f4b1580ad7f 100644
--- a/tests/providers/cursor/cursor-catalog.test.ts
+++ b/tests/providers/cursor/cursor-catalog.test.ts
@@ -1,12 +1,14 @@
 import { describe, expect, test } from "bun:test";
 import {
   CURSOR_CAPABILITIES,
+  cursorLiveRosterScope,
   cursorUmbrellaRows,
   parseCursorVariantId,
   recordLiveCursorClaudeModels,
   resetLiveCursorClaudeWireIdentitiesForTests,
   resolveCursorSelection,
 } from "../../../src/adapters/cursor/catalog";
+import { clearModelCache } from "../../../src/codex/model-cache";
 import {
   cursorEffortSuffix,
   cursorModelHasEffortTiers,
@@ -211,6 +213,30 @@ describe("cursor umbrella catalog (devlog 260828_cursor_umbrella_catalog)", () =
       }
     });
 
+    test("live roster spellings stay isolated by provider credential scope and clear with its cache", () => {
+      const trusted = cursorLiveRosterScope("https://trusted.cursor.test", "trusted-token");
+      const untrusted = cursorLiveRosterScope("https://other.cursor.test", "other-token");
+      recordLiveCursorClaudeModels(
+        ["claude-4.6-opus-high-thinking"],
+        { provider: "cursor-trusted", key: trusted },
+      );
+      recordLiveCursorClaudeModels(
+        ["claude-opus-4-6-thinking-high"],
+        { provider: "cursor-other", key: untrusted },
+      );
+
+      expect(resolveCursorSelection("claude-4.6-opus", "high", undefined, { liveRosterScope: trusted }).wireId)
+        .toBe("claude-4.6-opus-high-thinking");
+      expect(resolveCursorSelection("claude-4.6-opus", "high", undefined, { liveRosterScope: untrusted }).wireId)
+        .toBe("claude-opus-4-6-thinking-high");
+
+      clearModelCache("cursor-other");
+      expect(resolveCursorSelection("claude-4.6-opus", "high", undefined, { liveRosterScope: untrusted }).wireId)
+        .toBe("claude-4.6-opus-high-thinking");
+      expect(resolveCursorSelection("claude-4.6-opus", "high", undefined, { liveRosterScope: trusted }).wireId)
+        .toBe("claude-4.6-opus-high-thinking");
+    });
+
     test("ultra arms maxMode only on evidence-gated bases", () => {
       const kimi = resolveCursorSelection("kimi-k3-1m", "ultra");
       expect(kimi.maxMode).toBe(true);
diff --git a/tests/providers/cursor/cursor-roster-account-scope.test.ts b/tests/providers/cursor/cursor-roster-account-scope.test.ts
new file mode 100644
index 00000000000..f4861962fbe
--- /dev/null
+++ b/tests/providers/cursor/cursor-roster-account-scope.test.ts
@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { setFetchCursorUsableModelsForTests } from "../../../src/adapters/cursor/live-models";
+import { fetchProviderModels } from "../../../src/codex/catalog/provider-fetch";
+import { clearModelCache, providerCacheGenerations } from "../../../src/codex/model-cache";
+import type { OcxProviderConfig } from "../../../src/types";
+
+/**
+ * The live GetUsableModels roster is plan-specific: it is an observation made
+ * under one credential and must never be served to another, whether fresh,
+ * stale, or through a failure cooldown. The scoped spelling and Max-Mode maps
+ * (#5229) do not cover the cached roster itself; these cases pin the roster
+ * cache to the credential fingerprint that produced it.
+ */
+
+const PROVIDER = "cursor-roster-scope-test";
+
+beforeEach(() => {
+  clearModelCache(PROVIDER);
+  providerCacheGenerations.delete(PROVIDER);
+});
+
+afterEach(() => {
+  setFetchCursorUsableModelsForTests(null);
+  clearModelCache(PROVIDER);
+  providerCacheGenerations.delete(PROVIDER);
+});
+
+const baseProvider = {
+  adapter: "cursor",
+  baseUrl: "https://cursor.roster-scope.test",
+  authMode: "key",
+  liveModels: true,
+  models: ["gpt-5.5", "gpt-5.6-sol"],
+} as OcxProviderConfig;
+
+describe("cursor live roster account scoping", () => {
+  test("a credential change cannot reuse the previous account's plan roster", async () => {
+    const calls: string[] = [];
+    setFetchCursorUsableModelsForTests(async (opts) => {
+      calls.push(opts.apiKey);
+      return { ok: true, models: [opts.apiKey === "acct-a-token" ? "gpt-5.5" : "gpt-5.6-sol"] };
+    });
+
+    const accountA = await fetchProviderModels(PROVIDER, { ...baseProvider, apiKey: "acct-a-token" }, 60_000);
+    const accountB = await fetchProviderModels(PROVIDER, { ...baseProvider, apiKey: "acct-b-token" }, 60_000);
+
+    expect(accountA.map((model) => model.id)).toEqual(["gpt-5.5"]);
+    expect(accountB.map((model) => model.id)).toEqual(["gpt-5.6-sol"]);
+    // B went live: serving A's fresh cached roster would have skipped the fetch.
+    expect(calls).toEqual(["acct-a-token", "acct-b-token"]);
+  });
+
+  test("a failed discovery under one credential neither supplies nor suppresses the next", async () => {
+    const calls: string[] = [];
+    let fail = false;
+    setFetchCursorUsableModelsForTests(async (opts) => {
+      calls.push(opts.apiKey);
+      if (fail) return { ok: false, error: "auth" as const };
+      return { ok: true, models: [opts.apiKey === "acct-a-token" ? "gpt-5.5" : "gpt-5.6-sol"] };
+    });
+
+    // A caches its roster (ttl 0 keeps the fresh window closed so the failure
+    // below actually reaches the network seam).
+    await fetchProviderModels(PROVIDER, { ...baseProvider, apiKey: "acct-a-token" }, 0);
+    // A's next discovery fails, starting the provider cooldown; A degrades to
+    // its own stale roster.
+    fail = true;
+    const failedA = await fetchProviderModels(PROVIDER, { ...baseProvider, apiKey: "acct-a-token" }, 0);
+    expect(failedA.map((model) => model.id)).toEqual(["gpt-5.5"]);
+    // B must not read A's stale roster, and A's cooldown must not suppress B's
+    // first discovery: with no roster of its own, B goes live.
+    fail = false;
+    const accountB = await fetchProviderModels(PROVIDER, { ...baseProvider, apiKey: "acct-b-token" }, 0);
+
+    expect(accountB.map((model) => model.id)).toEqual(["gpt-5.6-sol"]);
+    expect(calls).toEqual(["acct-a-token", "acct-a-token", "acct-b-token"]);
+  });
+});
diff --git a/tests/providers/devin-live-models.test.ts b/tests/providers/devin-live-models.test.ts
index db365e2062c..70d3c8533e3 100644
--- a/tests/providers/devin-live-models.test.ts
+++ b/tests/providers/devin-live-models.test.ts
@@ -185,4 +185,23 @@ describe("devin advertised catalog input modalities", () => {
     expect(models.map((model) => model.id)).toEqual(["plain-model"]);
     expect(models[0]?.inputModalities).toEqual(["text"]);
   });
+
+  test("a credential change cannot reuse the previous account's live roster", async () => {
+    // The live catalog is entitlement-specific: an observation made under one
+    // credential must not be served to the next. Before the roster cache was
+    // bound to the credential fingerprint, account B read account A's fresh
+    // entry and never resolved its own token.
+    let token = "acct-a-key";
+    authSpy?.mockImplementation(async () => token);
+    setCachedCatalogForTests(parseCatalogBuffer(encodeMessage(1, catalogEntry("acct-a-model")), "acct-a-key", HOST));
+    const accountA = await fetchProviderModels("devin-test", devinProvider(), 60_000);
+
+    token = "acct-b-key";
+    setCachedCatalogForTests(parseCatalogBuffer(encodeMessage(1, catalogEntry("acct-b-model")), "acct-b-key", HOST));
+    const accountB = await fetchProviderModels("devin-test", devinProvider(), 60_000);
+
+    expect(accountA.map((model) => model.id)).toEqual(["acct-a-model"]);
+    expect(accountB.map((model) => model.id)).toEqual(["acct-b-model"]);
+    expect(authSpy?.mock.calls.length).toBe(2);
+  });
 });
diff --git a/tests/providers/devin-output-budget.test.ts b/tests/providers/devin-output-budget.test.ts
new file mode 100644
index 00000000000..ebd0b277259
--- /dev/null
+++ b/tests/providers/devin-output-budget.test.ts
@@ -0,0 +1,183 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { createDevinAdapter, resolveDevinMaxOutputTokensForTests } from "../../src/adapters/devin";
+import { parseCatalogBuffer, setCachedCatalogForTests } from "../../src/adapters/devin/cloud-direct/catalog";
+import { devinCacheIdentity, invalidateSessionIdentity } from "../../src/adapters/devin/cloud-direct/chat";
+import { encodeMessage, encodeString, encodeVarintField, iterFields } from "../../src/adapters/devin/cloud-direct/wire";
+import { createTranslatorBudget } from "../../src/lib/translator-budget";
+import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+/**
+ * The output budget a Devin turn actually sends.
+ *
+ * CompletionConfiguration #2 is the output cap and #3 is the context window.
+ * Every assertion below reads both, because the defect these guard against is
+ * not "the number is wrong" but "the two meanings were collapsed into one":
+ * a caller that names no cap has to reach the configured output budget without
+ * the context window leaking into the field that decides how long the answer
+ * may run.
+ */
+describe("Devin output budget on the wire", () => {
+  const apiKey = "ocx-devin-output-fixture";
+  const host = "https://server.codeium.com";
+  const previousHome = process.env.OPENCODEX_HOME;
+  const previousFetch = globalThis.fetch;
+  let home = "";
+  let requests: Buffer[] = [];
+
+  function frame(body: Buffer, flags = 0): Buffer {
+    const header = Buffer.alloc(5);
+    header[0] = flags;
+    header.writeUInt32BE(body.length, 1);
+    return Buffer.concat([header, body]);
+  }
+  function fields(buf: Buffer) {
+    return new Map([...iterFields(buf)].map(field => [field.num, field]));
+  }
+  function seed(rows: Array<{ uid: string; window?: number }>): void {
+    const buffer = Buffer.concat(rows.map(row => encodeMessage(1, Buffer.concat([
+      encodeString(1, row.uid),
+      encodeString(22, row.uid),
+      ...(row.window === undefined ? [] : [encodeVarintField(18, row.window)]),
+      encodeVarintField(4, 0),
+    ]))));
+    setCachedCatalogForTests(parseCatalogBuffer(buffer, apiKey, host));
+  }
+  async function run(
+    provider: Partial<OcxProviderConfig> = {},
+    options: OcxParsedRequest["options"] = {},
+    modelId = "swe-2-high",
+  ): Promise<AdapterEvent[]> {
+    const adapter = createDevinAdapter({ ...provider, adapter: "devin", apiKey, baseUrl: host });
+    const events: AdapterEvent[] = [];
+    await adapter.runTurn!({
+      modelId, stream: true,
+      context: { messages: [{ role: "user", content: "hi", timestamp: 1 }] },
+      options,
+    }, { headers: new Headers(), translatorBudget: createTranslatorBudget() },
+    event => { events.push(event); });
+    return events;
+  }
+  /** The completion configuration the one captured turn actually encoded. */
+  function sentCompletion(): { output: bigint; context: bigint } {
+    expect(requests).toHaveLength(1);
+    const completion = fields(fields(requests[0]!).get(8)!.value as Buffer);
+    return { output: completion.get(2)!.value as bigint, context: completion.get(3)!.value as bigint };
+  }
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "ocx-devin-output-"));
+    process.env.OPENCODEX_HOME = home;
+    requests = [];
+    setCachedCatalogForTests(null);
+    seed([{ uid: "swe-2-high", window: 262_000 }, { uid: "swe-2-max", window: 1_000_000 }]);
+    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (!url.endsWith("/GetChatMessage")) return new Response("unavailable", { status: 503 });
+      requests.push(Buffer.from(await (init!.body as Blob).arrayBuffer()).subarray(5));
+      return new Response(Buffer.concat([
+        frame(Buffer.concat([encodeString(3, "ok"), encodeVarintField(5, 2)])),
+        frame(Buffer.from("{}"), 2),
+      ]), { headers: { "content-type": "application/connect+proto" } });
+    }) as typeof fetch;
+  });
+  afterEach(() => {
+    globalThis.fetch = previousFetch;
+    setCachedCatalogForTests(null);
+    if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+    else process.env.OPENCODEX_HOME = previousHome;
+    invalidateSessionIdentity(devinCacheIdentity(apiKey, host));
+    removeTreeWithRetry(home);
+  });
+
+  test("a caller that names no cap still reaches the configured provider budget", async () => {
+    // Codex never sends max_output_tokens, so this is the path every real turn
+    // takes. Before the budget was wired the encoder's 8192 was the only cap a
+    // devin turn could ever have, whatever the operator configured.
+    const events = await run({ defaultMaxOutputTokens: 64_000 });
+    expect(events.some(event => event.type === "error")).toBe(false);
+    expect(sentCompletion().output).toBe(64_000n);
+  });
+
+  test("a per-model budget outranks the provider default and follows the selected variant", async () => {
+    await run({
+      defaultMaxOutputTokens: 64_000,
+      modelMaxOutputTokens: { "swe-2-high": 32_000, "swe-2-max": 100_000 },
+    });
+    expect(sentCompletion().output).toBe(32_000n);
+  });
+
+  test("an explicit small cap survives a much larger configured budget", async () => {
+    await run(
+      { defaultMaxOutputTokens: 64_000, modelMaxOutputTokens: { "swe-2-high": 32_000 } },
+      { maxOutputTokens: 64 },
+    );
+    expect(sentCompletion().output).toBe(64n);
+  });
+
+  test("the context window never becomes the output cap", async () => {
+    // The whole provider row describes input size and nothing else. The output
+    // field has to stay on the encoder default rather than inherit 262k, which
+    // would ask Cognition to generate an entire context window of tokens.
+    await run({ contextWindow: 200_000, modelContextWindows: { "swe-2-high": 180_000 } });
+    const sent = sentCompletion();
+    expect(sent.output).toBe(8192n);
+    expect(sent.context).toBe(180_000n);
+  });
+
+  test("a configured output budget does not disturb the input ceiling", async () => {
+    await run({ defaultMaxOutputTokens: 64_000 });
+    expect(sentCompletion().context).toBe(262_000n);
+  });
+});
+
+describe("Devin output budget resolution", () => {
+  const provider: Partial<OcxProviderConfig> = {
+    adapter: "devin",
+    defaultMaxOutputTokens: 64_000,
+    modelMaxOutputTokens: { "swe-2-high": 32_000 },
+  };
+
+  test("an explicit caller value is forwarded unchanged", () => {
+    expect(resolveDevinMaxOutputTokensForTests(provider as OcxProviderConfig, "swe-2-high", 64)).toBe(64);
+  });
+
+  test("an unconfigured provider leaves the encoder default in place", () => {
+    expect(resolveDevinMaxOutputTokensForTests({ adapter: "devin" } as OcxProviderConfig, "swe-2-high", undefined))
+      .toBeUndefined();
+  });
+
+  test("a dotted or case-folded saved hint still matches the selected uid", () => {
+    expect(resolveDevinMaxOutputTokensForTests(
+      { adapter: "devin", modelMaxOutputTokens: { "SWE.2-HIGH": 24_000 } } as OcxProviderConfig,
+      "swe-2-high", undefined,
+    )).toBe(24_000);
+  });
+
+  test("another variant's budget is never borrowed", () => {
+    expect(resolveDevinMaxOutputTokensForTests(
+      { adapter: "devin", modelMaxOutputTokens: { "swe-2-max": 100_000 } } as OcxProviderConfig,
+      "swe-2-high", undefined,
+    )).toBeUndefined();
+  });
+
+  test.each([Number.NaN, Number.POSITIVE_INFINITY, 0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1])(
+    "invalid configured metadata %p is ignored rather than encoded",
+    invalid => {
+      expect(resolveDevinMaxOutputTokensForTests(
+        { adapter: "devin", defaultMaxOutputTokens: invalid, modelMaxOutputTokens: { "swe-2": invalid } } as OcxProviderConfig,
+        "swe-2-high", undefined,
+      )).toBeUndefined();
+    },
+  );
+
+  test("the context window is not an output budget", () => {
+    expect(resolveDevinMaxOutputTokensForTests(
+      { adapter: "devin", contextWindow: 200_000, modelContextWindows: { "swe-2-high": 180_000 } } as OcxProviderConfig,
+      "swe-2-high", undefined,
+    )).toBeUndefined();
+  });
+});
diff --git a/tests/providers/model-rename-migration.test.ts b/tests/providers/model-rename-migration.test.ts
index be52a3da6ab..63f3ff71b69 100644
--- a/tests/providers/model-rename-migration.test.ts
+++ b/tests/providers/model-rename-migration.test.ts
@@ -142,6 +142,152 @@ describe("registry model rename migration (#1610)", () => {
       expect(entry?.models).not.toContain(rename.from);
     }
   });
+
+  test("repairs a saved kimi row still defaulting to the retired k2.7 id", () => {
+    // The shape a config saved under the pre-K2.8 registry carries: the picker list,
+    // the context-window record and the default all name kimi-k2.7-code, and the old
+    // registry already seeded kimi-for-coding rows next to them.
+    const stale = {
+      providers: {
+        kimi: {
+          adapter: "openai-chat",
+          baseUrl: "https://api.kimi.com/coding/v1",
+          authMode: "oauth",
+          defaultModel: "kimi-k2.7-code",
+          models: ["k3", "k3[1m]", "kimi-k2.7-code", "kimi-k2.7-code-highspeed", "kimi-k2.6", "kimi-k2.5", "kimi-for-coding"],
+          modelContextWindows: { "kimi-k2.7-code": 262_144, "kimi-for-coding": 262_144 },
+          noReasoningModels: ["kimi-k2.7-code", "kimi-k2.7-code-highspeed", "kimi-k2.6", "kimi-k2.5", "kimi-for-coding"],
+          modelReasoningEfforts: { "kimi-k2.7-code": [], "kimi-for-coding": [] },
+          modelDefaultReasoningEfforts: { k3: "max" },
+          modelReasoningEffortMap: { k3: { high: "high" } },
+        },
+      },
+    } as unknown as OcxConfig;
+
+    const { config, changed } = projectModelRenames(stale, MODEL_RENAMES);
+    const prov = config.providers.kimi!;
+    expect(changed).toBe(true);
+    expect(prov.defaultModel).toBe("kimi-for-coding");
+    expect(prov.models).toEqual(["k3", "k3[1m]", "kimi-for-coding"]);
+    expect(prov.modelContextWindows).toEqual({ "kimi-for-coding": 1_048_576 });
+    expect(prov.noReasoningModels).toEqual([]);
+    expect(prov.modelReasoningEfforts).toEqual({ "kimi-for-coding": ["low", "high", "max"] });
+    expect(prov.modelDefaultReasoningEfforts).toEqual({ k3: "max", "kimi-for-coding": "max" });
+    expect(prov.modelReasoningEffortMap?.["kimi-for-coding"]).toEqual({
+      none: "none", low: "low", medium: "high", high: "high", xhigh: "max", max: "max",
+    });
+  });
+
+  test("repairs the kimi-code key preset row the same way", () => {
+    const stale = {
+      providers: {
+        "kimi-code": {
+          adapter: "openai-chat",
+          baseUrl: "https://api.kimi.com/coding/v1",
+          authMode: "key",
+          apiKey: "sk-test",
+          defaultModel: "kimi-k2.7-code",
+          models: ["k3", "k3[1m]", "kimi-k2.7-code", "kimi-k2.6", "kimi-k2.5", "kimi-for-coding"],
+        },
+      },
+    } as unknown as OcxConfig;
+
+    const { config, changed } = projectModelRenames(stale, MODEL_RENAMES);
+    const prov = config.providers["kimi-code"]!;
+    expect(changed).toBe(true);
+    expect(prov.defaultModel).toBe("kimi-for-coding");
+    expect(prov.models).toEqual(["k3", "k3[1m]", "kimi-for-coding"]);
+  });
+
+  test("preserves explicit kimi-for-coding metadata while retiring old ids", () => {
+    const stale = {
+      providers: {
+        kimi: {
+          adapter: "openai-chat",
+          baseUrl: "https://api.kimi.com/coding/v1",
+          authMode: "oauth",
+          defaultModel: "kimi-k2.6",
+          models: ["kimi-k2.6", "kimi-for-coding"],
+          modelContextWindows: { "kimi-k2.6": 262_144, "kimi-for-coding": 131_072 },
+          modelReasoningEfforts: { "kimi-k2.6": [], "kimi-for-coding": ["low"] },
+          modelDefaultReasoningEfforts: { "kimi-for-coding": "low" },
+          modelReasoningEffortMap: { "kimi-for-coding": { medium: "low" } },
+        },
+      },
+    } as unknown as OcxConfig;
+
+    const { config } = projectModelRenames(stale, MODEL_RENAMES);
+    const prov = config.providers.kimi!;
+    expect(prov.defaultModel).toBe("kimi-for-coding");
+    expect(prov.models).toEqual(["kimi-for-coding"]);
+    expect(prov.modelContextWindows?.["kimi-for-coding"]).toBe(131_072);
+    expect(prov.modelReasoningEfforts?.["kimi-for-coding"]).toEqual(["low"]);
+    expect(prov.modelDefaultReasoningEfforts?.["kimi-for-coding"]).toBe("low");
+    expect(prov.modelReasoningEffortMap?.["kimi-for-coding"]).toEqual({ medium: "low" });
+  });
+
+  test("clears a stale no-reasoning classification saved under the live alias alone", () => {
+    // A config saved by the pre-K2.8 registry can carry kimi-for-coding in
+    // noReasoningModels even after every retired id is gone from the row - the old
+    // registry seeded the alias there. With no `from` left to rename, the stale
+    // classification would survive and keep the picker disabled; the drop must
+    // therefore trigger on the replacement id alone.
+    const stale = {
+      providers: {
+        kimi: {
+          adapter: "openai-chat",
+          baseUrl: "https://api.kimi.com/coding/v1",
+          authMode: "oauth",
+          defaultModel: "kimi-for-coding",
+          models: ["k3", "k3[1m]", "kimi-for-coding"],
+          noReasoningModels: ["kimi-for-coding"],
+          modelReasoningEfforts: { "kimi-for-coding": [] },
+        },
+      },
+    } as unknown as OcxConfig;
+
+    const { config, changed } = projectModelRenames(stale, MODEL_RENAMES);
+    const prov = config.providers.kimi!;
+    expect(changed).toBe(true);
+    expect(prov.noReasoningModels).toEqual([]);
+    expect(prov.modelReasoningEfforts?.["kimi-for-coding"]).toEqual(["low", "high", "max"]);
+  });
+
+  test("preserves an explicit no-reasoning override on the live alias", () => {
+    const configured = {
+      providers: {
+        kimi: {
+          adapter: "openai-chat",
+          baseUrl: "https://api.kimi.com/coding/v1",
+          authMode: "oauth",
+          defaultModel: "kimi-for-coding",
+          models: ["k3", "k3[1m]", "kimi-for-coding"],
+          noReasoningModels: ["kimi-for-coding"],
+          modelReasoningEfforts: { "kimi-for-coding": ["low"] },
+        },
+      },
+    } as unknown as OcxConfig;
+
+    const { config, changed } = projectModelRenames(configured, MODEL_RENAMES);
+    expect(changed).toBe(false);
+    expect(config.providers.kimi?.noReasoningModels).toEqual(["kimi-for-coding"]);
+  });
+
+  test("leaves a kimi row repointed at a different gateway alone", () => {
+    const custom = {
+      providers: {
+        kimi: {
+          adapter: "openai-chat",
+          baseUrl: "https://my-proxy.internal/v1",
+          authMode: "oauth",
+          defaultModel: "kimi-k2.7-code",
+          models: ["kimi-k2.7-code"],
+        },
+      },
+    } as unknown as OcxConfig;
+    const { changed } = projectModelRenames(custom, MODEL_RENAMES);
+    expect(changed).toBe(false);
+  });
 });
 
 describe("model rename startup persistence", () => {
diff --git a/tests/providers/provider-egress-outbound.test.ts b/tests/providers/provider-egress-outbound.test.ts
new file mode 100644
index 00000000000..bdf233dc1df
--- /dev/null
+++ b/tests/providers/provider-egress-outbound.test.ts
@@ -0,0 +1,247 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { DestinationDnsResolutionError } from "../../src/lib/destination-policy";
+import type { ProviderOutboundDependencies } from "../../src/lib/provider-outbound";
+import { InvalidProviderEgressError, PROVIDER_EGRESS_DIRECT } from "../../src/lib/provider-egress";
+import { PROXY_ENV_KEYS } from "../../src/lib/proxy-env";
+
+/**
+ * Provider discovery and quota probes share one transport chokepoint, `providerOutboundRequest`.
+ * Every caller of `providerOutboundGet`/`providerOutboundPost` — provider discovery, the
+ * model-catalog gather, the management provider test and the Ollama show probe — reaches the
+ * wire through the decision these cases pin.
+ *
+ * What makes these regressions rather than smoke tests: every one of them would pass if the
+ * provider route were ignored entirely, as long as the assertion were only "the request
+ * succeeded". Each case therefore asserts WHICH transport carried the request and WHICH proxy
+ * value it was pinned to.
+ */
+const proxyKeys = PROXY_ENV_KEYS.flatMap(key => [key, key.toLowerCase()]);
+const originalProxyEnv = Object.fromEntries(proxyKeys.map(key => [key, process.env[key]]));
+
+afterEach(() => {
+  for (const key of proxyKeys) {
+    const previous = originalProxyEnv[key];
+    if (previous === undefined) delete process.env[key];
+    else process.env[key] = previous;
+  }
+});
+
+const MODELS_URL = "https://provider.example/v1/models";
+const GLOBAL_PROXY = "http://global-egress.example:3128";
+const PROVIDER_PROXY = "http://provider-egress.example:8080";
+
+function pinnedDependencies(options?: { dnsFails?: boolean }): {
+  dependencies: ProviderOutboundDependencies;
+  captured: { address?: string };
+} {
+  const captured: { address?: string } = {};
+  return {
+    captured,
+    dependencies: {
+      resolveAddresses: mock(async () => {
+        if (options?.dnsFails) throw new DestinationDnsResolutionError("provider.example did not resolve");
+        return { hostname: "provider.example", addresses: [{ address: "93.184.216.34", family: 4 }], privateNetwork: false };
+      }),
+      pinnedGet: mock(async (_url, pinned) => {
+        captured.address = pinned.address;
+        return new Response('{"data":[]}', { status: 200, headers: { "content-type": "application/json" } });
+      }),
+      pinnedPost: mock(async (_url, pinned) => {
+        captured.address = pinned.address;
+        return new Response('{"data":[]}', { status: 200, headers: { "content-type": "application/json" } });
+      }),
+    },
+  };
+}
+
+/** Replace the global fetch and record the request-scoped proxy each call was pinned to. */
+function captureProxiedFetch(): { calls: Array<unknown>; restore: () => void } {
+  const calls: Array<unknown> = [];
+  const original = globalThis.fetch;
+  const stub = mock(async (_input: RequestInfo | URL, init?: RequestInit) => {
+    calls.push((init as { proxy?: unknown } | undefined)?.proxy);
+    return new Response('{"data":[]}', { status: 200, headers: { "content-type": "application/json" } });
+  });
+  globalThis.fetch = stub as unknown as typeof globalThis.fetch;
+  return { calls, restore: () => { globalThis.fetch = original; } };
+}
+
+describe("per-provider egress on the discovery and quota transport", () => {
+  test("a provider pinned to direct keeps the DNS-pinned transport while a global proxy is set", async () => {
+    // The DNS-pinned transport connects to an address this process resolved, through node:http,
+    // which never reads the proxy environment. That is what makes direct egress expressible
+    // here without asking anything of the runtime's own proxy handling.
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = GLOBAL_PROXY;
+    process.env.https_proxy = GLOBAL_PROXY;
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const { dependencies, captured } = pinnedDependencies();
+    const proxied = captureProxiedFetch();
+    try {
+      const response = await providerOutboundGet(
+        "vendor",
+        { baseUrl: "https://provider.example", proxy: PROVIDER_EGRESS_DIRECT },
+        MODELS_URL, {}, dependencies,
+      );
+      expect(response.status).toBe(200);
+      expect(captured.address).toBe("93.184.216.34");
+      expect(proxied.calls).toEqual([]);
+    } finally {
+      proxied.restore();
+    }
+  });
+
+  test("a provider proxy is pinned onto the request instead of being re-inferred from the environment", async () => {
+    // A global proxy is set to a DIFFERENT value on purpose: passing the request to fetch
+    // without pinning would let the environment decide, and the request would still succeed
+    // through the wrong exit.
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = GLOBAL_PROXY;
+    process.env.https_proxy = GLOBAL_PROXY;
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const { dependencies } = pinnedDependencies();
+    const proxied = captureProxiedFetch();
+    try {
+      await providerOutboundGet(
+        "vendor",
+        { baseUrl: "https://provider.example", proxy: PROVIDER_PROXY },
+        MODELS_URL, {}, dependencies,
+      );
+      expect(proxied.calls).toEqual([`${PROVIDER_PROXY}/`]);
+    } finally {
+      proxied.restore();
+    }
+  });
+
+  test("a provider proxy applies where global NO_PROXY exempts the host", async () => {
+    // The operator named this proxy for this provider. A global bypass list describes the
+    // global route and must not silently cancel the provider's own choice; the exemption that
+    // belongs to that choice is providers.<name>.noProxy, asserted below.
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = GLOBAL_PROXY;
+    process.env.NO_PROXY = "provider.example";
+    process.env.no_proxy = "provider.example";
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const { dependencies } = pinnedDependencies();
+    const proxied = captureProxiedFetch();
+    try {
+      await providerOutboundGet(
+        "vendor",
+        { baseUrl: "https://provider.example", proxy: PROVIDER_PROXY },
+        MODELS_URL, {}, dependencies,
+      );
+      expect(proxied.calls).toEqual([`${PROVIDER_PROXY}/`]);
+    } finally {
+      proxied.restore();
+    }
+  });
+
+  test("a provider noProxy match returns the request to the pinned transport", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const { dependencies, captured } = pinnedDependencies();
+    const proxied = captureProxiedFetch();
+    try {
+      await providerOutboundGet(
+        "vendor",
+        { baseUrl: "https://provider.example", proxy: PROVIDER_PROXY, noProxy: "provider.example" },
+        MODELS_URL, {}, dependencies,
+      );
+      expect(captured.address).toBe("93.184.216.34");
+      expect(proxied.calls).toEqual([]);
+    } finally {
+      proxied.restore();
+    }
+  });
+
+  test("a provider that declares nothing leaves the global decision untouched", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = GLOBAL_PROXY;
+    process.env.https_proxy = GLOBAL_PROXY;
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const { dependencies } = pinnedDependencies();
+    const proxied = captureProxiedFetch();
+    try {
+      await providerOutboundGet("vendor", { baseUrl: "https://provider.example" }, MODELS_URL, {}, dependencies);
+      // The global decision reaches the wire exactly as it did before this field existed,
+      // which is what "inherit" has to mean. That decision already pins the scheme-matched
+      // proxy here — the fake-IP admission binds the transport to the value it assumed rather
+      // than letting fetch re-infer it — so the assertion is that the pin is the GLOBAL proxy
+      // and is unchanged, not that no pin exists.
+      expect(proxied.calls).toEqual([GLOBAL_PROXY]);
+    } finally {
+      proxied.restore();
+    }
+  });
+
+  test("a DNS failure keeps an explicit provider proxy pinned through the degradation", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const { dependencies } = pinnedDependencies({ dnsFails: true });
+    const proxied = captureProxiedFetch();
+    try {
+      await providerOutboundGet(
+        "vendor",
+        { baseUrl: "https://provider.example", proxy: PROVIDER_PROXY },
+        MODELS_URL, {}, dependencies,
+      );
+      // Re-inferring the route here would move the request to a different exit at the exact
+      // moment local DNS stopped working, which is when the proxy matters most.
+      expect(proxied.calls).toEqual([`${PROVIDER_PROXY}/`]);
+    } finally {
+      proxied.restore();
+    }
+  });
+
+  test("a DNS failure under direct egress surfaces instead of degrading to an unpinned fetch", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = GLOBAL_PROXY;
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const { dependencies } = pinnedDependencies({ dnsFails: true });
+    const proxied = captureProxiedFetch();
+    try {
+      await expect(providerOutboundGet(
+        "vendor",
+        { baseUrl: "https://provider.example", proxy: PROVIDER_EGRESS_DIRECT },
+        MODELS_URL, {}, dependencies,
+      )).rejects.toThrow(DestinationDnsResolutionError);
+      expect(proxied.calls).toEqual([]);
+    } finally {
+      proxied.restore();
+    }
+  });
+
+  test("a malformed provider egress value refuses the request rather than choosing a route", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = GLOBAL_PROXY;
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const { dependencies, captured } = pinnedDependencies();
+    const proxied = captureProxiedFetch();
+    try {
+      await expect(providerOutboundGet(
+        "vendor",
+        { baseUrl: "https://provider.example", proxy: "ftp://egress.example" },
+        MODELS_URL, {}, dependencies,
+      )).rejects.toThrow(InvalidProviderEgressError);
+      // Neither degradation happened: no proxied send, and no direct send either.
+      expect(proxied.calls).toEqual([]);
+      expect(captured.address).toBeUndefined();
+    } finally {
+      proxied.restore();
+    }
+  });
+
+  test("an explicit route is refused on a caller-supplied executor instead of being dropped", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const executor = mock(async () => new Response(null, { status: 200 }));
+    await expect(providerOutboundGet(
+      "vendor",
+      { baseUrl: "https://provider.example", proxy: PROVIDER_PROXY, fetch: executor as unknown as typeof globalThis.fetch },
+      MODELS_URL, {}, pinnedDependencies().dependencies,
+    )).rejects.toThrow(InvalidProviderEgressError);
+    // The executor owns its own routing, so running it would send the request by a route the
+    // configuration contradicts.
+    expect(executor).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/providers/provider-outbound.test.ts b/tests/providers/provider-outbound.test.ts
index c0d5f59a2a9..e5614f455a4 100644
--- a/tests/providers/provider-outbound.test.ts
+++ b/tests/providers/provider-outbound.test.ts
@@ -3,6 +3,7 @@ import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { DestinationDnsResolutionError } from "../../src/lib/destination-policy";
 import type { ProviderOutboundDependencies } from "../../src/lib/provider-outbound";
 import { PROXY_ENV_KEYS } from "../../src/lib/proxy-env";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
@@ -234,6 +235,182 @@ describe("provider outbound GET transport", () => {
     }
   });
 
+  test("scheme-mismatched proxy variables keep the DNS-pinned transport", async () => {
+    const originalFetch = globalThis.fetch;
+    const fetchMock = mock(async () => new Response("unexpected", { status: 500 })) as typeof fetch;
+    globalThis.fetch = fetchMock;
+    try {
+      for (const { url, proxyKey } of [
+        { url: "http://provider.example/v1/models", proxyKey: "HTTPS_PROXY" },
+        { url: "https://provider.example/v1/models", proxyKey: "HTTP_PROXY" },
+      ] as const) {
+        for (const key of proxyKeys) delete process.env[key];
+        process.env[proxyKey] = "http://127.0.0.1:9";
+        const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+        const resolveOptions: { allowBenchmarkAddresses?: boolean }[] = [];
+        const { dependencies, captured } = directDependencies(new Response(null, { status: 204 }));
+        dependencies.resolveAddresses = mock(async (_url: string, options?: { allowBenchmarkAddresses?: boolean }) => {
+          resolveOptions.push({ allowBenchmarkAddresses: options?.allowBenchmarkAddresses });
+          return {
+            hostname: "provider.example",
+            addresses: [{ address: "93.184.216.34", family: 4 }],
+            privateNetwork: false,
+          };
+        }) as ProviderOutboundDependencies["resolveAddresses"];
+
+        const response = await providerOutboundGet(
+          "custom",
+          { baseUrl: new URL(url).origin + "/v1" },
+          url,
+          {},
+          dependencies,
+        );
+
+        expect(response.status).toBe(204);
+        expect(captured.address).toBe("93.184.216.34");
+        expect(resolveOptions).toEqual([{ allowBenchmarkAddresses: false }]);
+      }
+      expect(fetchMock).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("a NO_PROXY match keeps the request on the DNS-pinned transport", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = "http://127.0.0.1:9";
+    process.env.NO_PROXY = "provider.example";
+    const originalFetch = globalThis.fetch;
+    const fetchMock = mock(async () => new Response("unexpected", { status: 500 })) as typeof fetch;
+    globalThis.fetch = fetchMock;
+    try {
+      const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+      const { dependencies, captured } = directDependencies(new Response(null, { status: 204 }));
+
+      const response = await providerOutboundGet(
+        "custom",
+        { baseUrl: "https://provider.example/v1" },
+        "https://provider.example/v1/models",
+        {},
+        dependencies,
+      );
+
+      expect(response.status).toBe(204);
+      expect(captured.address).toBe("93.184.216.34");
+      expect(fetchMock).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("a scheme-mismatched proxy variable does not demand NO_PROXY for private providers", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTP_PROXY = "http://127.0.0.1:9";
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const { dependencies, captured } = directDependencies(new Response(null, { status: 200 }), {
+      privateNetwork: true,
+      address: "192.168.1.50",
+    });
+
+    const response = await providerOutboundGet(
+      "ollama-lan",
+      { baseUrl: "https://ollama.lan:11434/v1", allowPrivateNetwork: true },
+      "https://ollama.lan:11434/v1/models",
+      {},
+      dependencies,
+    );
+
+    expect(response.status).toBe(200);
+    expect(captured.address).toBe("192.168.1.50");
+  });
+
+  test("DNS failure with only a scheme-mismatched proxy rethrows instead of degrading to an unpinned fetch", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTP_PROXY = "http://127.0.0.1:9";
+    const originalFetch = globalThis.fetch;
+    const fetchMock = mock(async () => new Response("unexpected", { status: 500 })) as typeof fetch;
+    globalThis.fetch = fetchMock;
+    try {
+      const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+      const { dependencies } = directDependencies(new Response(null, { status: 204 }));
+      dependencies.resolveAddresses = mock(async () => {
+        throw new DestinationDnsResolutionError("getaddrinfo ENOTFOUND provider.example");
+      }) as ProviderOutboundDependencies["resolveAddresses"];
+
+      // A proxy variable fetch would never use for this https: target must not
+      // license the unpinned degradation path: the DNS failure surfaces as-is.
+      await expect(providerOutboundGet(
+        "custom",
+        { baseUrl: "https://provider.example/v1" },
+        "https://provider.example/v1/models",
+        {},
+        dependencies,
+      )).rejects.toBeInstanceOf(DestinationDnsResolutionError);
+      expect(fetchMock).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("DNS failure behind a scheme-matched proxy still degrades to the proxy fetch", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = "http://127.0.0.1:9";
+    const originalFetch = globalThis.fetch;
+    const fetchMock = mock(async () => new Response('{"data":[]}', { status: 200 })) as typeof fetch;
+    globalThis.fetch = fetchMock;
+    try {
+      const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+      const { dependencies } = directDependencies(new Response(null, { status: 204 }));
+      dependencies.resolveAddresses = mock(async () => {
+        throw new DestinationDnsResolutionError("getaddrinfo ENOTFOUND provider.example");
+      }) as ProviderOutboundDependencies["resolveAddresses"];
+
+      // The proxy the request will actually use may resolve names the local
+      // resolver cannot, so the degradation stays for the route that applies.
+      const response = await providerOutboundGet(
+        "custom",
+        { baseUrl: "https://provider.example/v1" },
+        "https://provider.example/v1/models",
+        {},
+        dependencies,
+      );
+
+      expect(response.status).toBe(200);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("a SOCKS scheme-matched variable admits and binds the proxy instead of pin-connecting to fake-IP", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = "socks5://127.0.0.1:9";
+    const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
+    const { dependencies, captured } = directDependencies(new Response(null, { status: 204 }));
+    const resolveOptions: { allowMihomoIpv6FakeIp?: boolean }[] = [];
+    dependencies.resolveAddresses = mock(async (_url: string, options?: { allowMihomoIpv6FakeIp?: boolean }) => {
+      resolveOptions.push({ allowMihomoIpv6FakeIp: options?.allowMihomoIpv6FakeIp });
+      return {
+        hostname: "provider.example",
+        addresses: [{ address: "fdfe:dcba:9876::1", family: 6 }],
+        privateNetwork: false,
+      };
+    }) as ProviderOutboundDependencies["resolveAddresses"];
+
+    // Admission and transport must name the same proxy: the request rides the
+    // SOCKS binding the admission assumed, so the unreachable proxy rejects
+    // here. Pin-connecting to the fake-IP instead would be the inconsistency.
+    await expect(providerOutboundGet(
+      "custom",
+      { baseUrl: "https://provider.example/v1" },
+      "https://provider.example/v1/models",
+      {},
+      dependencies,
+    )).rejects.toThrow();
+    expect(resolveOptions).toEqual([{ allowMihomoIpv6FakeIp: true }]);
+    expect(captured.address).toBeUndefined();
+  });
+
   test("built-in ollama admits loopback discovery without an explicit allowPrivateNetwork flag (#758)", async () => {
     for (const key of proxyKeys) delete process.env[key];
     const { providerOutboundGet } = await import("../../src/lib/provider-outbound");
@@ -571,7 +748,7 @@ describe("#3462 Mihomo IPv6 fake-IP admission is gated on the scheme-matched pro
 });
 
 describe("effectiveProxyFor picks the variable Bun fetch actually honours", () => {
-  test("scheme-matched selection; HTTP ALL_PROXY is never consulted", async () => {
+  test("scheme-matched selection; HTTP ALL_PROXY only counts for http: targets", async () => {
     const { effectiveProxyFor } = await import("../../src/lib/proxy-env");
     const https = new URL("https://opencode.ai/zen/v1/models");
     const http = new URL("http://ollama.lan:11434/v1/models");
@@ -582,9 +759,50 @@ describe("effectiveProxyFor picks the variable Bun fetch actually honours", () =
     expect(effectiveProxyFor(https, { ALL_PROXY: "socks5://127.0.0.1:1080" })).toBe("socks5://127.0.0.1:1080");
     expect(effectiveProxyFor(http, { HTTP_PROXY: "http://p:5" })).toBe("http://p:5");
     expect(effectiveProxyFor(http, { HTTPS_PROXY: "http://p:6" })).toBeNull();
+    // Bun's native fetch honours a non-SOCKS ALL_PROXY for plain http: targets on
+    // every platform the CI matrix covers (the provider-outbound e2e proves the
+    // request reaches the proxy); https: targets only ever use the socks5 wrapper.
+    expect(effectiveProxyFor(http, { ALL_PROXY: "http://p:7" })).toBe("http://p:7");
+    expect(effectiveProxyFor(http, { all_proxy: "http://p:13" })).toBe("http://p:13");
+    expect(effectiveProxyFor(http, { ALL_PROXY: "ftp://p:8" })).toBeNull();
+    expect(effectiveProxyFor(http, { ALL_PROXY: "http://" })).toBeNull();
+    // A SOCKS URL in a scheme-matched variable is a usable proxy: admission
+    // binds it explicitly and the transport follows, so it counts as applying.
+    expect(effectiveProxyFor(https, { HTTPS_PROXY: "socks5://p:9" })).toBe("socks5://p:9");
+    expect(effectiveProxyFor(http, { HTTP_PROXY: "socks5h://p:14" })).toBe("socks5h://p:14");
+    // A malformed or non-proxy-scheme scheme-matched variable is not a proxy
+    // Bun fetch can use either: it must not count as "the proxy that applies".
+    expect(effectiveProxyFor(http, { HTTP_PROXY: "http://" })).toBeNull();
+    expect(effectiveProxyFor(http, { HTTP_PROXY: "not a url" })).toBeNull();
+    expect(effectiveProxyFor(https, { HTTPS_PROXY: "http://" })).toBeNull();
     expect(effectiveProxyFor(https, { HTTPS_PROXY: "   " })).toBeNull();
+    // A present-but-unusable scheme-matched variable fails closed rather than
+    // falling through to ALL_PROXY: no usable proxy is guaranteed either way,
+    // so the DNS-pinned transport must stay.
+    expect(effectiveProxyFor(http, { HTTP_PROXY: "not a url", ALL_PROXY: "http://p:10" })).toBeNull();
+    expect(effectiveProxyFor(https, { HTTPS_PROXY: "ftp://p:11", ALL_PROXY: "http://p:12" })).toBeNull();
     expect(effectiveProxyFor(new URL("ftp://x/"), { HTTPS_PROXY: "http://p:7", HTTP_PROXY: "http://p:7" })).toBeNull();
   });
+
+  test("schemeMatchedProxyFor keeps the stricter fake-IP binding gate", async () => {
+    const { schemeMatchedProxyFor } = await import("../../src/lib/proxy-env");
+    const https = new URL("https://opencode.ai/zen/v1/models");
+    const http = new URL("http://ollama.lan:11434/v1/models");
+    expect(schemeMatchedProxyFor(https, { HTTPS_PROXY: "http://p:1" })).toBe("http://p:1");
+    expect(schemeMatchedProxyFor(http, { HTTP_PROXY: "http://p:2" })).toBe("http://p:2");
+    // A SOCKS URL in a scheme-matched variable is a valid explicit binding.
+    expect(schemeMatchedProxyFor(https, { HTTPS_PROXY: "socks5://p:3" })).toBe("socks5://p:3");
+    expect(schemeMatchedProxyFor(https, { ALL_PROXY: "socks5://p:4" })).toBe("socks5://p:4");
+    // A non-SOCKS ALL_PROXY never counts for the binding gate, even for the
+    // http: targets effectiveProxyFor reports it for.
+    expect(schemeMatchedProxyFor(http, { ALL_PROXY: "http://p:5" })).toBeNull();
+    expect(schemeMatchedProxyFor(https, { ALL_PROXY: "http://p:6" })).toBeNull();
+    expect(schemeMatchedProxyFor(https, { HTTP_PROXY: "http://p:7" })).toBeNull();
+    // An unusable scheme-matched value is not a binding either: admitting a
+    // fake-IP answer against it would pin-connect to an address nothing resolves.
+    expect(schemeMatchedProxyFor(https, { HTTPS_PROXY: "not a url" })).toBeNull();
+    expect(schemeMatchedProxyFor(https, { HTTPS_PROXY: "ftp://p:8" })).toBeNull();
+  });
 });
 
 describe("provider outbound default User-Agent", () => {
diff --git a/tests/providers/provider-registry-parity.test.ts b/tests/providers/provider-registry-parity.test.ts
index 094eb8f1cb1..70931a206c2 100644
--- a/tests/providers/provider-registry-parity.test.ts
+++ b/tests/providers/provider-registry-parity.test.ts
@@ -46,7 +46,7 @@ const EXPECTED_KEY_PROVIDER_IDS = [
   "volcengine", "volcengine-coding-plan", "volcengine-agent-plan", "qianfan", "alibaba", "alibaba-token-plan", "alibaba-token-plan-intl", "parallel", "zenmux", "litellm", "ollama-cloud", "mistral",
   "minimax", "minimax-cn", "kimi-code", "opencode-zen", "vercel-ai-gateway", "opper",
   "opencode-free", "xiaomi", "xiaomi-mimo", "kilo", "mimo-free", "mimo", "cloudflare-ai-gateway", "cloudflare-workers-ai", "gitlab-duo",
-  "qoder", "qoder-cn", "codebuddy", "codebuddy-cn",
+  "qoder", "qoder-cn", "codebuddy", "codebuddy-cn", "stepfun",
 ];
 
 describe("provider registry parity", () => {
@@ -945,15 +945,12 @@ describe("provider registry parity", () => {
   });
 
   test("Kimi coding aliases preserve model context and capability parity", () => {
-    const codingModels = [
-      "k3",
-      "k3[1m]",
-      "kimi-k2.7-code",
-      "kimi-k2.7-code-highspeed",
-      "kimi-k2.6",
-      "kimi-k2.5",
-      "kimi-for-coding",
-    ];
+    // 260921: the picker AND every preset metadata list seed only ids the subscription
+    // endpoint still serves (live /coding/v1/models: kimi-for-coding[-highspeed], k3,
+    // k3-256k). Seeding a retired id in a metadata list would re-arm the model-rename
+    // migration on every boot (#5066); saved rows still naming one are repaired by
+    // MODEL_RENAMES instead.
+    const codingModels = ["k3", "k3[1m]", "k3-256k", "kimi-for-coding"];
     const parityLists = [
       "noReasoningModels",
       "noTemperatureModels",
@@ -966,13 +963,25 @@ describe("provider registry parity", () => {
     for (const providerId of ["kimi", "kimi-code"]) {
       const entry = PROVIDER_REGISTRY.find(provider => provider.id === providerId);
       expect(entry?.models).toEqual(codingModels);
+      // The whole point of the refresh: both presets default to the live alias. A
+      // registry rollback to the retired default would silently pass without this.
+      expect(entry?.defaultModel).toBe("kimi-for-coding");
+      expect(entry?.models).not.toContain("kimi-k2.7-code");
       for (const modelId of codingModels) {
-        expect(entry?.modelContextWindows?.[modelId]).toBe(modelId === "k3[1m]" ? 1_048_576 : 262_144);
+        // 260921: kimi-for-coding (K2.8 Preview) shares the verified 1M ceiling with k3[1m];
+        // all other ids stay at the 256K standard window.
+        expect(entry?.modelContextWindows?.[modelId]).toBe(modelId === "k3[1m]" || modelId === "kimi-for-coding" ? 1_048_576 : 262_144);
       }
       for (const field of parityLists) {
-        expect(entry?.[field]).toContain("kimi-k2.7-code");
-        expect(entry?.[field]).toContain("kimi-for-coding");
+        // Every preset list is live-id only: kimi-for-coding must be there, the retired
+        // k2.x ids must not (a stale k2.7 row would leak the dead id back into the picker).
+        if (field !== "noReasoningModels") expect(entry?.[field]).toContain("kimi-for-coding");
+        expect(entry?.[field] ?? []).not.toContain("kimi-k2.7-code");
       }
+      // kimi-for-coding left noReasoningModels when K2.8 added the adjustable ladder.
+      expect(entry?.noReasoningModels ?? []).not.toContain("kimi-for-coding");
+      expect(entry?.modelReasoningEfforts?.["kimi-for-coding"]).toEqual(["low", "high", "max"]);
+      expect(entry?.modelDefaultReasoningEfforts?.["kimi-for-coding"]).toBe("max");
       expect(entry?.modelSuffixBracketStrip).toBe(true);
       expect(entry?.promptCacheKey).toBe(true);
       // Key-pool 429 rotation rebuilds the provider from the persisted config (not the routed
@@ -1004,7 +1013,8 @@ describe("provider registry parity", () => {
       expect(entry?.noPenaltyModels).toContain("k3");
       expect(entry?.preserveReasoningContentModels).toContain("k3");
       expect(entry?.preserveReasoningContentModels).toContain("k3[1m]");
-      expect(entry?.modelReasoningEfforts?.["kimi-for-coding"]).toEqual([]);
+      // 260921: K2.8 gave kimi-for-coding the same adjustable low/high/max ladder as k3.
+      expect(entry?.modelReasoningEfforts?.["kimi-for-coding"]).toEqual(["low", "high", "max"]);
     }
 
     const kimi = PROVIDER_REGISTRY.find(provider => provider.id === "kimi")!;
diff --git a/tests/providers/stepfun-provider.test.ts b/tests/providers/stepfun-provider.test.ts
new file mode 100644
index 00000000000..ffb1143da33
--- /dev/null
+++ b/tests/providers/stepfun-provider.test.ts
@@ -0,0 +1,166 @@
+import { describe, expect, test } from "bun:test";
+import { createOpenAIChatAdapter } from "../../src/adapters/openai-chat";
+import { KEY_LOGIN_PROVIDERS } from "../../src/oauth/key-providers";
+import { deriveProviderPresets, providerConfigSeed } from "../../src/providers/derive";
+import { enrichProviderFromCatalog } from "../../src/oauth/key-providers";
+import { PROVIDER_REGISTRY } from "../../src/providers/registry";
+import { routeModel } from "../../src/router";
+import type { OcxConfig, OcxProviderConfig } from "../../src/types";
+import { en } from "../../gui/src/i18n/en";
+import { interpolate, type TFn } from "../../gui/src/i18n/shared";
+import { formatProviderDisplayName, isCatalogProviderId, providerIconSrc } from "../../gui/src/provider-icons";
+
+const englishT: TFn = (key, vars) => interpolate(en[key], vars);
+
+const BASE_URL = "https://api.stepfun.com/v1";
+const TEST_KEY = "test-stepfun-key-12345";
+
+function getStepFunRegistryEntry() {
+  const entry = PROVIDER_REGISTRY.find(p => p.id === "stepfun");
+  if (!entry) throw new Error("StepFun registry entry not found");
+  return entry;
+}
+
+function createStepFunConfig(overrides: Partial<OcxProviderConfig> = {}): OcxConfig {
+  return {
+    port: 10100,
+    defaultProvider: "stepfun",
+    providers: {
+      stepfun: {
+        adapter: "openai-chat",
+        baseUrl: BASE_URL,
+        authMode: "key",
+        apiKey: TEST_KEY,
+        ...overrides,
+      },
+    },
+  };
+}
+
+describe("StepFun provider", () => {
+  test("appears in the provider registry and preset catalog", () => {
+    const entry = getStepFunRegistryEntry();
+    expect(entry).toMatchObject({
+      id: "stepfun",
+      label: "StepFun",
+      adapter: "openai-chat",
+      baseUrl: BASE_URL,
+      authKind: "key",
+      dashboardUrl: "https://platform.stepfun.com",
+      defaultModel: "step-5-preview",
+      liveModels: true,
+      preserveCustomDestination: true,
+    });
+    expect(entry.models).toEqual([
+      "step-5-preview",
+      "step-3.5-flash",
+      "step-3.7-flash",
+    ]);
+
+    // Check presence in derived presets for UI catalog
+    const presets = deriveProviderPresets();
+    const preset = presets.find(p => p.id === "stepfun");
+    expect(preset).toBeDefined();
+    expect(preset).toMatchObject({
+      id: "stepfun",
+      label: "StepFun",
+      adapter: "openai-chat",
+      baseUrl: BASE_URL,
+      auth: "key",
+      defaultModel: "step-5-preview",
+      dashboardUrl: "https://platform.stepfun.com",
+    });
+
+    // Check presence in key login providers
+    expect(KEY_LOGIN_PROVIDERS.stepfun).toMatchObject({
+      baseUrl: BASE_URL,
+      adapter: "openai-chat",
+      dashboardUrl: "https://platform.stepfun.com",
+      defaultModel: "step-5-preview",
+      liveModels: true,
+    });
+  });
+
+  test("can save API key and enrich config from catalog seed", () => {
+    const entry = getStepFunRegistryEntry();
+    const seed = providerConfigSeed(entry);
+    expect(seed).toMatchObject({
+      adapter: "openai-chat",
+      baseUrl: BASE_URL,
+      authMode: "key",
+      defaultModel: "step-5-preview",
+    });
+
+    // Verify saving provider config with API Key and enriching metadata
+    const userConfig: OcxProviderConfig = {
+      adapter: "openai-chat",
+      baseUrl: BASE_URL,
+      authMode: "key",
+      apiKey: TEST_KEY,
+    };
+    enrichProviderFromCatalog("stepfun", userConfig);
+
+    expect(userConfig.apiKey).toBe(TEST_KEY);
+    expect(userConfig.defaultModel).toBe("step-5-preview");
+    expect(userConfig.models).toEqual([
+      "step-5-preview",
+      "step-3.5-flash",
+      "step-3.7-flash",
+    ]);
+    expect(userConfig.modelContextWindows?.["step-5-preview"]).toBe(1_000_000);
+    expect(userConfig.modelContextWindows?.["step-3.5-flash"]).toBe(256_000);
+    expect(userConfig.modelContextWindows?.["step-3.7-flash"]).toBe(256_000);
+  });
+
+  test("models can be selected and routed with correct metadata", () => {
+    const config = createStepFunConfig();
+
+    // Model 1: step-5-preview
+    const route5 = routeModel(config, "stepfun/step-5-preview");
+    expect(route5.modelId).toBe("step-5-preview");
+    expect(route5.provider.adapter).toBe("openai-chat");
+    expect(route5.provider.baseUrl).toBe(BASE_URL);
+    expect(route5.provider.modelContextWindows?.["step-5-preview"]).toBe(1_000_000);
+    expect(route5.provider.modelInputModalities?.["step-5-preview"]).toEqual(["text", "image"]);
+
+    // Model 2: step-3.5-flash
+    const route35 = routeModel(config, "stepfun/step-3.5-flash");
+    expect(route35.modelId).toBe("step-3.5-flash");
+    expect(route35.provider.modelContextWindows?.["step-3.5-flash"]).toBe(256_000);
+    expect(route35.provider.noVisionModels).toContain("step-3.5-flash");
+
+    // Model 3: step-3.7-flash
+    const route37 = routeModel(config, "stepfun/step-3.7-flash");
+    expect(route37.modelId).toBe("step-3.7-flash");
+    expect(route37.provider.modelContextWindows?.["step-3.7-flash"]).toBe(256_000);
+    expect(route37.provider.modelInputModalities?.["step-3.7-flash"]).toEqual(["text", "image"]);
+  });
+
+  test("builds requests targeting the correct StepFun endpoint", () => {
+    const config = createStepFunConfig();
+    const route = routeModel(config, "stepfun/step-5-preview");
+    const adapter = createOpenAIChatAdapter(route.provider);
+
+    const request = adapter.buildRequest({
+      modelId: route.modelId,
+      context: {
+        messages: [{ role: "user", content: "Hello StepFun", timestamp: Date.now() }],
+      },
+      stream: false,
+      options: {},
+    });
+
+    expect(request.url).toBe("https://api.stepfun.com/v1/chat/completions");
+    expect(request.headers.Authorization).toBe(`Bearer ${TEST_KEY}`);
+
+    const parsedBody = JSON.parse(String(request.body));
+    expect(parsedBody.model).toBe("step-5-preview");
+    expect(parsedBody.messages[0].content).toBe("Hello StepFun");
+  });
+
+  test("resolves UI display name and brand icon", () => {
+    expect(formatProviderDisplayName("stepfun", englishT)).toBe("StepFun");
+    expect(isCatalogProviderId("stepfun")).toBe(true);
+    expect(providerIconSrc("stepfun")).toBe("/provider-icons/stepfun-color.svg");
+  });
+});
diff --git a/tests/providers/xai/grok-lifecycle.test.ts b/tests/providers/xai/grok-lifecycle.test.ts
index 6968bedceab..e6e42c80759 100644
--- a/tests/providers/xai/grok-lifecycle.test.ts
+++ b/tests/providers/xai/grok-lifecycle.test.ts
@@ -164,7 +164,9 @@ describe("Grok fence lifecycle wiring", () => {
     const stopFn = sliceFn(CLI_SOURCE, "async function handleStop(", "async function handleUninstall(");
     // process.exit() inside handleStop would strand runTrayProxyRestart's start() half.
     expect(stopFn).toContain("process.exitCode = 1");
-    expect(stopFn).toContain("return !stopFailed");
+    // The structured outcome (the stop --json summary) keeps the old boolean as ok, so
+    // the dispatcher's downtime-warning gate is byte-for-byte the pre-summary semantics.
+    expect(stopFn).toContain("return { ok: !stopFailed, summary };");
     expect(stopFn).not.toContain("process.exit(1)");
 
     const restartCase = sliceFn(DISPATCH_SOURCE, "restart: async", "health: async");
@@ -297,7 +299,7 @@ describe("Grok fence lifecycle wiring", () => {
     expect(noPidBranch).toContain("stopFailed = true;");
     expect(noPidBranch).toContain("ownershipBlocked = true;");
     const gateFn = sliceFn(CLI_SOURCE, "const abandonedTeardownIsSafeToFinish", "let stopFailed = false;");
-    expect(gateFn).toContain('probeProxyLiveness(endpoint.port, endpoint.hostname) === "dead"');
+    expect(gateFn).toContain('probeEndpointLiveness(endpoint) === "dead"');
     expect(gateFn).toContain("return false;");
   });
 
diff --git a/tests/providers/xai/xai-empty-catalog-tool-choice.test.ts b/tests/providers/xai/xai-empty-catalog-tool-choice.test.ts
new file mode 100644
index 00000000000..28b2549397c
--- /dev/null
+++ b/tests/providers/xai/xai-empty-catalog-tool-choice.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, test } from "bun:test";
+import { normalizeXaiResponsesWebSearch } from "../../../src/adapters/xai-web-search";
+import {
+  createGrokResponsesSparseTerminalBlockRewrite,
+  GROK_FORBIDDEN_TOOL_CALL_REASON,
+  GROK_REFUSED_TERMINAL_EVENT_TYPE,
+  forbiddenToolCallMessage,
+} from "../../../src/server/grok-responses-snapshot-repair";
+import { createTestTranslatorBudget } from "../../helpers/translator-budget";
+
+const XAI_PROVIDER = { baseUrl: "https://api.x.ai/v1" };
+
+function normalize(body: Record<string, unknown>): Record<string, unknown> {
+  return normalizeXaiResponsesWebSearch(body, XAI_PROVIDER) as Record<string, unknown>;
+}
+
+const CALL_ITEM: Record<string, unknown> = {
+  type: "function_call",
+  id: "fc_1",
+  call_id: "call_1",
+  name: "apply_patch",
+  arguments: "{}",
+};
+
+const MESSAGE_ITEM: Record<string, unknown> = {
+  type: "message",
+  id: "msg_1",
+  role: "assistant",
+  status: "completed",
+  content: [{ type: "output_text", text: "there is nothing to call here", annotations: [] }],
+};
+
+function dataBlock(payload: unknown): string {
+  return `data: ${JSON.stringify(payload)}`;
+}
+
+/** Replay a sparse Grok stream against one outbound body and return the terminal it publishes. */
+function reconstructTerminal(outboundBody: unknown): Record<string, unknown> {
+  const rewrite = createGrokResponsesSparseTerminalBlockRewrite(
+    createTestTranslatorBudget(),
+    outboundBody,
+  );
+  rewrite(dataBlock({ type: "response.output_item.done", output_index: 0, item: CALL_ITEM }));
+  rewrite(dataBlock({ type: "response.output_item.done", output_index: 1, item: MESSAGE_ITEM }));
+  const out = rewrite(
+    `event: response.completed\n${dataBlock({
+      type: "response.completed",
+      response: { id: "resp_1", status: "completed", output: [] },
+    })}`,
+  );
+  expect(out).toHaveLength(1);
+  const data = out[0]!.split(/\r?\n/)
+    .filter(line => line.startsWith("data: "))
+    .map(line => line.slice("data: ".length))
+    .join("");
+  return JSON.parse(data) as Record<string, unknown>;
+}
+
+describe("xAI Responses selectors after tool normalization", () => {
+  test("a catalog emptied by normalization drops the selector that has nothing left to select", () => {
+    // The cached-only declaration is omitted above rather than widened to live search, which
+    // leaves the request selecting from a catalog it no longer has; xAI answers 400.
+    const body = normalize({
+      model: "grok-4.6",
+      input: "latest xAI news",
+      tools: [{ type: "web_search", external_web_access: false }],
+      tool_choice: "auto",
+    });
+
+    expect(Object.hasOwn(body, "tools")).toBe(false);
+    expect(Object.hasOwn(body, "tool_choice")).toBe(false);
+  });
+
+  test("a prohibition the omission would erase is restated as the explicit empty catalog", () => {
+    // Normalization turns a selector for the removed search into "none", and the request then
+    // says nothing else about what this turn may contain. Omitting that word for the wire without
+    // restating it would leave a body that authorizes more than the caller did.
+    const body = normalize({
+      model: "grok-4.6",
+      input: "latest xAI news",
+      tools: [{ type: "web_search", external_web_access: false }],
+      tool_choice: { type: "web_search" },
+    });
+
+    expect(Object.hasOwn(body, "tool_choice")).toBe(false);
+    expect(body.tools).toEqual([]);
+  });
+
+  test("a caller's own prohibition survives an omission it never asked for", () => {
+    const body = normalize({ model: "grok-4.6", input: "hi", tool_choice: "none" });
+
+    expect(Object.hasOwn(body, "tool_choice")).toBe(false);
+    expect(body.tools).toEqual([]);
+  });
+
+  test("omitting auto invents no catalog the caller never declared", () => {
+    // An absent catalog states no boundary, and a passthrough request may legitimately omit
+    // tools and still receive a call its client understands.
+    const body = normalize({ model: "grok-4.6", input: "hi", tool_choice: "auto" });
+
+    expect(Object.hasOwn(body, "tool_choice")).toBe(false);
+    expect(Object.hasOwn(body, "tools")).toBe(false);
+  });
+
+  test("the restated catalog still refuses a forbidden call in a reconstructed terminal", () => {
+    // The wire-compatibility omission and the reconstruction boundary meet here: the repair reads
+    // the final outbound body, so a request that forbade every client call must still refuse one
+    // that arrives in a sparse stream, and must keep the assistant text that arrived beside it.
+    const terminal = reconstructTerminal(normalize({
+      model: "grok-4.6",
+      input: "latest xAI news",
+      tools: [{ type: "web_search", external_web_access: false }],
+      tool_choice: { type: "web_search" },
+    }));
+    const response = terminal.response as Record<string, unknown>;
+
+    expect(terminal.type).toBe(GROK_REFUSED_TERMINAL_EVENT_TYPE);
+    expect(response.output).toEqual([MESSAGE_ITEM]);
+    expect(response.incomplete_details).toEqual({
+      reason: GROK_FORBIDDEN_TOOL_CALL_REASON,
+      message: forbiddenToolCallMessage(CALL_ITEM.name as string),
+    });
+  });
+
+  test("an explicitly empty catalog carries no selector either", () => {
+    for (const choice of ["auto", "none"]) {
+      const body = normalize({ model: "grok-4.6", input: "hi", tools: [], tool_choice: choice });
+      expect(Object.hasOwn(body, "tool_choice")).toBe(false);
+    }
+  });
+
+  test("a selector that still has a tool to select is left alone", () => {
+    const body = normalize({
+      model: "grok-4.6",
+      input: "hi",
+      tools: [{ type: "function", name: "read_file" }],
+      tool_choice: "auto",
+    });
+
+    expect(body.tool_choice).toBe("auto");
+  });
+
+  test("a forced function selector survives an empty catalog as a client input error", () => {
+    // Dropping it would silently turn "call this tool" into "answer however you like"; the
+    // request-build path answers a selector this proxy cannot honor with a 400 instead.
+    const body = normalize({
+      model: "grok-4.6",
+      input: "hi",
+      tools: [],
+      tool_choice: { type: "function", name: "read_file" },
+    });
+
+    expect(body.tool_choice).toEqual({ type: "function", name: "read_file" });
+  });
+});
diff --git a/tests/providers/xai/xai-web-search-compat.test.ts b/tests/providers/xai/xai-web-search-compat.test.ts
index 67faa1c3f9e..6dd69540f91 100644
--- a/tests/providers/xai/xai-web-search-compat.test.ts
+++ b/tests/providers/xai/xai-web-search-compat.test.ts
@@ -75,11 +75,15 @@ describe("xAI Responses web-search compatibility", () => {
       },
     });
 
-    expect(body.tools).toBeUndefined();
     expect(body.input).toEqual([
       { type: "message", role: "user", content: [{ type: "input_text", text: "hello" }] },
     ]);
-    expect(body.tool_choice).toBe("none");
+    // The selector is omitted because xAI rejects one that selects from a catalog this
+    // normalization emptied, and the deny-all it stated is restated as the explicit empty
+    // catalog. Both spellings forbid every client call this turn; only the second one survives
+    // the wire, and the reconstruction path reads the request's boundary from exactly this body.
+    expect(body).not.toHaveProperty("tool_choice");
+    expect(body.tools).toEqual([]);
   });
 
   test("keeps public xAI search declarations live when the private access flag is absent", () => {
diff --git a/tests/responses/chat-inbound-developer-position.test.ts b/tests/responses/chat-inbound-developer-position.test.ts
new file mode 100644
index 00000000000..9ef81f5ded8
--- /dev/null
+++ b/tests/responses/chat-inbound-developer-position.test.ts
@@ -0,0 +1,277 @@
+/**
+ * A Chat Completions instruction that arrives after the conversation has started keeps the
+ * slot it was written in, on every path that carries the same transcript.
+ *
+ * The translator folded every system and developer message into body.instructions, so
+ * U1 -> A1 -> D2 -> U2 reached the router as instructions plus a three-message input. The
+ * outbound adapter has preserved that slot since #4161 and cannot restore what the inbound
+ * already flattened, and the divergence only appears once a routing feature turns translation
+ * on: an ordinary openai-chat route goes straight to the Chat wire, while a combo enters the
+ * Responses pipeline (src/server/chat-completions.ts).
+ *
+ * The cross-path cases below therefore read the final upstream body on all three paths and
+ * compare it with the transcript the caller sent. A case that hands an already-translated
+ * object to the adapter cannot see this defect at all.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { chatCompletionsToResponsesBody } from "../../src/chat/inbound";
+import { anthropicToResponsesBody } from "../../src/claude/inbound";
+import { parseRequest } from "../../src/responses/parser";
+import { responsesRequestSchema } from "../../src/responses/schema";
+import { handleChatCompletions } from "../../src/server/chat-completions";
+import { handleResponses } from "../../src/server/responses";
+import { clearComboSelectionState, clearComboTargetCooldowns } from "../../src/combos";
+import { clearComboRecallForTests } from "../../src/server/responses/combo-session-recall";
+import { clearKeyCooldowns } from "../../src/providers/key-failover";
+import { clearResponseStateForTests, flushResponseState } from "../../src/responses/state";
+import { resetProviderRequestPacingForTest } from "../../src/providers/request-pacing";
+import { chatStream, chatSuccess } from "../helpers/combo-failover-upstream";
+import { installIsolatedCodexHome, type IsolatedCodexHome } from "../helpers/isolated-codex-home";
+import { acquireOwnedSpendHome } from "../helpers/owned-spend-home";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import type { OcxConfig, OcxProviderConfig } from "../../src/types";
+
+type Rec = Record<string, unknown>;
+
+// One transcript for every case here: an instruction written between two turns.
+const U1 = { role: "user", content: "U1" };
+const A1 = { role: "assistant", content: "A1" };
+const D2 = { role: "developer", content: "D2" };
+const U2 = { role: "user", content: "U2" };
+const TRANSCRIPT = [U1, A1, D2, U2];
+
+function translate(messages: unknown[], extra: Rec = {}): Rec {
+  return chatCompletionsToResponsesBody({ model: "m1", messages, ...extra });
+}
+
+function items(body: Rec): Rec[] {
+  return body.input as Rec[];
+}
+
+function instructionItem(body: Rec): Rec | undefined {
+  return items(body).find(item => item.role === "developer");
+}
+
+function itemShape(body: Rec): string[] {
+  return items(body).map(item => String(item.type) + ":" + String(item.role ?? ""));
+}
+
+describe("Chat translation inbound instruction placement", () => {
+  test("a leading block is still this request's instructions", () => {
+    const body = translate([{ role: "system", content: "S0" }, { role: "developer", content: "D0" }, U1]);
+
+    expect(body.instructions).toBe("S0\n\nD0");
+    expect(items(body)).toEqual([
+      { type: "message", role: "user", content: [{ type: "input_text", text: "U1" }] },
+    ]);
+  });
+
+  test("a developer message past the first turn keeps its slot instead of moving to instructions", () => {
+    const body = translate(TRANSCRIPT);
+
+    expect(body.instructions).toBeUndefined();
+    expect(items(body)).toEqual([
+      { type: "message", role: "user", content: [{ type: "input_text", text: "U1" }] },
+      { type: "message", role: "assistant", content: [{ type: "output_text", text: "A1" }] },
+      { type: "message", role: "developer", content: [{ type: "input_text", text: "D2" }] },
+      { type: "message", role: "user", content: [{ type: "input_text", text: "U2" }] },
+    ]);
+  });
+
+  test("a leading block and a later one land in different places", () => {
+    const body = translate([{ role: "system", content: "S0" }, ...TRANSCRIPT]);
+
+    expect(body.instructions).toBe("S0");
+    expect(itemShape(body)).toEqual([
+      "message:user", "message:assistant", "message:developer", "message:user",
+    ]);
+  });
+
+  // The representation is the Claude inbound's, not a second invention: that path has carried a
+  // mid-conversation instruction as a chronological item since #4148, and a system item would be
+  // refused by the native ChatGPT backend and folded back onto instructions by canonical
+  // forwarding (src/adapters/openai-responses/canonical-forward.ts). Deriving the expected item
+  // from that translator is what keeps the two inbounds in step.
+  test("a mid-conversation system message takes the item the Claude inbound already mints", () => {
+    const claude = anthropicToResponsesBody({
+      model: "m1",
+      messages: [U1, A1, { role: "system", content: "D2" }, U2],
+    });
+    const chat = translate([U1, A1, { role: "system", content: "D2" }, U2]);
+
+    expect(instructionItem(claude)).toBeDefined();
+    expect(instructionItem(chat)).toEqual(instructionItem(claude));
+    expect(chat.instructions).toBeUndefined();
+  });
+
+  test("the translated body is a valid Responses request and parses back as a conversation message", () => {
+    const body = translate(TRANSCRIPT);
+
+    expect(responsesRequestSchema.safeParse(body).success).toBe(true);
+    const parsed = parseRequest(body);
+    expect(parsed.context.messages.map(message => message.role)).toEqual([
+      "user", "assistant", "developer", "user",
+    ]);
+    expect(parsed.context.systemPrompt ?? []).toEqual([]);
+    expect(JSON.stringify(parsed.context.messages[2])).toContain("D2");
+  });
+
+  test("an instruction inside a tool batch waits for the batch instead of splitting the pair", () => {
+    const body = translate([
+      U1,
+      { role: "assistant", tool_calls: [{ id: "call_1", type: "function", function: { name: "f", arguments: "{}" } }] },
+      { role: "developer", content: "D-mid" },
+      { role: "tool", tool_call_id: "call_1", content: "R1" },
+      U2,
+    ]);
+
+    expect(itemShape(body)).toEqual([
+      "message:user", "function_call:", "function_call_output:", "message:developer", "message:user",
+    ]);
+    expect(items(body)[3]).toEqual({
+      type: "message", role: "developer", content: [{ type: "input_text", text: "D-mid" }],
+    });
+    expect(body.instructions).toBeUndefined();
+  });
+
+  test("an abandoned tool batch still releases the held instruction before the next turn", () => {
+    const body = translate([
+      U1,
+      { role: "assistant", tool_calls: [{ id: "call_1", type: "function", function: { name: "f", arguments: "{}" } }] },
+      { role: "developer", content: "D-mid" },
+      U2,
+    ]);
+
+    expect(itemShape(body)).toEqual([
+      "message:user", "function_call:", "message:developer", "message:user",
+    ]);
+  });
+
+  test("an empty instruction produces no item and no instructions", () => {
+    const body = translate([U1, { role: "developer", content: "   " }, U2]);
+
+    expect(itemShape(body)).toEqual(["message:user", "message:user"]);
+    expect(body.instructions).toBeUndefined();
+  });
+});
+
+describe("Chat, combo and Responses paths agree on instruction placement", () => {
+  let testDir = "";
+  let previousHome: string | undefined;
+  let isolatedCodexHome: IsolatedCodexHome | null = null;
+  let releaseSpendHome: (() => void) | undefined;
+  let upstream: ReturnType<typeof Bun.serve> | null = null;
+  let captured: Rec[] = [];
+
+  beforeEach(() => {
+    previousHome = process.env.OPENCODEX_HOME;
+    isolatedCodexHome = installIsolatedCodexHome("ocx-developer-position-codex-");
+    testDir = mkdtempSync(join(tmpdir(), "ocx-developer-position-"));
+    process.env.OPENCODEX_HOME = testDir;
+    // Taken after this suite installs its home so the physical dispatch owns that journal.
+    releaseSpendHome = acquireOwnedSpendHome();
+    clearComboSelectionState();
+    clearComboRecallForTests();
+    clearComboTargetCooldowns();
+    clearKeyCooldowns();
+    clearResponseStateForTests();
+    captured = [];
+    upstream = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      async fetch(request) {
+        const body = await request.json() as Rec;
+        captured.push(body);
+        // Answer the wire each path asked for: the native send keeps the caller's stream bit,
+        // the translated bridge always streams internally.
+        return body.stream === true ? chatStream("ok") : chatSuccess("ok");
+      },
+    });
+  });
+
+  afterEach(async () => {
+    // Released before the home is restored so no live unlinked database survives teardown.
+    releaseSpendHome?.();
+    releaseSpendHome = undefined;
+    await upstream?.stop(true);
+    upstream = null;
+    await flushResponseState();
+    clearResponseStateForTests();
+    clearComboSelectionState();
+    clearComboRecallForTests();
+    clearComboTargetCooldowns();
+    clearKeyCooldowns();
+    resetProviderRequestPacingForTest();
+    if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+    else process.env.OPENCODEX_HOME = previousHome;
+    isolatedCodexHome?.restore();
+    isolatedCodexHome = null;
+    if (testDir) removeTreeWithRetry(testDir);
+  });
+
+  function config(): OcxConfig {
+    const provider: OcxProviderConfig = {
+      adapter: "openai-chat",
+      baseUrl: new URL("/v1", upstream!.url).href,
+      allowPrivateNetwork: true,
+      authMode: "key",
+      apiKey: "fixture-key",
+      // Declared accepting, so the wire role is identical on the native and translated paths
+      // and the comparison below is about placement alone.
+      foldDeveloperRoleToSystem: false,
+    };
+    return {
+      port: 0,
+      defaultProvider: "chat",
+      providers: { chat: provider },
+      combos: { pair: { strategy: "failover", targets: [{ provider: "chat", model: "m1" }] } },
+    };
+  }
+
+  async function chatWireMessages(model: string): Promise<unknown> {
+    const response = await handleChatCompletions(new Request("http://localhost/v1/chat/completions", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ model, stream: false, messages: TRANSCRIPT }),
+    }), config(), { model: "", provider: "" });
+
+    expect(response.status).toBe(200);
+    await response.text();
+    expect(captured).toHaveLength(1);
+    return captured[0]!.messages;
+  }
+
+  async function responsesWireMessages(): Promise<unknown> {
+    const response = await handleResponses(new Request("http://localhost/v1/responses", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        model: "chat/m1",
+        stream: false,
+        store: false,
+        // The canonical Responses spelling of the same transcript.
+        input: items(translate(TRANSCRIPT)),
+      }),
+    }), config(), { model: "", provider: "" });
+
+    expect(response.status).toBe(200);
+    await response.text();
+    expect(captured).toHaveLength(1);
+    return captured[0]!.messages;
+  }
+
+  test("the native Chat route forwards the transcript unchanged", async () => {
+    expect(await chatWireMessages("chat/m1")).toEqual(TRANSCRIPT);
+  });
+
+  test("a combo route translates and still sends the transcript unchanged", async () => {
+    expect(await chatWireMessages("combo/pair")).toEqual(TRANSCRIPT);
+  });
+
+  test("the Responses path sends the same transcript", async () => {
+    expect(await responsesWireMessages()).toEqual(TRANSCRIPT);
+  });
+});
diff --git a/tests/responses/chat-inline-document-bytes.test.ts b/tests/responses/chat-inline-document-bytes.test.ts
new file mode 100644
index 00000000000..17aa779eb8d
--- /dev/null
+++ b/tests/responses/chat-inline-document-bytes.test.ts
@@ -0,0 +1,191 @@
+import { describe, expect, test } from "bun:test";
+import { createAnthropicAdapter } from "../../src/adapters/anthropic";
+import { createOpenAIChatAdapter } from "../../src/adapters/openai-chat";
+import { chatCompletionsToResponsesBody, ChatCompletionsRequestError } from "../../src/chat/inbound";
+import { anthropicToResponsesBody } from "../../src/claude/inbound";
+import { parseRequest } from "../../src/responses/parser";
+import { inlineDocumentDataUrl, inlineDocumentMarker } from "../../src/responses/inline-document";
+import type { OcxParsedRequest, OcxProviderConfig } from "../../src/types";
+
+/**
+ * #5212. Both inbound parsers reduced an attachment to its name before any adapter ran, so no
+ * adapter could forward one even to a target that has a representation for it. The caller could
+ * not tell "the model read the document" from "the model was told a document existed", which is
+ * why every assertion here reads the outbound request rather than the response.
+ */
+
+const PDF_BYTES = "JVBERi0xLjQK";
+// Derived, not restated: the wire spelling is the module's to define, and a test that repeats it
+// fails for the wrong reason the next time it changes.
+const PDF_DATA_URL = inlineDocumentDataUrl({
+  type: "document",
+  text: "",
+  mediaType: "application/pdf",
+  data: PDF_BYTES,
+});
+
+const chatProvider: OcxProviderConfig = {
+  adapter: "openai-chat",
+  baseUrl: "https://gateway.example.internal/v1",
+  apiKey: "k",
+  // The case below asserts that a document survives on a `developer` turn, so it needs the
+  // role to reach the wire. That role folds to `system` unless a destination records that it
+  // accepts it, so the destination records it here; the document contract is what is under
+  // test, not the role decision.
+  foldDeveloperRoleToSystem: false,
+};
+const anthropicProvider = {
+  adapter: "anthropic",
+  baseUrl: "https://api.anthropic.com",
+  apiKey: "sk-x",
+  authMode: "apiKey",
+} as unknown as OcxProviderConfig;
+
+function chatRequest(part: unknown): Record<string, unknown> {
+  return {
+    model: "mock/test-model",
+    messages: [{ role: "user", content: [part] }],
+  };
+}
+
+function claudeRequest(block: unknown): Record<string, unknown> {
+  return {
+    model: "anthropic/claude-sonnet-4.5",
+    max_tokens: 64,
+    messages: [{ role: "user", content: [block] }],
+  };
+}
+
+const DOCUMENT_BLOCK = {
+  type: "document",
+  title: "spec",
+  source: { type: "base64", media_type: "application/pdf", data: PDF_BYTES },
+};
+
+/** The user turn's content, which `inputContentParts` collapses to a string for lone text. */
+function parsedContent(body: Record<string, unknown>): unknown {
+  const parsed = parseRequest(body as never);
+  const user = parsed.context.messages.find(message => message.role === "user");
+  return user!.content;
+}
+
+describe("inline document bytes survive the inbound parse", () => {
+  test("a Chat file part becomes a document carrying its bytes", () => {
+    const content = parsedContent(chatCompletionsToResponsesBody(chatRequest({
+      type: "file",
+      file: { filename: "doc.pdf", file_data: PDF_DATA_URL },
+    })));
+    expect(content).toEqual([
+      {
+        type: "document",
+        text: inlineDocumentMarker("doc.pdf"),
+        mediaType: "application/pdf",
+        data: PDF_BYTES,
+        filename: "doc.pdf",
+      },
+    ]);
+  });
+
+  test("an Anthropic base64 document keeps its bytes and its title", () => {
+    const content = parsedContent(anthropicToResponsesBody(claudeRequest(DOCUMENT_BLOCK)));
+    expect(content).toEqual([
+      {
+        type: "document",
+        text: inlineDocumentMarker("spec"),
+        mediaType: "application/pdf",
+        data: PDF_BYTES,
+        filename: "spec",
+      },
+    ]);
+  });
+
+  test("a document with no usable bytes still reduces to the marker", () => {
+    const content = parsedContent(anthropicToResponsesBody(claudeRequest({
+      type: "document",
+      title: "remote",
+      source: { type: "url", url: "https://example.com/doc.pdf" },
+    })));
+    expect(content).toBe(inlineDocumentMarker("remote"));
+  });
+
+  test("a reference with no payload is still refused rather than answered", () => {
+    expect(() => chatCompletionsToResponsesBody(chatRequest({
+      type: "file",
+      file: { file_id: "file-123" },
+    }))).toThrow(ChatCompletionsRequestError);
+    expect(() => chatCompletionsToResponsesBody(chatRequest({
+      type: "input_audio",
+      input_audio: { data: "AA==", format: "wav" },
+    }))).toThrow(ChatCompletionsRequestError);
+  });
+});
+
+describe("inline document bytes reach a wire that can hold them", () => {
+  function chatOutbound(body: Record<string, unknown>): Record<string, unknown> {
+    const parsed = parseRequest(body as never) as OcxParsedRequest;
+    return JSON.parse(createOpenAIChatAdapter(chatProvider).buildRequest(parsed).body) as Record<string, unknown>;
+  }
+
+  test("an Anthropic document reaches the OpenAI Chat wire as a file part", () => {
+    const outbound = chatOutbound(anthropicToResponsesBody(claudeRequest(DOCUMENT_BLOCK)));
+    const messages = outbound.messages as Array<{ role: string; content: unknown }>;
+    expect(messages.at(-1)).toEqual({
+      role: "user",
+      content: [{ type: "file", file: { file_data: PDF_DATA_URL, filename: "spec" } }],
+    });
+  });
+
+  test("a Chat file part reaches the Anthropic wire as a document block", async () => {
+    const parsed = parseRequest(chatCompletionsToResponsesBody(chatRequest({
+      type: "file",
+      file: { filename: "doc.pdf", file_data: PDF_DATA_URL },
+    })) as never) as OcxParsedRequest;
+    const { body } = await createAnthropicAdapter(anthropicProvider).buildRequest(parsed);
+    const sent = JSON.parse(typeof body === "string" ? body : JSON.stringify(body)) as {
+      messages: Array<{ role: string; content: unknown }>;
+    };
+    expect(sent.messages.at(-1)).toEqual({
+      role: "user",
+      content: [{
+        type: "document",
+        source: { type: "base64", media_type: "application/pdf", data: PDF_BYTES },
+        title: "doc.pdf",
+      }],
+    });
+  });
+
+  test("a document beside text keeps both on the Chat wire", () => {
+    const outbound = chatOutbound(anthropicToResponsesBody({
+      model: "anthropic/claude-sonnet-4.5",
+      max_tokens: 64,
+      messages: [{ role: "user", content: [{ type: "text", text: "Summarize it." }, DOCUMENT_BLOCK] }],
+    }));
+    const messages = outbound.messages as Array<{ role: string; content: unknown[] }>;
+    expect(messages.at(-1)!.content).toEqual([
+      { type: "text", text: "Summarize it." },
+      { type: "file", file: { file_data: PDF_DATA_URL, filename: "spec" } },
+    ]);
+  });
+
+  test("a developer turn carrying a document keeps its role", () => {
+    const parsed = {
+      modelId: "local-model",
+      context: {
+        messages: [{
+          role: "developer",
+          content: [{ type: "document", text: inlineDocumentMarker("spec"), mediaType: "application/pdf", data: PDF_BYTES, filename: "spec" }],
+          timestamp: 0,
+        }],
+      },
+      stream: false,
+      options: {},
+    } as unknown as OcxParsedRequest;
+    const outbound = JSON.parse(createOpenAIChatAdapter(chatProvider).buildRequest(parsed).body) as {
+      messages: Array<{ role: string; content: unknown }>;
+    };
+    expect(outbound.messages).toEqual([{
+      role: "developer",
+      content: [{ type: "file", file: { file_data: PDF_DATA_URL, filename: "spec" } }],
+    }]);
+  });
+});
diff --git a/tests/responses/chat-media-translation.test.ts b/tests/responses/chat-media-translation.test.ts
index a3042d4f3d7..d37c27ec871 100644
--- a/tests/responses/chat-media-translation.test.ts
+++ b/tests/responses/chat-media-translation.test.ts
@@ -16,9 +16,10 @@ const provider: OcxProviderConfig = { adapter: "openai-chat", baseUrl: "https://
 const media = [
   { type: "input_audio", input_audio: { data: "YWJj", format: "wav" } },
   { type: "input_audio", audio_url: "data:audio/wav;base64,YWJj" },
-  { type: "file", file: { filename: "private.pdf", file_data: "data:application/pdf;base64,JVBERi0=" } },
   { type: "input_file", file_id: "file-private" },
 ];
+// An inline document is carried in user content and still has no carrier anywhere else (#5212).
+const INLINE_FILE = { type: "file", file: { filename: "private.pdf", file_data: "data:application/pdf;base64,JVBERi0=" } };
 
 function chat(part: unknown, role = "user") {
   return { model: "model", messages: [{ role, tool_call_id: "call1", content: [{ type: "text", text: "read this" }, part] }] };
@@ -34,9 +35,24 @@ describe("Chat media stays native or fails explicitly at translation", () => {
     }
   });
 
+  test("an inline document is carried in user content and refused where nothing carries it", () => {
+    const translated = chatCompletionsToResponsesBody(chat(INLINE_FILE));
+    expect(translated.input).toEqual([{
+      type: "message",
+      role: "user",
+      content: [
+        { type: "input_text", text: "read this" },
+        { type: "input_file", file_data: "data:application/pdf;base64,JVBERi0=", filename: "private.pdf" },
+      ],
+    }]);
+    for (const role of ["tool", "system", "assistant"]) {
+      expect(() => chatCompletionsToResponsesBody(chat(INLINE_FILE, role))).toThrow("OpenCodex cannot translate");
+    }
+  });
+
   test("the native Chat route retains the caller's exact media blocks", () => {
     const route = { provider, providerName: "gateway", modelId: "model" } as RouteResult;
-    for (const part of media) {
+    for (const part of [...media, INLINE_FILE]) {
       const raw = chat(part);
       expect(isNativeChatRouteEligible(route, raw)).toBe(true);
       const wire = JSON.parse(buildOpenAIChatPassthroughRequest(provider, raw, "model", false).body);
@@ -59,8 +75,9 @@ describe("Chat media stays native or fails explicitly at translation", () => {
   });
 
   test("plain text mentioning an attachment is not treated as one", () => {
-    const out = chatCompletionsToResponsesBody({ model: "model", messages: [{ role: "user", content: JSON.stringify(media) }] });
-    expect(out.input).toEqual([{ type: "message", role: "user", content: [{ type: "input_text", text: JSON.stringify(media) }] }]);
+    const text = JSON.stringify([...media, INLINE_FILE]);
+    const out = chatCompletionsToResponsesBody({ model: "model", messages: [{ role: "user", content: text }] });
+    expect(out.input).toEqual([{ type: "message", role: "user", content: [{ type: "input_text", text }] }]);
   });
 });
 
@@ -93,7 +110,7 @@ test("real HTTP translation refuses media before sending to the selected upstrea
     server = startServer(0);
     for (const part of [
       { type: "input_audio", audio_url: "data:audio/wav;base64,YWJj" },
-      { type: "input_file", filename: "private.pdf", file_data: "data:application/pdf;base64,JVBERi0=" },
+      { type: "input_file", filename: "private.pdf", file_id: "file-private" },
     ]) {
       const response = await fetch(new URL("/v1/responses", server.url), {
         method: "POST", headers: { "Content-Type": "application/json" },
diff --git a/tests/responses/chat-native-developer-role.test.ts b/tests/responses/chat-native-developer-role.test.ts
new file mode 100644
index 00000000000..364b74b5ee1
--- /dev/null
+++ b/tests/responses/chat-native-developer-role.test.ts
@@ -0,0 +1,161 @@
+/**
+ * The native Chat route forwards the caller's messages to the upstream without translating
+ * them, which also meant it never read `foldDeveloperRoleToSystem`. An operator who had
+ * recorded that a destination rejects the `developer` role still sent `developer` there, and
+ * the destination answered `400 role 'developer' is not allowed` before the model saw the
+ * request — a failure that lives outside this repository, which is why nothing here caught it.
+ *
+ * These cases drive the real `/v1/chat/completions` endpoint and read the body the upstream
+ * actually received, because the defect was in which body the route builds, not in what the
+ * adapter returns when it is called directly. The translated route's own role decision is
+ * covered beside that adapter in `tests/adapters/openai/openai-chat-developer-position.test.ts`.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { saveConfig } from "../../src/config";
+import { startServer } from "../../src/server";
+import { installIsolatedCodexHome, type IsolatedCodexHome } from "../helpers/isolated-codex-home";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import type { OcxConfig, OcxProviderConfig } from "../../src/types";
+
+let testDir = "";
+let previousHome: string | undefined;
+let isolatedCodexHome: IsolatedCodexHome | null = null;
+
+beforeEach(() => {
+  previousHome = process.env.OPENCODEX_HOME;
+  isolatedCodexHome = installIsolatedCodexHome("ocx-chat-developer-role-");
+  testDir = mkdtempSync(join(tmpdir(), "ocx-chat-developer-role-"));
+  process.env.OPENCODEX_HOME = testDir;
+});
+
+afterEach(() => {
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  isolatedCodexHome?.restore();
+  isolatedCodexHome = null;
+  if (testDir) removeTreeWithRetry(testDir);
+});
+
+/** A mid-conversation instruction, with a sibling field and turns on both sides of it. */
+const CONVERSATION = [
+  { role: "system", content: "base instructions" },
+  { role: "user", content: "First turn." },
+  { role: "developer", name: "reminder-sentinel", content: "Answer in exactly one sentence." },
+  { role: "user", content: "Second turn." },
+];
+
+/** The instruction's index in the conversation above; it must hold whatever role it carries. */
+const INSTRUCTION_SLOT = CONVERSATION.findIndex(message => message.role === "developer");
+
+/** Send one non-streaming request through the proxy and return the body the upstream received. */
+async function upstreamBodyFor(
+  providerOverrides: Partial<OcxProviderConfig>,
+): Promise<Record<string, unknown>> {
+  const captured: Array<{ pathname: string; body: Record<string, unknown> }> = [];
+  const upstream = Bun.serve({
+    port: 0,
+    async fetch(req) {
+      const { pathname } = new URL(req.url);
+      captured.push({ pathname, body: await req.json() as Record<string, unknown> });
+      // The translated route reaches a different endpoint, so answering every path would let a
+      // rerouted request look like a successful native send.
+      if (!pathname.endsWith("/chat/completions")) {
+        return Response.json({ error: { message: `unexpected path ${pathname}` } }, { status: 404 });
+      }
+      return Response.json({
+        id: "chatcmpl_developer_role",
+        object: "chat.completion",
+        choices: [{ index: 0, message: { role: "assistant", content: "ok" }, finish_reason: "stop" }],
+      });
+    },
+  });
+  saveConfig({
+    port: 0,
+    defaultProvider: "mock",
+    providers: {
+      mock: {
+        adapter: "openai-chat",
+        baseUrl: `${upstream.url.toString().replace(/\/$/, "")}/v1`,
+        apiKey: "k",
+        allowPrivateNetwork: true,
+        ...providerOverrides,
+      },
+    },
+  } as OcxConfig);
+  const server = startServer(0);
+  try {
+    const response = await fetch(new URL("/v1/chat/completions", server.url), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ model: "mock/test-model", stream: false, messages: CONVERSATION }),
+    });
+    expect(response.status).toBe(200);
+    await response.text();
+  } finally {
+    await server.stop(true);
+    upstream.stop(true);
+  }
+  expect(captured).toHaveLength(1);
+  expect(captured[0]!.pathname).toBe("/v1/chat/completions");
+  return captured[0]!.body;
+}
+
+function upstreamMessages(body: Record<string, unknown>): Array<Record<string, unknown>> {
+  return body.messages as Array<Record<string, unknown>>;
+}
+
+describe("the developer role on the native Chat wire", () => {
+  test("an unrecorded destination still receives the caller's messages verbatim", async () => {
+    // The default is the one thing this change must not move: nobody has recorded what this
+    // destination accepts, so the route has no reason to rewrite what the caller sent.
+    expect(upstreamMessages(await upstreamBodyFor({}))).toEqual(CONVERSATION);
+  });
+
+  test("a destination recorded as rejecting the role receives system in the same slot", async () => {
+    const messages = upstreamMessages(await upstreamBodyFor({ foldDeveloperRoleToSystem: true }));
+
+    expect(messages.map(message => message.role)).toEqual(["system", "user", "system", "user"]);
+    // The role changes and nothing else does: the sibling field survives, and so does the text.
+    expect(messages[INSTRUCTION_SLOT]).toEqual({
+      ...CONVERSATION[INSTRUCTION_SLOT]!,
+      role: "system",
+    });
+    // The turns this instruction was written to sit between are still on either side of it.
+    expect(messages.filter((_, index) => index !== INSTRUCTION_SLOT))
+      .toEqual(CONVERSATION.filter((_, index) => index !== INSTRUCTION_SLOT));
+  });
+
+  test("a destination recorded as accepting the role receives it unchanged", async () => {
+    const messages = upstreamMessages(await upstreamBodyFor({ foldDeveloperRoleToSystem: false }));
+
+    expect(messages).toEqual(CONVERSATION);
+    expect(messages[INSTRUCTION_SLOT]!.role).toBe("developer");
+  });
+
+  test("the instruction holds its slot in all three states", async () => {
+    // One request at a time: each one writes the configuration the next server reads.
+    const bodies = [
+      await upstreamBodyFor({}),
+      await upstreamBodyFor({ foldDeveloperRoleToSystem: true }),
+      await upstreamBodyFor({ foldDeveloperRoleToSystem: false }),
+    ];
+
+    for (const body of bodies) {
+      const messages = upstreamMessages(body);
+      expect(messages).toHaveLength(CONVERSATION.length);
+      expect(messages[INSTRUCTION_SLOT]!.content).toBe(CONVERSATION[INSTRUCTION_SLOT]!.content);
+      expect(String(messages[0]!.content)).not.toContain(CONVERSATION[INSTRUCTION_SLOT]!.content);
+    }
+  });
+
+  test("the route remains a passthrough rather than a translation", async () => {
+    const body = await upstreamBodyFor({ foldDeveloperRoleToSystem: true });
+
+    expect(body.model).toBe("test-model");
+    expect(body).not.toHaveProperty("input");
+    expect(body).not.toHaveProperty("instructions");
+  });
+});
diff --git a/tests/responses/chat-tool-choice-allowed-tools.test.ts b/tests/responses/chat-tool-choice-allowed-tools.test.ts
new file mode 100644
index 00000000000..181aaa325b0
--- /dev/null
+++ b/tests/responses/chat-tool-choice-allowed-tools.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, test } from "bun:test";
+import { chatCompletionsToResponsesBody, ChatCompletionsRequestError } from "../../src/chat/inbound";
+import { parseRequest } from "../../src/responses/parser";
+import { createOpenAIChatAdapter } from "../../src/adapters/openai-chat";
+
+/**
+ * #5211 case 1. A Chat Completions caller narrows the catalogue with
+ * `tool_choice.allowed_tools`, and the translated path used to let that object fall past every
+ * branch of `toolChoiceToResponses`: the request kept its full tool list, carried no tool choice
+ * at all, and still answered 200. Asserting on the translated body alone would not catch a
+ * later regression on the way out, so each case here follows the value into the request the
+ * adapter actually sends.
+ */
+
+const CHAT_TOOLS = [
+  { type: "function", function: { name: "tool_a", parameters: { type: "object", properties: {} } } },
+  { type: "function", function: { name: "tool_b", parameters: { type: "object", properties: {} } } },
+];
+
+function chatBody(toolChoice: unknown): Record<string, unknown> {
+  return {
+    model: "mock/test-model",
+    messages: [{ role: "user", content: "Call only tool_b." }],
+    tools: CHAT_TOOLS,
+    tool_choice: toolChoice,
+  };
+}
+
+function outboundBody(toolChoice: unknown): Record<string, unknown> {
+  const translated = chatCompletionsToResponsesBody(chatBody(toolChoice));
+  const parsed = parseRequest(translated as never);
+  const adapter = createOpenAIChatAdapter({
+    adapter: "openai-chat",
+    baseUrl: "https://gateway.example.internal/v1",
+    apiKey: "k",
+  });
+  return JSON.parse(adapter.buildRequest(parsed as never).body) as Record<string, unknown>;
+}
+
+function outboundToolNames(body: Record<string, unknown>): string[] {
+  return (body.tools as Array<{ function?: { name?: string } }>).map(tool => tool.function?.name ?? "");
+}
+
+describe("chat tool_choice allowed_tools reaches the outbound request", () => {
+  test("a single-tool subset narrows the tools the upstream is offered", () => {
+    const body = outboundBody({
+      type: "allowed_tools",
+      allowed_tools: { mode: "required", tools: [{ type: "function", function: { name: "tool_b" } }] },
+    });
+    expect(outboundToolNames(body)).toEqual(["tool_b"]);
+    expect(body.tool_choice).toBe("required");
+  });
+
+  test("a larger subset keeps every allowed tool and drops the rest", () => {
+    const body = outboundBody({
+      type: "allowed_tools",
+      allowed_tools: {
+        mode: "auto",
+        tools: [
+          { type: "function", function: { name: "tool_a" } },
+          { type: "function", function: { name: "tool_b" } },
+        ],
+      },
+    });
+    expect(outboundToolNames(body).sort()).toEqual(["tool_a", "tool_b"]);
+    expect(body.tool_choice).toBe("auto");
+  });
+
+  test("the flat entry spelling and a flat choice object are both accepted", () => {
+    const nested = chatCompletionsToResponsesBody(chatBody({
+      type: "allowed_tools",
+      allowed_tools: { mode: "required", tools: [{ type: "function", name: "tool_a" }] },
+    }));
+    const flat = chatCompletionsToResponsesBody(chatBody({
+      type: "allowed_tools",
+      mode: "required",
+      tools: [{ type: "function", name: "tool_a" }],
+    }));
+    expect(nested.tool_choice)
+      .toEqual({ type: "allowed_tools", mode: "required", tools: [{ type: "function", name: "tool_a" }] });
+    expect(flat.tool_choice).toEqual(nested.tool_choice);
+  });
+
+  test("mode defaults to auto and hosted entries are named by their type", () => {
+    const translated = chatCompletionsToResponsesBody(chatBody({
+      type: "allowed_tools",
+      allowed_tools: { tools: [{ type: "web_search" }] },
+    }));
+    expect(translated.tool_choice)
+      .toEqual({ type: "allowed_tools", mode: "auto", tools: [{ type: "web_search" }] });
+  });
+
+  test("an unnameable entry is refused rather than quietly widening the subset", () => {
+    expect(() => chatCompletionsToResponsesBody(chatBody({
+      type: "allowed_tools",
+      allowed_tools: { mode: "required", tools: [{ type: "function", function: {} }] },
+    }))).toThrow(ChatCompletionsRequestError);
+    expect(() => chatCompletionsToResponsesBody(chatBody({
+      type: "allowed_tools",
+      allowed_tools: { mode: "required", tools: [] },
+    }))).toThrow(ChatCompletionsRequestError);
+  });
+
+  test("a selector kind nobody can evaluate is refused", () => {
+    expect(() => chatCompletionsToResponsesBody(chatBody({
+      type: "allowed_tools",
+      allowed_tools: { mode: "required", tools: [{ type: "mcp", name: "tool_a" }] },
+    }))).toThrow(/unsupported tool_choice.allowed_tools.tools entry type/);
+  });
+
+  test("the existing named and string choices are unchanged", () => {
+    expect(chatCompletionsToResponsesBody(chatBody("required")).tool_choice).toBe("required");
+    expect(chatCompletionsToResponsesBody(chatBody({ type: "function", function: { name: "tool_a" } })).tool_choice)
+      .toEqual({ type: "function", name: "tool_a" });
+  });
+});
diff --git a/tests/responses/opaque-blob-wrapped-rejection.test.ts b/tests/responses/opaque-blob-wrapped-rejection.test.ts
new file mode 100644
index 00000000000..f8a1bced390
--- /dev/null
+++ b/tests/responses/opaque-blob-wrapped-rejection.test.ts
@@ -0,0 +1,171 @@
+import { describe, expect, test } from "bun:test";
+import { shouldAttemptOpaqueBlobRecovery } from "../../src/server/responses/core";
+import { isLiteLlmWrappedCiphertextRejection } from "../../src/server/responses/core-opaque-recovery";
+import { causeForRecoveryKind, resendPermission } from "../../src/lib/request-failure-model";
+
+/**
+ * #5245: an OpenAI-compatible gateway relays the ciphertext rejection inside its own error
+ * string, so the identity the single-shot sanitized rebuild keys on never matched and the turn
+ * failed outright instead of retrying without the stale blob.
+ *
+ * Held in a sibling file rather than appended to responses-opaque-blob-recovery.test.ts, which
+ * sits 148 lines under the size ratchet's new-file threshold. Two branches can each stay under a
+ * cap alone and sum over it together, and the remedy for that is a move, never a number.
+ *
+ * The negative cases carry the weight here. Recognising the wrapper is easy; recognising ONLY
+ * the coded identity through it is the part a broad implementation gets wrong, because rerunning
+ * the whole classifier on the embedded payload silently admits four other identities that were
+ * each accepted on evidence about how one specific upstream words its own rejection.
+ */
+
+const BLOB = "provider-minted-opaque-state";
+
+function outboundWithBlob(): string {
+  return JSON.stringify({
+    model: "model-a",
+    input: [
+      { type: "message", role: "user", content: [{ type: "input_text", text: "before" }] },
+      { type: "reasoning", content: [], summary: [], encrypted_content: BLOB, status: "completed" },
+    ],
+  });
+}
+
+/** An upstream error body as a gateway relays it: the real payload inside a prose message. */
+function wrapped(inner: unknown, trailing = ""): string {
+  return JSON.stringify({
+    error: {
+      message: `litellm.BadRequestError: OpenAIException - ${JSON.stringify(inner)}${trailing}`,
+      type: "invalid_request_error",
+      code: "400",
+    },
+  });
+}
+
+const CODED_CIPHERTEXT_REJECTION = {
+  error: {
+    message: "The encrypted content could not be verified.",
+    type: "invalid_request_error",
+    code: "invalid_encrypted_content",
+  },
+};
+
+const base = {
+  status: 400,
+  adapterName: "openai-responses",
+  outboundBody: outboundWithBlob(),
+  errorBody: wrapped(CODED_CIPHERTEXT_REJECTION),
+  alreadyAttempted: false,
+};
+
+describe("a relayed ciphertext rejection", () => {
+  test("earns the sanitized rebuild the direct rejection already earned", () => {
+    expect(shouldAttemptOpaqueBlobRecovery(base)).toBe(true);
+  });
+
+  test("survives braces and escaped quotes inside the relayed message", () => {
+    const awkward = {
+      error: {
+        message: 'The encrypted content {"id": "a\\"b"} could not be verified.',
+        type: "invalid_request_error",
+        code: "invalid_encrypted_content",
+      },
+    };
+    expect(shouldAttemptOpaqueBlobRecovery({ ...base, errorBody: wrapped(awkward) })).toBe(true);
+  });
+
+  test("survives the prose a gateway appends after the payload", () => {
+    const errorBody = wrapped(CODED_CIPHERTEXT_REJECTION, " Received Model Group=gpt-5");
+    expect(shouldAttemptOpaqueBlobRecovery({ ...base, errorBody })).toBe(true);
+  });
+
+  test("is still single-shot and still requires the send to have carried a blob", () => {
+    expect(shouldAttemptOpaqueBlobRecovery({ ...base, alreadyAttempted: true })).toBe(false);
+    expect(shouldAttemptOpaqueBlobRecovery({
+      ...base,
+      outboundBody: JSON.stringify({ model: "model-a", input: [{ type: "message", role: "user" }] }),
+    })).toBe(false);
+    expect(shouldAttemptOpaqueBlobRecovery({ ...base, status: 500 })).toBe(false);
+    expect(shouldAttemptOpaqueBlobRecovery({ ...base, adapterName: "openai-chat" })).toBe(false);
+  });
+});
+
+describe("the wrapper admits the coded identity and nothing else", () => {
+  /**
+   * Each of these is accepted when the upstream states it DIRECTLY. None may be accepted through
+   * a relay: the wording evidence belongs to the upstream that produced it, and a gateway in
+   * between is not that evidence.
+   */
+  const relayedButNotAdmitted: ReadonlyArray<readonly [string, unknown]> = [
+    ["an unrelated parameter complaint", {
+      error: { type: "invalid_request_error", code: "unknown_parameter", message: "Unknown parameter" },
+    }],
+    ["the code-less unverifiable-ciphertext wording", {
+      error: {
+        type: "invalid_request_error",
+        code: null,
+        message: "The encrypted content 6871-test-ef-0 could not be verified."
+          + " Reason: Encrypted content could not be decrypted or parsed.",
+      },
+    }],
+    ["the caller-mismatch wording", {
+      error: {
+        type: "invalid_request_error",
+        code: null,
+        message: "reasoning `encrypted_content` was not issued to this caller",
+      },
+    }],
+    ["an xAI compaction-blob decoder error", {
+      code: "invalid-argument",
+      error: "Could not decode the compaction blob: invalid payload",
+    }],
+    ["a rate limit", { error: { type: "rate_limit_error", code: "rate_limit_exceeded", message: "Slow down" } }],
+    ["a quota exhaustion", { error: { type: "insufficient_quota", code: "insufficient_quota", message: "No credit" } }],
+    ["a policy refusal", { error: { type: "invalid_request_error", code: "content_policy_violation", message: "Refused" } }],
+  ];
+
+  for (const [label, inner] of relayedButNotAdmitted) {
+    test(`does not resend on ${label}`, () => {
+      expect(shouldAttemptOpaqueBlobRecovery({ ...base, errorBody: wrapped(inner) })).toBe(false);
+    });
+  }
+
+  test("ignores a message that only looks like the wrapper", () => {
+    expect(isLiteLlmWrappedCiphertextRejection(JSON.parse(wrapped(CODED_CIPHERTEXT_REJECTION)))).toBe(true);
+    expect(isLiteLlmWrappedCiphertextRejection({
+      error: { message: `OpenAIException - ${JSON.stringify(CODED_CIPHERTEXT_REJECTION)}` },
+    })).toBe(false);
+    expect(isLiteLlmWrappedCiphertextRejection({ error: { message: "litellm.BadRequestError: no payload" } })).toBe(false);
+    expect(isLiteLlmWrappedCiphertextRejection({ error: { message: 17 } })).toBe(false);
+    expect(isLiteLlmWrappedCiphertextRejection(null)).toBe(false);
+  });
+
+  test("refuses a relayed payload too large to be this envelope", () => {
+    const padded = {
+      error: {
+        message: "x".repeat(20_000),
+        type: "invalid_request_error",
+        code: "invalid_encrypted_content",
+      },
+    };
+    expect(isLiteLlmWrappedCiphertextRejection(JSON.parse(wrapped(padded)))).toBe(false);
+  });
+});
+
+describe("the relayed rejection lands on the shared cause", () => {
+  /**
+   * The recovery this path takes is recorded as `opaque-blob-rejection`, and the shared table has
+   * to agree that a ciphertext refusal is repaired rather than repeated or waited out. If these
+   * ever disagree, the durable log and the metrics projection describe a different decision from
+   * the one the code made.
+   */
+  test("is a ciphertext refusal, repaired rather than repeated", () => {
+    expect(causeForRecoveryKind("opaque-blob-rejection")).toBe("ciphertext-refusal");
+    expect(resendPermission("headers-only", "ciphertext-refusal")).toBe("permitted-after-repair");
+    expect(resendPermission("headers-only", "rate-limit")).toBe("permitted");
+    expect(resendPermission("headers-only", "quota-exhausted")).toBe("refused-futile");
+  });
+
+  test("a ciphertext refusal after output reached the caller is not repaired either", () => {
+    expect(resendPermission("semantic-output", "ciphertext-refusal")).toBe("refused-committed");
+  });
+});
diff --git a/tests/responses/provider-egress-fetch.test.ts b/tests/responses/provider-egress-fetch.test.ts
new file mode 100644
index 00000000000..ff793fba0ee
--- /dev/null
+++ b/tests/responses/provider-egress-fetch.test.ts
@@ -0,0 +1,261 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { CODEX_RESPONSES_HTTP_URL } from "../../src/server/responses/codex-ws-request";
+import { MIN_BOUNDED_CODEX_WS_BUN_VERSION } from "../../src/server/responses/ws-upstream";
+import { InvalidProviderEgressError, PROVIDER_EGRESS_DIRECT } from "../../src/lib/provider-egress";
+import { markEgressTransparentExecutor } from "../../src/lib/provider-egress";
+import {
+  __resetEgressWebsocketDowngradeNotices,
+  providerFetch,
+  sendWithConnectionPolicy,
+} from "../../src/server/responses/fetch-helpers";
+import { PROXY_ENV_KEYS } from "../../src/lib/proxy-env";
+import type { OcxProviderConfig } from "../../src/types";
+
+/**
+ * The inference dispatch. Every Responses, Chat, compaction and continuation send reaches the
+ * wire through `providerFetch`, so this is where a per-provider route has to be applied for a
+ * model call rather than only for discovery.
+ *
+ * Each case asserts the proxy the request was actually pinned to. A test that only asserted a
+ * 200 would pass with the route dropped entirely.
+ */
+const proxyKeys = PROXY_ENV_KEYS.flatMap(key => [key, key.toLowerCase()]);
+const originalProxyEnv = Object.fromEntries(proxyKeys.map(key => [key, process.env[key]]));
+
+afterEach(() => {
+  for (const key of proxyKeys) {
+    const previous = originalProxyEnv[key];
+    if (previous === undefined) delete process.env[key];
+    else process.env[key] = previous;
+  }
+  __resetEgressWebsocketDowngradeNotices();
+});
+
+const TARGET = "https://api.provider.example/v1/responses";
+const PROVIDER_PROXY = "http://provider-egress.example:8080";
+const GLOBAL_PROXY = "http://global-egress.example:3128";
+
+function captureDispatch(): { calls: Array<{ url: string; proxy: unknown }>; restore: () => void } {
+  const calls: Array<{ url: string; proxy: unknown }> = [];
+  const original = globalThis.fetch;
+  const stub = mock(async (input: RequestInfo | URL, init?: RequestInit) => {
+    calls.push({
+      url: typeof input === "string" ? input : input instanceof URL ? input.href : input.url,
+      proxy: (init as { proxy?: unknown } | undefined)?.proxy,
+    });
+    return new Response('{"ok":true}', { status: 200, headers: { "content-type": "application/json" } });
+  });
+  globalThis.fetch = stub as unknown as typeof globalThis.fetch;
+  return { calls, restore: () => { globalThis.fetch = original; } };
+}
+
+function provider(extra: Partial<OcxProviderConfig> = {}): OcxProviderConfig {
+  return { adapter: "openai-responses", baseUrl: "https://api.provider.example/v1", ...extra } as OcxProviderConfig;
+}
+
+describe("per-provider egress on the inference dispatch", () => {
+  test("a provider pinned to direct sends with the runtime's explicit direct connection", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = GLOBAL_PROXY;
+    const captured = captureDispatch();
+    try {
+      await providerFetch(provider({ proxy: PROVIDER_EGRESS_DIRECT }), undefined, { providerName: "vendor" })(
+        TARGET, { method: "POST", body: "{}" },
+      );
+      // `false` rather than an absent option: absent falls back to HTTPS_PROXY, which is set.
+      expect(captured.calls).toEqual([{ url: TARGET, proxy: false }]);
+    } finally {
+      captured.restore();
+    }
+  });
+
+  test("a provider proxy reaches the dispatch instead of the global one", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = GLOBAL_PROXY;
+    const captured = captureDispatch();
+    try {
+      await providerFetch(provider({ proxy: PROVIDER_PROXY }), undefined, { providerName: "vendor" })(
+        TARGET, { method: "POST", body: "{}" },
+      );
+      expect(captured.calls).toEqual([{ url: TARGET, proxy: `${PROVIDER_PROXY}/` }]);
+    } finally {
+      captured.restore();
+    }
+  });
+
+  test("a provider that declares nothing dispatches with no proxy option at all", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = GLOBAL_PROXY;
+    const captured = captureDispatch();
+    try {
+      await providerFetch(provider(), undefined, { providerName: "vendor" })(TARGET, { method: "POST", body: "{}" });
+      expect(captured.calls).toEqual([{ url: TARGET, proxy: undefined }]);
+    } finally {
+      captured.restore();
+    }
+  });
+
+  test("the route is decided per destination, not once per provider", async () => {
+    // One executor, two destinations: the bypass list names one of them. Resolving the route
+    // when the wrapper was built instead of when the request is sent would give both the same
+    // exit and the second assertion would fail.
+    for (const key of proxyKeys) delete process.env[key];
+    const captured = captureDispatch();
+    const send = providerFetch(
+      provider({ proxy: PROVIDER_PROXY, noProxy: "internal.example" }),
+      undefined,
+      { providerName: "vendor" },
+    );
+    try {
+      await send(TARGET, { method: "POST", body: "{}" });
+      await send("https://internal.example/v1/responses", { method: "POST", body: "{}" });
+      expect(captured.calls.map(call => call.proxy)).toEqual([`${PROVIDER_PROXY}/`, false]);
+    } finally {
+      captured.restore();
+    }
+  });
+
+  test("an explicit route moves the WebSocket fast lane onto HTTP rather than dialling past it", async () => {
+    // The WebSocket upstream picks its proxy from the process environment when it dials, so it
+    // cannot carry a per-provider route. Serving the turn over HTTP honours the operator's
+    // choice; dialling anyway would send it out the global exit while the configuration says
+    // otherwise. The downgrade is announced, because a transport change nobody asked for is
+    // exactly the kind of substitution that must not be silent.
+    for (const key of proxyKeys) delete process.env[key];
+    const warnings: string[] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args: unknown[]) => { warnings.push(args.map(String).join(" ")); };
+    const captured = captureDispatch();
+    const streamingPost = { method: "POST", body: JSON.stringify({ stream: true }) } as const;
+    try {
+      const send = providerFetch(
+        provider({ proxy: PROVIDER_PROXY }),
+        MIN_BOUNDED_CODEX_WS_BUN_VERSION,
+        { providerName: "vendor" },
+      );
+      await send(CODEX_RESPONSES_HTTP_URL, { ...streamingPost });
+      await send(CODEX_RESPONSES_HTTP_URL, { ...streamingPost });
+      expect(captured.calls.map(call => call.proxy)).toEqual([`${PROVIDER_PROXY}/`, `${PROVIDER_PROXY}/`]);
+      // Announced once per provider per process, not once per request.
+      expect(warnings.filter(line => line.includes("vendor"))).toHaveLength(1);
+    } finally {
+      captured.restore();
+      console.warn = originalWarn;
+    }
+  });
+
+  test("an explicit route is refused on a caller-supplied executor instead of being dropped", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    const executor = mock(async () => new Response(null, { status: 200 }));
+    const configured = provider({ proxy: PROVIDER_PROXY }) as OcxProviderConfig & { fetch?: typeof globalThis.fetch };
+    configured.fetch = executor as unknown as typeof globalThis.fetch;
+    // The hook must not run either: it commits attempt accounting and consumes admission state,
+    // so charging an attempt for a send that is about to be refused would misreport the attempt
+    // and could mask the egress error behind an unrelated throw.
+    const beforeDispatch = mock(() => undefined);
+    await expect(providerFetch(configured, undefined, { providerName: "vendor", beforeDispatch })(
+      TARGET, { method: "POST", body: "{}" },
+    )).rejects.toThrow(InvalidProviderEgressError);
+    expect(beforeDispatch).not.toHaveBeenCalled();
+    expect(executor).not.toHaveBeenCalled();
+  });
+
+  test("a malformed egress value rejects the send rather than falling back to a route", async () => {
+    for (const key of proxyKeys) delete process.env[key];
+    process.env.HTTPS_PROXY = GLOBAL_PROXY;
+    const captured = captureDispatch();
+    try {
+      await expect(providerFetch(provider({ proxy: "ftp://egress.example" }), undefined, { providerName: "vendor" })(
+        TARGET, { method: "POST", body: "{}" },
+      )).rejects.toThrow(InvalidProviderEgressError);
+      expect(captured.calls).toEqual([]);
+    } finally {
+      captured.restore();
+    }
+  });
+
+  test("a rebuilt request resolves its route against the destination it is actually sent to", async () => {
+    // A queued request can be rebuilt at its physical send -- account reselection can move the
+    // upstream host -- so a route decided when the executor was constructed would be applied to
+    // a host it was not decided for. Here the bypass list names only the rebuilt destination:
+    // resolving early would send it through the proxy, and the credential would leave by a
+    // route the operator excluded. The same class as #4992, which is why the decision now sits
+    // at the same boundary as the connection policy.
+    for (const key of proxyKeys) delete process.env[key];
+    const captured = captureDispatch();
+    const rebuiltUrl = "https://internal.example/v1/responses";
+    try {
+      await providerFetch(
+        provider({ proxy: PROVIDER_PROXY, noProxy: "internal.example" }),
+        undefined,
+        {
+          providerName: "vendor",
+          dispatchOverride: (_input, init, execute) => execute(rebuiltUrl, init),
+        },
+      )(TARGET, { method: "POST", body: "{}" });
+      expect(captured.calls).toEqual([{ url: rebuiltUrl, proxy: false }]);
+    } finally {
+      captured.restore();
+    }
+  });
+
+  test("an internal wrapper that forwards its init still carries the route", async () => {
+    // Not every `provider.fetch` owns a transport. The xAI route installs a wrapper that only
+    // adds a header and delegates; refusing those would make the per-provider proxy unusable on
+    // one of the two providers the original issue names. The marker is opt-in, so an executor
+    // arriving from configuration stays opaque and is still refused.
+    for (const key of proxyKeys) delete process.env[key];
+    const seen: Array<unknown> = [];
+    const wrapper = markEgressTransparentExecutor((async (_input: RequestInfo | URL, init?: RequestInit) => {
+      seen.push((init as { proxy?: unknown } | undefined)?.proxy);
+      return new Response(null, { status: 200 });
+    }) as unknown as typeof globalThis.fetch);
+    const configured = provider({ proxy: PROVIDER_PROXY }) as OcxProviderConfig & { fetch?: typeof globalThis.fetch };
+    configured.fetch = wrapper;
+    await providerFetch(configured, undefined, { providerName: "vendor" })(TARGET, { method: "POST", body: "{}" });
+    expect(seen).toEqual([`${PROVIDER_PROXY}/`]);
+  });
+
+  test("an override that drives the physical boundary itself keeps an ordinary provider routable", async () => {
+    // The production shape: `dispatchOverride` calls the connection policy with
+    // `provider.fetch ?? execute` and its own binding, so `execute` -- the executor this module
+    // supplies -- becomes the selected transport. Treating that wrapper as caller-owned would
+    // refuse every configured provider on this path, and only after the attempt was recorded,
+    // which is precisely the failure an assertion on the returned status cannot see.
+    for (const key of proxyKeys) delete process.env[key];
+    const captured = captureDispatch();
+    const configured = provider({ proxy: PROVIDER_PROXY });
+    try {
+      const response = await providerFetch(configured, undefined, {
+        providerName: "vendor",
+        dispatchOverride: (input, init, execute) =>
+          sendWithConnectionPolicy(execute, input, init, { providerName: "vendor", provider: configured }),
+      })(TARGET, { method: "POST", body: "{}" });
+      expect(response.status).toBe(200);
+      // Decided once, by the boundary that knows the final destination.
+      expect(captured.calls).toEqual([{ url: TARGET, proxy: `${PROVIDER_PROXY}/` }]);
+    } finally {
+      captured.restore();
+    }
+  });
+
+  test("the outermost boundary owns the decision when a reselected provider differs", async () => {
+    // Reselection can replace the provider mid-dispatch, so the override's binding is fresher
+    // than the one captured when the wrapper was built. The inner pass must defer to it rather
+    // than re-deciding from the stale closure and overwriting the route.
+    for (const key of proxyKeys) delete process.env[key];
+    const captured = captureDispatch();
+    const staleProvider = provider({ proxy: PROVIDER_PROXY });
+    const reselected = provider({ proxy: PROVIDER_EGRESS_DIRECT });
+    try {
+      await providerFetch(staleProvider, undefined, {
+        providerName: "vendor",
+        dispatchOverride: (input, init, execute) =>
+          sendWithConnectionPolicy(execute, input, init, { providerName: "vendor", provider: reselected }),
+      })(TARGET, { method: "POST", body: "{}" });
+      expect(captured.calls).toEqual([{ url: TARGET, proxy: false }]);
+    } finally {
+      captured.restore();
+    }
+  });
+});
diff --git a/tests/responses/responses-fetch-helpers-boundary.test.ts b/tests/responses/responses-fetch-helpers-boundary.test.ts
index 787ffe6e286..e2f63efeacd 100644
--- a/tests/responses/responses-fetch-helpers-boundary.test.ts
+++ b/tests/responses/responses-fetch-helpers-boundary.test.ts
@@ -45,7 +45,9 @@ function expectRuntimeImportBoundary(source: string): string[] {
 describe("Responses fetch-helper import boundary", () => {
   test("loads only transport-owned runtime dependencies", () => {
     expect(expectRuntimeImportBoundary(readFileSync(helperPath, "utf8"))).toEqual([
+      "../../lib/provider-egress",
       "../../lib/proxy-env",
+      "../../lib/redact",
       "../../lib/upstream-http-version",
       "../../providers/request-pacing",
       "./ws-upstream",
diff --git a/tests/responses/responses-function-tool-repair.test.ts b/tests/responses/responses-function-tool-repair.test.ts
index 599e9cd9fa9..7577ac1559e 100644
--- a/tests/responses/responses-function-tool-repair.test.ts
+++ b/tests/responses/responses-function-tool-repair.test.ts
@@ -211,6 +211,77 @@ describe("pure function completion repair", () => {
     expect(repairFunctionCalls(missing, schemas).value).toBe(missing);
   });
 
+  test("repairs the exact flat exec_command input wrapper into its required cmd", () => {
+    const shell = {
+      type: "function",
+      name: "exec_command",
+      parameters: {
+        type: "object",
+        properties: { cmd: { type: "string" } },
+        required: ["cmd"],
+        additionalProperties: false,
+      },
+    };
+    const map = collectFunctionCallRepairSchemas({ tools: [shell] });
+    const call = item('{"input":"printf hello"}', { name: "exec_command" });
+    expect(repairFunctionCalls(call, map).value)
+      .toEqual({ ...call, arguments: '{"cmd":"printf hello"}' });
+
+    const reserved = item('{"input":"printf hello"}', {
+      name: "exec_command",
+      namespace: "functions",
+    });
+    expect(repairFunctionCalls(reserved, map).value)
+      .toEqual({ ...reserved, arguments: '{"cmd":"printf hello"}' });
+  });
+
+  test("exec_command input repair stays fail-closed outside the exact schema and payload", () => {
+    const declaration = (parameters: Record<string, unknown>, namespace?: string) => ({
+      type: "function",
+      name: "exec_command",
+      ...(namespace ? { namespace } : {}),
+      parameters,
+    });
+    const canonical = {
+      type: "object",
+      properties: { cmd: { type: "string" } },
+      required: ["cmd"],
+    };
+    const cases: Array<{ payload: string; tool?: ReturnType<typeof declaration> }> = [
+      { payload: '{"cmd":"already canonical"}' },
+      { payload: '{"input":"one","cwd":"/tmp"}' },
+      { payload: '{"input":7}' },
+      { payload: '{"input":"one","cmd":"two"}' },
+      { payload: '{"input":"one"', },
+      { payload: '{"input":"one"}', tool: declaration({ ...canonical, required: [] }) },
+      { payload: '{"input":"one"}', tool: declaration({ ...canonical, properties: { cmd: { type: "number" } } }) },
+    ];
+    for (const entry of cases) {
+      const tool = entry.tool ?? declaration(canonical);
+      const map = collectFunctionCallRepairSchemas({ tools: [tool] });
+      const namespace = tool.namespace;
+      const call = item(entry.payload, {
+        name: namespace ? `${namespace}__exec_command` : "exec_command",
+        ...(namespace ? { namespace } : {}),
+      });
+      expect(repairFunctionCalls(call, map).value).toBe(call);
+    }
+
+    // A namespace is declared by its group, not by a `namespace` property on a
+    // top-level function. Exercise the actual remote identity so this proves the
+    // bare-only repair guard rather than passing because schema lookup missed.
+    const remoteMap = collectFunctionCallRepairSchemas({ tools: [{
+      type: "namespace",
+      name: "remote",
+      tools: [declaration(canonical)],
+    }] });
+    const remoteCall = item('{"input":"one"}', {
+      name: "exec_command",
+      namespace: "remote",
+    });
+    expect(repairFunctionCalls(remoteCall, remoteMap).value).toBe(remoteCall);
+  });
+
   test.each([" ", "{", '{"cell_id":4.5}', '{"yield_time_ms":1.5}', '{"union":4.0}',
     '{"cell_id":9007199254740993}', '{"cell_id":4,"unknown":9007199254740993}', '{"cell_id":4,"unknown":1e400}'])
   ("preserves invalid/disagreeing/unsafe payload %s", argumentsText => {
@@ -269,6 +340,36 @@ describe("native function completion SSE", () => {
     } finally { rewrite.dispose?.(); budget.dispose(); }
   });
 
+  test("repairs exec_command input only at authoritative SSE completion boundaries", () => {
+    const map = collectFunctionCallRepairSchemas({ tools: [{
+      type: "function",
+      name: "exec_command",
+      parameters: {
+        type: "object",
+        properties: { cmd: { type: "string" } },
+        required: ["cmd"],
+      },
+    }] });
+    const rewrite = createResponsesFunctionToolRepairBlockRewrite(map);
+    const shellItem = item("", { name: "exec_command", status: "in_progress" });
+    try {
+      const added = frame("response.output_item.added", { output_index: 0, item: shellItem });
+      const delta = frame("response.function_call_arguments.delta", {
+        item_id: "fc_one",
+        delta: '{"input":"printf hello"}',
+      });
+      expect(rewrite(added)).toEqual([added]);
+      expect(rewrite(delta)).toEqual([delta]);
+      const done = rewrite(frame("response.function_call_arguments.done", {
+        item_id: "fc_one",
+        arguments: '{"input":"printf hello"}',
+      }));
+      expect(payload(done[0]!)).toMatchObject({ arguments: '{"cmd":"printf hello"}' });
+    } finally {
+      rewrite.dispose?.();
+    }
+  });
+
   test.each(["response.output_item.done", "response.completed"])("no-arg %s works without arguments.done", type => {
     const rewrite = createResponsesFunctionToolRepairBlockRewrite(schemas);
     try {
diff --git a/tests/responses/responses-muse-tool-name-alias.test.ts b/tests/responses/responses-muse-tool-name-alias.test.ts
index 30f76330d48..30fc04cfee3 100644
--- a/tests/responses/responses-muse-tool-name-alias.test.ts
+++ b/tests/responses/responses-muse-tool-name-alias.test.ts
@@ -9,6 +9,7 @@ import {
   rewriteMuseToolNamesForUpstream,
 } from "../../src/responses/muse-tool-name-alias";
 import { expandPreviousResponseInput } from "../../src/responses/state";
+import { GROK_REFUSED_TERMINAL_EVENT_TYPE } from "../../src/server/grok-responses-snapshot-repair";
 import { handleResponses } from "../../src/server/responses";
 import type { OcxConfig } from "../../src/types";
 import { acquireOwnedSpendHome } from "../helpers/owned-spend-home";
@@ -269,6 +270,17 @@ describe("muse tool-name inbound restore through handleResponses", () => {
   const frame = (event: string, payload: Record<string, unknown>): string =>
     `event: ${event}\ndata: ${JSON.stringify({ type: event, ...payload })}`;
 
+  const ssePayloads = (text: string): Array<Record<string, unknown>> => text
+    .split(/\r?\n\r?\n/u)
+    .flatMap(block => {
+      const data = block.split(/\r?\n/u)
+        .filter(line => line.startsWith("data: "))
+        .map(line => line.slice("data: ".length))
+        .join("");
+      if (data.length === 0 || data === "[DONE]") return [];
+      return [JSON.parse(data) as Record<string, unknown>];
+    });
+
   test("non-stream function_call and tool_choice restore the original MCP name", async () => {
     const savedFetch = globalThis.fetch;
     let outbound: Record<string, unknown> | undefined;
@@ -336,6 +348,120 @@ describe("muse tool-name inbound restore through handleResponses", () => {
     }
   });
 
+  for (const selectorKind of ["named", "allowed_tools"] as const) {
+    test(`sparse terminal reconstruction keeps the restored identity for ${selectorKind}`, async () => {
+      const savedFetch = globalThis.fetch;
+      let outbound: Record<string, unknown> | undefined;
+      const itemId = "fc_sparse";
+      const callId = "call_sparse";
+      globalThis.fetch = (async (_input, init) => {
+        outbound = JSON.parse(String(init?.body)) as Record<string, unknown>;
+        const choice = outbound.tool_choice as Record<string, unknown>;
+        const wireName = selectorKind === "named"
+          ? choice.name as string
+          : ((choice.tools as Array<{ name: string }>)[0]!.name);
+        const item = {
+          type: "function_call",
+          id: itemId,
+          call_id: callId,
+          name: wireName,
+          arguments: "{}",
+          status: "completed",
+        };
+        const upstream = [
+          frame("response.output_item.done", { output_index: 0, item }),
+          frame("response.completed", { response: { id: "resp_sparse", status: "completed", output: [] } }),
+          "data: [DONE]",
+        ].join("\n\n") + "\n\n";
+        return new Response(upstream, { headers: { "content-type": "text/event-stream" } });
+      }) as typeof fetch;
+      try {
+        takeSpendHome();
+        const toolChoice = selectorKind === "named"
+          ? { type: "function", name: original }
+          : { type: "allowed_tools", mode: "required", tools: [{ type: "function", name: original }] };
+        const response = await handleResponses(new Request("http://localhost/v1/responses", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            model: "fixture/muse-spark-1.3",
+            stream: true,
+            input: "search",
+            tools: [{ type: "function", name: original, parameters: { type: "object" } }],
+            tool_choice: toolChoice,
+          }),
+        }), config, { model: "", provider: "", surface: "grok" });
+        const outboundChoice = outbound?.tool_choice as Record<string, unknown>;
+        const wireName = selectorKind === "named"
+          ? outboundChoice.name as string
+          : ((outboundChoice.tools as Array<{ name: string }>)[0]!.name);
+        expect(wireName).not.toBe(original);
+        expect((outbound?.tools as Array<{ name: string }>)[0]!.name).toBe(wireName);
+
+        const terminal = ssePayloads(await response.text())
+          .find(payload => payload.type === "response.completed");
+        expect(terminal).toBeDefined();
+        expect((terminal!.response as { output: unknown[] }).output).toEqual([expect.objectContaining({
+          type: "function_call",
+          id: itemId,
+          call_id: callId,
+          name: original,
+        })]);
+      } finally {
+        globalThis.fetch = savedFetch;
+      }
+    });
+  }
+
+  test("sparse terminal reconstruction still refuses an unselected aliased tool", async () => {
+    const savedFetch = globalThis.fetch;
+    const selected = original;
+    const unselected = "mcp__plugin_android-emulator_android-emulator__android_install_app";
+    globalThis.fetch = (async (_input, init) => {
+      const outbound = JSON.parse(String(init?.body)) as Record<string, unknown>;
+      const selectedWire = (outbound.tool_choice as { name: string }).name;
+      const wireNames = (outbound.tools as Array<{ name: string }>).map(tool => tool.name);
+      const unselectedWire = wireNames.find(name => name !== selectedWire)!;
+      const item = {
+        type: "function_call",
+        id: "fc_unselected",
+        call_id: "call_unselected",
+        name: unselectedWire,
+        arguments: "{}",
+        status: "completed",
+      };
+      const upstream = [
+        frame("response.output_item.done", { output_index: 0, item }),
+        frame("response.completed", { response: { id: "resp_unselected", status: "completed", output: [] } }),
+        "data: [DONE]",
+      ].join("\n\n") + "\n\n";
+      return new Response(upstream, { headers: { "content-type": "text/event-stream" } });
+    }) as typeof fetch;
+    try {
+      takeSpendHome();
+      const response = await handleResponses(new Request("http://localhost/v1/responses", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "fixture/muse-spark-1.3",
+          stream: true,
+          input: "search",
+          tools: [
+            { type: "function", name: selected, parameters: { type: "object" } },
+            { type: "function", name: unselected, parameters: { type: "object" } },
+          ],
+          tool_choice: { type: "function", name: selected },
+        }),
+      }), config, { model: "", provider: "", surface: "grok" });
+      const terminal = ssePayloads(await response.text())
+        .find(payload => payload.type === GROK_REFUSED_TERMINAL_EVENT_TYPE);
+      expect(terminal).toBeDefined();
+      expect((terminal!.response as { output: unknown[] }).output).toEqual([]);
+    } finally {
+      globalThis.fetch = savedFetch;
+    }
+  });
+
   // #4410: the undeclared-tool guard reads `name` straight off this event, outside any
   // function_call item, so a hashed alias here would still look like an undeclared tool.
   test("streamed response.function_call_arguments.done restores the original name", async () => {
diff --git a/tests/responses/responses-passthrough-transient-policy.test.ts b/tests/responses/responses-passthrough-transient-policy.test.ts
index 77bc00487fe..211d30d1ed7 100644
--- a/tests/responses/responses-passthrough-transient-policy.test.ts
+++ b/tests/responses/responses-passthrough-transient-policy.test.ts
@@ -43,7 +43,12 @@ describe("the Responses passthrough lane reads the provider transient policy", (
   });
 
   test("every transient-retry send takes its attempts from that resolver", () => {
-    const sites = occurrences(packed, "fetchWithTransientRetry(");
+    // Every helper this lane sends through, not just the one it started with. The post-header
+    // replacement reaches upstream exactly like the legs above it and has to draw on the same
+    // resolver; counting only `fetchWithTransientRetry` would let a second send helper be added
+    // on the constant while this file still reported balance.
+    const sites = occurrences(packed, "fetchWithTransientRetry(")
+      + occurrences(packed, "refetchAfterProtocolSafeReset(");
     // The lane's initial send plus its recovery legs. A site that stops being counted here is a
     // site that stopped being governed by the policy.
     expect(sites).toBeGreaterThanOrEqual(4);
diff --git a/tests/responses/responses-reset-replay.test.ts b/tests/responses/responses-reset-replay.test.ts
new file mode 100644
index 00000000000..81b252738d6
--- /dev/null
+++ b/tests/responses/responses-reset-replay.test.ts
@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ambiguousResendAllowanceFor,
+  selfContainedResponsesBody,
+} from "../../src/server/responses/reset-replay";
+import { authorizeResendForRecovery } from "../../src/lib/request-resend-gate";
+
+const clientTurn = {
+  store: false,
+  input: [
+    { type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+    { type: "function_call", name: "read", call_id: "c1", arguments: "{}" },
+    { type: "function_call_output", call_id: "c1", output: "ok" },
+  ],
+  tools: [{ type: "function", name: "read" }],
+};
+
+describe("selfContainedResponsesBody", () => {
+  test("accepts a turn whose second send can only repeat the inference", () => {
+    expect(selfContainedResponsesBody(clientTurn)).toBe(true);
+    expect(selfContainedResponsesBody({ store: false, input: "plain prompt" })).toBe(true);
+    expect(selfContainedResponsesBody({
+      store: false,
+      input: [{ role: "user", content: "hi" }],
+    })).toBe(true);
+  });
+
+  test("refuses anything that leaves state behind or continues someone else's turn", () => {
+    for (const override of [
+      { store: true },
+      { store: undefined },
+      { background: true },
+      { previous_response_id: "resp_1" },
+      { conversation: "conv_1" },
+      { stream_id: undefined },
+      { input: undefined },
+      { input: { not: "a list" } },
+    ]) {
+      expect(selfContainedResponsesBody({ ...clientTurn, ...override })).toBe(false);
+    }
+    expect(selfContainedResponsesBody(null)).toBe(false);
+    expect(selfContainedResponsesBody([clientTurn])).toBe(false);
+  });
+
+  test("refuses a catalog carrying anything the origin would execute", () => {
+    for (const tools of [
+      [{ type: "web_search" }],
+      [{ type: "function", name: "read" }, { type: "mcp", server_label: "s" }],
+      [{ type: "tool_search", execution: "server" }],
+      [{ type: "namespace", name: "ns", tools: [{ type: "code_interpreter" }] }],
+      [{ type: "namespace" }],
+      "not a list",
+    ]) {
+      expect(selfContainedResponsesBody({ ...clientTurn, tools })).toBe(false);
+    }
+    expect(selfContainedResponsesBody({
+      ...clientTurn,
+      tools: [{ type: "namespace", name: "ns", tools: [{ type: "function", name: "read" }] }],
+    })).toBe(true);
+  });
+
+  test("a hosted tool cannot ride in through a deferred declaration", () => {
+    expect(selfContainedResponsesBody({
+      ...clientTurn,
+      input: [...clientTurn.input, { type: "additional_tools", tools: [{ type: "web_search" }] }],
+    })).toBe(false);
+    expect(selfContainedResponsesBody({
+      ...clientTurn,
+      input: [...clientTurn.input, { type: "tool_search_output", tools: [{ type: "function", name: "read" }] }],
+    })).toBe(true);
+  });
+
+  test("an input item type this proxy does not recognise is refused", () => {
+    expect(selfContainedResponsesBody({
+      ...clientTurn,
+      input: [{ type: "image_generation_call", id: "ig1" }],
+    })).toBe(false);
+  });
+});
+
+describe("ambiguousResendAllowanceFor", () => {
+  test("absent or disabled policy grants nothing", () => {
+    const claim = () => true;
+    expect(ambiguousResendAllowanceFor({}, () => true, claim)).toBeUndefined();
+    expect(ambiguousResendAllowanceFor({ retryOnReset: { enabled: false } }, () => true, claim)).toBeUndefined();
+  });
+
+  test("a bare opt-in spends one replacement for the whole request", () => {
+    const limits: number[] = [];
+    let left = 1;
+    const grant = ambiguousResendAllowanceFor({ retryOnReset: {} }, () => true, limit => {
+      limits.push(limit);
+      return left-- > 0;
+    })!;
+    expect(grant.selfContained).toBe(true);
+    expect(grant.claim()).toBe(true);
+    expect(grant.claim()).toBe(false);
+    // Both questions were asked at the same ceiling, against the one request-wide counter.
+    expect(limits).toEqual([1, 1]);
+  });
+
+  test("the body judgment is lazy and reaches the gate as a refusal reason", () => {
+    let judged = 0;
+    const grant = ambiguousResendAllowanceFor({ retryOnReset: {} }, () => { judged += 1; return false; }, () => true)!;
+    expect(judged).toBe(0);
+    const decision = authorizeResendForRecovery("pre-header", "connection-reset", grant);
+    expect(decision.allowed).toBe(false);
+    if (!decision.allowed) expect(decision.refusal).toBe("ambiguous-request-not-replayable");
+    expect(judged).toBe(1);
+  });
+
+  test("a provider that opted in still funds only what the operator asked for", () => {
+    const seen: number[] = [];
+    const grant = ambiguousResendAllowanceFor(
+      { retryOnReset: { replacements: 2 } },
+      () => true,
+      limit => { seen.push(limit); return true; },
+    )!;
+    expect(grant.claim()).toBe(true);
+    expect(seen).toEqual([2]);
+  });
+});
diff --git a/tests/responses/responses-sparse-terminal-tool-scope.test.ts b/tests/responses/responses-sparse-terminal-tool-scope.test.ts
new file mode 100644
index 00000000000..b1344ce73d3
--- /dev/null
+++ b/tests/responses/responses-sparse-terminal-tool-scope.test.ts
@@ -0,0 +1,324 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createGrokResponsesSparseTerminalBlockRewrite,
+  forbiddenToolCallMessage,
+  GROK_FORBIDDEN_TOOL_CALL_REASON,
+  GROK_REFUSED_TERMINAL_EVENT_TYPE,
+} from "../../src/server/grok-responses-snapshot-repair";
+import { rewriteRoutedCustomToolsForUpstream } from "../../src/responses/custom-tool-compat";
+import { rewriteRoutedNamespaceToolsForUpstream } from "../../src/responses/namespace-tool-compat";
+import type { RequestToolScopeCorrespondence } from "../../src/server/responses-request-tool-scope";
+import { createTestTranslatorBudget } from "../helpers/translator-budget";
+
+function dataBlock(payload: unknown): string {
+  return `data: ${JSON.stringify(payload)}`;
+}
+
+function terminalBlock(payload: unknown): string {
+  return `event: response.completed\ndata: ${JSON.stringify(payload)}`;
+}
+
+function payloadOf(block: string): Record<string, unknown> {
+  const data = block.split(/\r?\n/)
+    .filter(line => line.startsWith("data: "))
+    .map(line => line.slice("data: ".length))
+    .join("");
+  return JSON.parse(data) as Record<string, unknown>;
+}
+
+function eventNameOf(block: string): string | undefined {
+  const line = block.split(/\r?\n/).find(candidate => candidate.startsWith("event: "));
+  return line === undefined ? undefined : line.slice("event: ".length);
+}
+
+function responseOf(block: string): Record<string, unknown> {
+  return payloadOf(block).response as Record<string, unknown>;
+}
+
+const MESSAGE_ITEM: Record<string, unknown> = {
+  type: "message",
+  id: "msg_1",
+  role: "assistant",
+  status: "completed",
+  content: [{ type: "output_text", text: "here is the answer", annotations: [] }],
+};
+
+const CALL_ITEM: Record<string, unknown> = {
+  type: "function_call",
+  id: "fc_1",
+  call_id: "call_1",
+  name: "apply_patch",
+  arguments: "{}",
+};
+
+const SPARSE_TERMINAL = {
+  type: "response.completed",
+  response: { id: "resp_1", status: "completed", output: [] },
+};
+
+function relay(
+  outboundBody: unknown,
+  items: readonly { index: number; item: Record<string, unknown> }[],
+  correspondence?: RequestToolScopeCorrespondence,
+): { terminal: string; forwarded: string[] } {
+  const rewrite = createGrokResponsesSparseTerminalBlockRewrite(
+    createTestTranslatorBudget(),
+    outboundBody,
+    correspondence,
+  );
+  const forwarded: string[] = [];
+  for (const { index, item } of items) {
+    forwarded.push(
+      ...rewrite(dataBlock({ type: "response.output_item.done", output_index: index, item })),
+    );
+  }
+  const out = rewrite(terminalBlock(SPARSE_TERMINAL));
+  expect(out).toHaveLength(1);
+  return { terminal: out[0]!, forwarded };
+}
+
+function ordered(...items: Record<string, unknown>[]): { index: number; item: Record<string, unknown> }[] {
+  return items.map((item, index) => ({ index, item }));
+}
+
+describe("Grok sparse terminal reconstruction honours the request's tool selection", () => {
+  test("a request that selected no tools keeps the text and refuses the call explicitly", () => {
+    const { terminal } = relay(
+      { model: "grok-4.6", tools: [{ type: "function", name: "apply_patch" }], tool_choice: "none" },
+      ordered(CALL_ITEM, MESSAGE_ITEM),
+    );
+
+    expect(payloadOf(terminal).type).toBe(GROK_REFUSED_TERMINAL_EVENT_TYPE);
+    expect(eventNameOf(terminal)).toBe(GROK_REFUSED_TERMINAL_EVENT_TYPE);
+    const response = responseOf(terminal);
+    expect(response.status).toBe("incomplete");
+    // The forbidden call is the only casualty; the assistant text that arrived with it survives.
+    expect(response.output).toEqual([MESSAGE_ITEM]);
+    expect(response.incomplete_details).toEqual({
+      reason: GROK_FORBIDDEN_TOOL_CALL_REASON,
+      message: forbiddenToolCallMessage(CALL_ITEM.name as string),
+    });
+  });
+
+  test("a refusal with nothing else to publish is still explicit, not an empty clean finish", () => {
+    const { terminal } = relay(
+      { model: "grok-4.6", tools: [{ type: "function", name: "apply_patch" }], tool_choice: "none" },
+      ordered(CALL_ITEM),
+    );
+
+    expect(payloadOf(terminal).type).toBe(GROK_REFUSED_TERMINAL_EVENT_TYPE);
+    expect(responseOf(terminal).output).toEqual([]);
+  });
+
+  test("the raw stream is forwarded untouched; only the reconstructed terminal is bounded", () => {
+    const { forwarded } = relay(
+      { model: "grok-4.6", tools: [{ type: "function", name: "apply_patch" }], tool_choice: "none" },
+      ordered(CALL_ITEM),
+    );
+
+    expect(forwarded).toEqual([
+      dataBlock({ type: "response.output_item.done", output_index: 0, item: CALL_ITEM }),
+    ]);
+  });
+
+  test("a selection that permits the call reconstructs it unchanged", () => {
+    const { terminal } = relay(
+      {
+        model: "grok-4.6",
+        tools: [{ type: "function", name: "apply_patch" }],
+        tool_choice: { type: "function", name: "apply_patch" },
+      },
+      ordered(CALL_ITEM, MESSAGE_ITEM),
+    );
+
+    expect(payloadOf(terminal).type).toBe("response.completed");
+    expect(responseOf(terminal).output).toEqual([CALL_ITEM, MESSAGE_ITEM]);
+  });
+
+  test("a forced selector for a different tool refuses the call it did not select", () => {
+    const { terminal } = relay(
+      {
+        model: "grok-4.6",
+        tools: [{ type: "function", name: "apply_patch" }, { type: "function", name: "read_file" }],
+        tool_choice: { type: "function", name: "read_file" },
+      },
+      ordered(CALL_ITEM, MESSAGE_ITEM),
+    );
+
+    expect(payloadOf(terminal).type).toBe(GROK_REFUSED_TERMINAL_EVENT_TYPE);
+    expect(responseOf(terminal).output).toEqual([MESSAGE_ITEM]);
+  });
+
+  test("an allow-list admits a listed tool and refuses an unlisted one", () => {
+    const body = {
+      model: "grok-4.6",
+      tools: [{ type: "function", name: "apply_patch" }, { type: "function", name: "read_file" }],
+      tool_choice: {
+        type: "allowed_tools",
+        mode: "auto",
+        tools: [{ type: "function", name: "read_file" }],
+      },
+    };
+    const listed: Record<string, unknown> = { ...CALL_ITEM, name: "read_file" };
+
+    expect(responseOf(relay(body, ordered(listed)).terminal).output).toEqual([listed]);
+    expect(payloadOf(relay(body, ordered(CALL_ITEM, MESSAGE_ITEM)).terminal).type)
+      .toBe(GROK_REFUSED_TERMINAL_EVENT_TYPE);
+  });
+
+  test("a namespaced call matches the selector under either flattened spelling", () => {
+    const namespaced: Record<string, unknown> = { ...CALL_ITEM, name: "search", namespace: "docs" };
+    for (const selected of ["docs__search", "docs.search"]) {
+      const rewritten = rewriteRoutedNamespaceToolsForUpstream({
+        model: "grok-4.6",
+        tools: [{ type: "namespace", name: "docs", tools: [{ type: "function", name: "search" }] }],
+        tool_choice: { type: "function", name: selected },
+      });
+      const { terminal } = relay(
+        rewritten.body,
+        ordered(namespaced),
+        { routedNamespaceToolAliases: rewritten.aliases },
+      );
+      expect(responseOf(terminal).output).toEqual([namespaced]);
+    }
+  });
+
+  test("a qualified selector never admits another namespace with the same basename", () => {
+    const rewritten = rewriteRoutedNamespaceToolsForUpstream({
+      model: "grok-4.6",
+      tools: [
+        { type: "namespace", name: "alpha", tools: [{ type: "function", name: "lookup" }] },
+        { type: "namespace", name: "beta", tools: [{ type: "function", name: "lookup" }] },
+      ],
+      tool_choice: { type: "function", name: "lookup", namespace: "alpha" },
+    });
+    const alpha = { ...CALL_ITEM, name: "lookup", namespace: "alpha" };
+    const beta = { ...CALL_ITEM, name: "lookup", namespace: "beta" };
+    const correspondence = { routedNamespaceToolAliases: rewritten.aliases };
+
+    expect(responseOf(relay(rewritten.body, ordered(alpha), correspondence).terminal).output)
+      .toEqual([alpha]);
+    expect(payloadOf(relay(rewritten.body, ordered(beta), correspondence).terminal).type)
+      .toBe(GROK_REFUSED_TERMINAL_EVENT_TYPE);
+  });
+
+  test("same-named function and custom identities do not match by coincidence", () => {
+    const clientBody = {
+      model: "grok-4.6",
+      tools: [{ type: "function", name: "lookup" }, { type: "custom", name: "lookup" }],
+      tool_choice: { type: "function", name: "lookup" },
+    };
+    const converted = rewriteRoutedCustomToolsForUpstream(clientBody, false);
+    const custom = {
+      type: "custom_tool_call",
+      id: "ctc_1",
+      call_id: "call_1",
+      name: "lookup",
+      input: "query",
+    };
+
+    expect(payloadOf(relay(converted.body, ordered(custom), {
+      clientToolAuthorizationBody: clientBody,
+      convertedRoutedCustomToolNames: converted.names,
+    }).terminal).type)
+      .toBe(GROK_REFUSED_TERMINAL_EVENT_TYPE);
+  });
+
+  test("a request-verified custom-to-function conversion remains authorized", () => {
+    const clientBody = {
+      model: "grok-4.6",
+      tools: [{ type: "custom", name: "shell", description: "run", format: { type: "text" } }],
+      tool_choice: { type: "custom", name: "shell" },
+    };
+    const converted = rewriteRoutedCustomToolsForUpstream(clientBody, false);
+    const namespaced = rewriteRoutedNamespaceToolsForUpstream(converted.body, converted.names);
+    const custom = {
+      type: "custom_tool_call",
+      id: "ctc_1",
+      call_id: "call_1",
+      name: "shell",
+      input: "echo ok",
+    };
+
+    const { terminal } = relay(namespaced.body, ordered(custom, MESSAGE_ITEM), {
+      clientToolAuthorizationBody: clientBody,
+      routedNamespaceToolAliases: namespaced.aliases,
+      convertedRoutedCustomToolNames: converted.names,
+    });
+    expect(responseOf(terminal).output).toEqual([custom, MESSAGE_ITEM]);
+  });
+
+  test("malformed narrowing selectors fail closed instead of becoming unrestricted", () => {
+    for (const toolChoice of [
+      { type: "function", name: "apply_patch", namespace: 42 },
+      { type: "allowed_tools", mode: "auto", tools: "apply_patch" },
+    ]) {
+      const { terminal } = relay(
+        {
+          model: "grok-4.6",
+          tools: [{ type: "function", name: "apply_patch" }],
+          tool_choice: toolChoice,
+        },
+        ordered(CALL_ITEM),
+      );
+      expect(payloadOf(terminal).type).toBe(GROK_REFUSED_TERMINAL_EVENT_TYPE);
+    }
+  });
+
+  test("a catalog emptied by normalization admits no client call, with or without a selector", () => {
+    for (const body of [
+      { model: "grok-4.6", tools: [] },
+      { model: "grok-4.6", tools: [], tool_choice: "auto" },
+      { model: "grok-4.6", tools: [{ type: "web_search" }], tool_choice: "auto" },
+    ]) {
+      const { terminal } = relay(body, ordered(CALL_ITEM, MESSAGE_ITEM));
+      expect(payloadOf(terminal).type).toBe(GROK_REFUSED_TERMINAL_EVENT_TYPE);
+      expect(responseOf(terminal).output).toEqual([MESSAGE_ITEM]);
+    }
+  });
+
+  test("a request that declares no catalog at all keeps its existing reconstruction", () => {
+    // A passthrough request may legitimately omit `tools` and still receive a call the client
+    // understands, so an absent catalog states no boundary for this repair to enforce.
+    const { terminal } = relay({ model: "grok-4.6", input: [] }, ordered(CALL_ITEM, MESSAGE_ITEM));
+
+    expect(payloadOf(terminal).type).toBe("response.completed");
+    expect(responseOf(terminal).output).toEqual([CALL_ITEM, MESSAGE_ITEM]);
+  });
+
+  test("a selection with nothing to refuse reconstructs the ordinary terminal", () => {
+    const { terminal } = relay(
+      { model: "grok-4.6", tools: [{ type: "function", name: "apply_patch" }], tool_choice: "none" },
+      ordered(MESSAGE_ITEM),
+    );
+
+    expect(payloadOf(terminal).type).toBe("response.completed");
+    expect(responseOf(terminal).output).toEqual([MESSAGE_ITEM]);
+  });
+
+  test("a withheld index never fills a gap the stream actually left", () => {
+    const { terminal } = relay(
+      { model: "grok-4.6", tools: [{ type: "function", name: "apply_patch" }], tool_choice: "none" },
+      [{ index: 0, item: CALL_ITEM }, { index: 2, item: MESSAGE_ITEM }],
+    );
+
+    expect(payloadOf(terminal).type).toBe("response.completed");
+    expect(responseOf(terminal).output).toEqual([]);
+  });
+
+  test("refusing a call releases every retained byte", () => {
+    const budget = createTestTranslatorBudget();
+    const rewrite = createGrokResponsesSparseTerminalBlockRewrite(budget, {
+      model: "grok-4.6",
+      tools: [{ type: "function", name: "apply_patch" }],
+      tool_choice: "none",
+    });
+    rewrite(dataBlock({ type: "response.output_item.done", output_index: 0, item: CALL_ITEM }));
+    rewrite(dataBlock({ type: "response.output_item.done", output_index: 1, item: MESSAGE_ITEM }));
+    rewrite(terminalBlock(SPARSE_TERMINAL));
+
+    expect(budget.snapshot().currentBytes).toBe(0);
+    rewrite.dispose?.();
+    expect(budget.snapshot().currentBytes).toBe(0);
+  });
+});
diff --git a/tests/responses/ws-failure-stage.test.ts b/tests/responses/ws-failure-stage.test.ts
index e84145b04dc..7985d979878 100644
--- a/tests/responses/ws-failure-stage.test.ts
+++ b/tests/responses/ws-failure-stage.test.ts
@@ -9,10 +9,12 @@ import {
   closedBeforeTerminalMessage,
   codexWsFailureDetail,
   markCodexWsStage,
+  projectCodexWsFailure,
   readCodexWsStage,
   type CodexWsFailureStage,
   type CodexWsStageRecord,
 } from "../../src/server/responses/codex-ws-wire";
+import { permitsResend, resendPermission } from "../../src/lib/request-failure-model";
 import {
   codexWsUpstreamFetch,
   CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS,
@@ -161,6 +163,41 @@ describe("codex WS failure classification", () => {
       .toBe("before-send");
   });
 
+  /**
+   * The same four outcomes said in the shared stage-and-cause vocabulary, so a WebSocket failure
+   * can be compared with an HTTP one instead of being the one surface with private words for it.
+   * These rows are asserted individually because a projection is a mapping, and a mapping whose
+   * rows are only checked for totality can be rewritten wholesale without any case objecting.
+   */
+  test("projects each outcome onto the shared stage and cause", () => {
+    expect(projectCodexWsFailure(stage({ sent: false, elapsedMs: null })))
+      .toEqual({ stage: "pre-header", cause: "transport-unsent" });
+    expect(projectCodexWsFailure(stage()))
+      .toEqual({ stage: "pre-header", cause: "transport-ambiguous" });
+    expect(projectCodexWsFailure(stage({ upstreamFrames: 3, controlFrames: 3 })))
+      .toEqual({ stage: "protocol-prelude", cause: "transport-ambiguous" });
+    expect(projectCodexWsFailure(stage({ upstreamFrames: 9, controlFrames: 2, relayedEvents: 7 })))
+      .toEqual({ stage: "semantic-output", cause: "transport-ambiguous" });
+  });
+
+  /**
+   * The shared table has to reach the same verdict the transport already enforces on its own, or
+   * one of the two is lying about this exchange. A create frame that never left is the only
+   * outcome the origin provably did not see.
+   */
+  test("only an unsent create frame may be sent again", () => {
+    const resendable = ([
+      stage({ sent: false, elapsedMs: null }),
+      stage(),
+      stage({ upstreamFrames: 3, controlFrames: 3 }),
+      stage({ upstreamFrames: 9, controlFrames: 2, relayedEvents: 7 }),
+    ]).map(candidate => {
+      const projected = projectCodexWsFailure(candidate);
+      return permitsResend(resendPermission(projected.stage, projected.cause));
+    });
+    expect(resendable).toEqual([true, false, false, false]);
+  });
+
   test("renders every field, with n/a for the durations that do not exist yet", () => {
     expect(codexWsFailureDetail(stage({ upstreamFrames: 2, controlFrames: 2, firstFrameMs: 41 }))).toBe(
       " [cause=no-response-event request=812B sent=yes frames=2 control=2 relayed=0"
diff --git a/tests/routing/cl01-openai-chat-review-regressions.test.ts b/tests/routing/cl01-openai-chat-review-regressions.test.ts
index ca0e68781b4..aece7696bc8 100644
--- a/tests/routing/cl01-openai-chat-review-regressions.test.ts
+++ b/tests/routing/cl01-openai-chat-review-regressions.test.ts
@@ -7,6 +7,10 @@ const baseProvider: OcxProviderConfig = {
   baseUrl: "https://api.openai.com/v1",
   apiKey: "sk-test",
   authMode: "key",
+  // The wire role folds to `system` unless a destination is recorded as accepting
+  // `developer`; this case is about placement after a tool result, so it declares the
+  // destination rather than asserting the default.
+  foldDeveloperRoleToSystem: false,
 };
 
 function bodyFor(provider: OcxProviderConfig, parsed: OcxParsedRequest): Record<string, unknown> {
diff --git a/tests/routing/combo-stream-preflight.test.ts b/tests/routing/combo-stream-preflight.test.ts
index 798cce0ef22..29e6d34c3e7 100644
--- a/tests/routing/combo-stream-preflight.test.ts
+++ b/tests/routing/combo-stream-preflight.test.ts
@@ -1,8 +1,10 @@
 import { describe, expect, spyOn, test } from "bun:test";
 import {
   comboStreamPayloadCommitsOutput,
+  deferProtocolSafeResetRecovery,
   preflightComboStreamResponse,
 } from "../../src/server/responses/combo-stream-preflight";
+import { stageCommitment, type RequestFailureStage } from "../../src/lib/request-failure-model";
 import type { RequestLogContext } from "../../src/server/request-log";
 import { MAX_CLIENT_SSE_FRAME_BYTES } from "../../src/server/sse-frame-buffer";
 
@@ -538,7 +540,7 @@ describe("combo stream preflight", () => {
     expect(source.cancelSpy()!.mock.calls).toHaveLength(0);
   });
 
-  test("replayReadErrors accepts a reconstructed prefix and the same reader.read error", async () => {
+  test("replayReadErrors returns a reconstructed prefix, the same read error, and the observed stage", async () => {
     const readError = new Error("preflight-read-reset");
     const source = prefixThenReadError(createdPrefix, readError);
     const result = await preflightComboStreamResponse(
@@ -547,7 +549,14 @@ describe("combo stream preflight", () => {
       undefined,
       { replayReadErrors: true },
     );
-    expect(result.kind).toBe("accepted");
+    expect(result.kind).toBe("read-error");
+    if (result.kind === "read-error") {
+      expect(result.error).toBe(readError);
+      // response.created and nothing else: the failure model puts that in the prelude, and a
+      // prelude is a stage at which the caller has observed nothing.
+      expect(result.stage).toBe("protocol-prelude");
+      expect(stageCommitment(result.stage)).toBe("nothing-observed");
+    }
     expect(source.cancelSpy()).toBeDefined();
     expect(source.cancelSpy()!.mock.calls).toHaveLength(0);
     const reader = result.response.body!.getReader();
@@ -559,4 +568,88 @@ describe("combo stream preflight", () => {
     expect(source.cancelSpy()!.mock.calls).toHaveLength(0);
   });
 
+  test("a read error before any event is headers-only, and a committed stream never reports one", async () => {
+    const readError = new Error("preflight-read-reset");
+    const bare = await preflightComboStreamResponse(
+      prefixThenReadError(new TextEncoder().encode(""), readError).response,
+      { model: "m1", provider: "a" },
+      undefined,
+      { replayReadErrors: true },
+    );
+    expect(bare.kind).toBe("read-error");
+    if (bare.kind === "read-error") {
+      expect(bare.stage).toBe("headers-only");
+      expect(stageCommitment(bare.stage)).toBe("nothing-observed");
+    }
+
+    // Once output commits the preflight stops buffering and hands the body back, so the read
+    // error that follows happens on the caller's side of the boundary and no stage is ever
+    // reported. That is the stronger statement: a committed stream does not reach the resend
+    // gate at all, rather than reaching it and being refused there.
+    const outputPrefix = new TextEncoder().encode(`data: ${JSON.stringify({
+      type: "response.output_text.delta", delta: "hi",
+    })}\n\n`);
+    const committed = await preflightComboStreamResponse(
+      prefixThenReadError(outputPrefix, readError).response,
+      { model: "m1", provider: "a" },
+      undefined,
+      { replayReadErrors: true },
+    );
+    expect(committed.kind).toBe("accepted");
+    // The prefix is still relayed and the error still reaches whoever reads it.
+    const reader = committed.response.body!.getReader();
+    expect((await reader.read()).value).toEqual(outputPrefix);
+    await expect(reader.read()).rejects.toBe(readError);
+  });
+
+  /**
+   * The boundary that decides resend permission, asserted where it is actually enforced.
+   *
+   * The stage a read error is reported at is only half the guarantee. What matters is that a
+   * stream which committed output never gets a replacement offered at all, and the seam that
+   * decides it is the deferred wrapper, not the preflight. The commitment is read from
+   * `stageCommitment` rather than compared against a written-out stage name, so a stage added
+   * to the model later cannot pass this by being unlisted.
+   */
+  test("a replacement is offered only for a stage the caller observed nothing at", async () => {
+    const readError = new Error("preflight-read-reset");
+    const logCtx: RequestLogContext = { model: "m1", provider: "a" };
+    const seen: RequestFailureStage[] = [];
+    const recover = async (_error: unknown, stage: RequestFailureStage): Promise<Response | null> => {
+      seen.push(stage);
+      return null;
+    };
+
+    const prelude = deferProtocolSafeResetRecovery(
+      prefixThenReadError(createdPrefix, readError).response, logCtx, recover);
+    const preludeReader = prelude.body!.getReader();
+    expect((await preludeReader.read()).value).toEqual(createdPrefix);
+    await expect(preludeReader.read()).rejects.toBe(readError);
+    expect(seen).toHaveLength(1);
+    expect(stageCommitment(seen[0]!)).toBe("nothing-observed");
+
+    seen.length = 0;
+    const outputPrefix = new TextEncoder().encode(`data: ${JSON.stringify({
+      type: "response.output_text.delta", delta: "hi",
+    })}\n\n`);
+    const committed = deferProtocolSafeResetRecovery(
+      prefixThenReadError(outputPrefix, readError).response, logCtx, recover);
+    const committedReader = committed.body!.getReader();
+    expect((await committedReader.read()).value).toEqual(outputPrefix);
+    await expect(committedReader.read()).rejects.toBe(readError);
+    // Never consulted. A turn whose output the caller already saw cannot be replaced, and it
+    // does not get as far as asking.
+    expect(seen).toEqual([]);
+  });
+
+  test("a response.created carrying output is not a prelude", () => {
+    expect(comboStreamPayloadCommitsOutput({
+      type: "response.created", response: { id: "r1", output: [] },
+    })).toBe(false);
+    expect(comboStreamPayloadCommitsOutput({
+      type: "response.created",
+      response: { id: "r1", output: [{ type: "message", role: "assistant" }] },
+    })).toBe(true);
+  });
+
 });
diff --git a/tests/server/api-key-model-scope.test.ts b/tests/server/api-key-model-scope.test.ts
new file mode 100644
index 00000000000..51e45b7c8c6
--- /dev/null
+++ b/tests/server/api-key-model-scope.test.ts
@@ -0,0 +1,159 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// The schema this exercises is reached through `src/config`, the entry the
+// runtime evaluates first. Importing `config/schema/*` directly enters that
+// module cycle from the wrong end and throws a TDZ ReferenceError.
+import { loadConfig } from "../../src/config";
+import {
+  admissionModelDeniedBody,
+  AdmissionModelDeniedError,
+  admissionModelDeniedResponse,
+  admissionModelScopeOf,
+  assertRouteAllowedByScope,
+  MODEL_NOT_ALLOWED_FOR_KEY,
+  resolveAdmissionModelScope,
+  routeAllowedByScope,
+} from "../../src/server/admission-model-scope";
+import { routeModel } from "../../src/router";
+import type { OcxConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+const KEY = "ocx_data_" + "a".repeat(40);
+const OTHER_KEY = "ocx_data_" + "b".repeat(40);
+
+const previousHome = process.env.OPENCODEX_HOME;
+const homes: string[] = [];
+
+afterEach(() => {
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  for (const home of homes.splice(0)) removeTreeWithRetry(home);
+});
+
+/** Load a hand-written config.json the way a startup would, and report the keys that survived. */
+function loadKeysFrom(apiKeys: unknown[]): string[] {
+  const home = mkdtempSync(join(tmpdir(), "ocx-key-scope-"));
+  homes.push(home);
+  process.env.OPENCODEX_HOME = home;
+  writeFileSync(join(home, "config.json"), JSON.stringify({
+    port: 10100,
+    defaultProvider: "allowed",
+    providers: { allowed: { adapter: "openai-chat", baseUrl: "https://allowed.test/v1", models: ["small"] } },
+    apiKeys,
+  }));
+  return (loadConfig().apiKeys ?? []).map(entry => entry.name);
+}
+
+function configWithKey(scope: { allowedProviders?: string[]; allowedModels?: string[] }): Pick<OcxConfig, "apiKeys"> {
+  return {
+    apiKeys: [
+      { id: "scoped", name: "mail", key: KEY, createdAt: "2026-01-01T00:00:00.000Z", ...scope },
+      { id: "open", name: "coding", key: OTHER_KEY, createdAt: "2026-01-01T00:00:00.000Z" },
+    ],
+  };
+}
+
+describe("per-key model and provider scope", () => {
+  test("a key with neither list is unrestricted", () => {
+    expect(admissionModelScopeOf({})).toBeUndefined();
+    expect(admissionModelScopeOf({ allowedProviders: [], allowedModels: [] })).toBeUndefined();
+    expect(routeAllowedByScope(undefined, { providerName: "xai", modelId: "grok-4.6" })).toBe(true);
+  });
+
+  test("only a configured key carries a scope", () => {
+    const config = configWithKey({ allowedProviders: ["zai-discount"] });
+    expect(resolveAdmissionModelScope(config, { kind: "configured", keyId: "scoped", source: "bearer" }))
+      .toEqual({ providers: ["zai-discount"], models: [] });
+    // The environment token and loopback have no stored record to attach a
+    // scope to, so narrowing them would be inventing a policy nobody wrote.
+    expect(resolveAdmissionModelScope(config, { kind: "environment", source: "bearer" })).toBeUndefined();
+    expect(resolveAdmissionModelScope(config, { kind: "loopback", source: "loopback" })).toBeUndefined();
+    expect(resolveAdmissionModelScope(config, undefined)).toBeUndefined();
+    expect(resolveAdmissionModelScope(config, { kind: "configured", keyId: "open", source: "bearer" })).toBeUndefined();
+  });
+
+  test("the two lists are independent conditions and both must hold", () => {
+    const scope = admissionModelScopeOf({ allowedProviders: ["zai-discount"], allowedModels: ["glm-5.3-flash"] })!;
+    expect(routeAllowedByScope(scope, { providerName: "zai-discount", modelId: "glm-5.3-flash" })).toBe(true);
+    // The allowed model on a forbidden provider is exactly what a combo child or
+    // a policy fallback reaches while the requested selector never changes.
+    expect(routeAllowedByScope(scope, { providerName: "openrouter", modelId: "glm-5.3-flash" })).toBe(false);
+    // The allowed provider carrying a forbidden model is the mirror case.
+    expect(routeAllowedByScope(scope, { providerName: "zai-discount", modelId: "grok-4.6" })).toBe(false);
+  });
+
+  test("a model entry matches bare or fully qualified, and folds case and spacing", () => {
+    const scope = admissionModelScopeOf({ allowedModels: ["  ZAI-Discount/GLM-5.3-Flash  "] })!;
+    expect(routeAllowedByScope(scope, { providerName: "zai-discount", modelId: "glm-5.3-flash" })).toBe(true);
+    // Pinned to that provider: the same model elsewhere is a different destination.
+    expect(routeAllowedByScope(scope, { providerName: "openrouter", modelId: "glm-5.3-flash" })).toBe(false);
+    const bare = admissionModelScopeOf({ allowedModels: ["glm-5.3-flash"] })!;
+    expect(routeAllowedByScope(bare, { providerName: "openrouter", modelId: "glm-5.3-flash" })).toBe(true);
+  });
+
+  test("an alias is judged by what it resolves to, not by the name the client sent", () => {
+    // The defect this guards: a bare alias names neither the provider nor the
+    // model, so a scope checked against the caller's string has nothing to
+    // match on and would authorize a destination it never saw.
+    const config = {
+      port: 10100,
+      defaultProvider: "allowed",
+      providers: {
+        allowed: { adapter: "openai-chat", baseUrl: "https://allowed.test/v1", models: ["small"] },
+        forbidden: {
+          adapter: "openai-chat", baseUrl: "https://forbidden.test/v1",
+          models: ["expensive"], modelAliases: { expensive: "cheap" },
+        },
+      },
+    } as unknown as OcxConfig;
+    const scope = admissionModelScopeOf({ allowedProviders: ["allowed"] })!;
+
+    const routed = routeModel(config, "cheap");
+    expect(routed).toMatchObject({ providerName: "forbidden", modelId: "expensive" });
+    expect(routeAllowedByScope(scope, routed)).toBe(false);
+    expect(() => assertRouteAllowedByScope(scope, "cheap", routed)).toThrow(AdmissionModelDeniedError);
+
+    const permitted = routeModel(config, "allowed/small");
+    expect(() => assertRouteAllowedByScope(scope, "allowed/small", permitted)).not.toThrow();
+  });
+
+  test("a refusal is 403 and names the caller's own selector", () => {
+    const error = new AdmissionModelDeniedError("gldf-flash", { providerName: "xai", modelId: "grok-4.6" });
+    const body = admissionModelDeniedBody(error);
+    expect(body.error.type).toBe(MODEL_NOT_ALLOWED_FOR_KEY);
+    // The client learns which of its own requests was refused. A key that may
+    // not reach xai has no business learning that its alias points there.
+    expect(body.error.model).toBe("gldf-flash");
+    expect(JSON.stringify(body)).not.toContain("grok-4.6");
+    const response = admissionModelDeniedResponse(error);
+    // 403, not 404: the key authenticated and simply may not go there, and a
+    // 404 would tell the client its credential is wrong and invite a retry.
+    expect(response.status).toBe(403);
+  });
+
+  test("a malformed scope drops the key instead of widening it", () => {
+    const scoped = { key: KEY, id: "scoped", name: "mail", createdAt: "2026-01-01T00:00:00.000Z", allowedProviders: ["zai-discount"] };
+    const open = { key: OTHER_KEY, id: "open", name: "coding", createdAt: "2026-01-01T00:00:00.000Z" };
+    expect(loadKeysFrom([scoped, open])).toEqual(["mail", "coding"]);
+
+    // Every other field on this record degrades to a default. These two must
+    // not: degrading a damaged permission field reads as "allowed everything",
+    // which is the one direction it can never fail. The damaged key is dropped
+    // and its still-valid neighbour survives, so one bad record does not take
+    // the whole array with it.
+    for (const damaged of [
+      { ...scoped, allowedProviders: "zai-discount" },
+      { ...scoped, allowedProviders: [""] },
+      { ...scoped, allowedModels: [123] },
+      { ...scoped, allowedModels: ["x".repeat(257)] },
+    ]) {
+      expect(loadKeysFrom([damaged, open])).toEqual(["coding"]);
+    }
+
+    // A degrading neighbour still degrades, so the fail-closed choice is scoped
+    // to the permission fields rather than hardening the whole record.
+    expect(loadKeysFrom([{ ...scoped, name: 7 }, open])).toHaveLength(2);
+  });
+});
diff --git a/tests/server/api-key-scope-alpha-search.test.ts b/tests/server/api-key-scope-alpha-search.test.ts
new file mode 100644
index 00000000000..769d972a130
--- /dev/null
+++ b/tests/server/api-key-scope-alpha-search.test.ts
@@ -0,0 +1,252 @@
+/**
+ * Per-key model and provider scope on /v1/alpha/search (#5049).
+ *
+ * An account-qualified search model is resolved through the router and was
+ * already covered. The two branches beside it were not: an unqualified model is
+ * relayed verbatim to whichever ChatGPT account the upstream resolves to, and
+ * the sidecar fallback spends the operator configured web-search backend. Both
+ * bill a provider without ever naming a route.
+ */
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { saveConfig } from "../../src/config";
+import { MODEL_NOT_ALLOWED_FOR_KEY, UNNAMED_DESTINATION_MODEL } from "../../src/server/admission-model-scope";
+import type { DataPlaneAdmission } from "../../src/server/auth-cors";
+import type { RequestLogContext } from "../../src/server/request-log";
+import { handleSearch } from "../../src/server/search";
+import type { OcxConfig } from "../../src/types";
+import { fakeChatGptJwt } from "../helpers/fake-chatgpt-jwt";
+import { installIsolatedCodexHome, type IsolatedCodexHome } from "../helpers/isolated-codex-home";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+const SCOPED_KEY = "ocx_data_" + "s".repeat(40);
+const OPEN_KEY = "ocx_data_" + "t".repeat(40);
+const SCOPED: DataPlaneAdmission = { kind: "configured", keyId: "scoped", source: "bearer" };
+const UNSCOPED: DataPlaneAdmission = { kind: "configured", keyId: "open", source: "bearer" };
+const CALLER_TOKEN = fakeChatGptJwt({ chatgpt_account_id: "acct-123" });
+const SEARCH_MODEL = "gpt-search-test";
+const EXA_SEARCH_MODEL = "exa-search-test";
+
+const TEST_DIR = join(import.meta.dir, ".tmp-alpha-search-scope");
+const originalFetch = globalThis.fetch;
+const previousHome = process.env.OPENCODEX_HOME;
+const previousToken = process.env.OPENCODEX_API_AUTH_TOKEN;
+let codexHome: IsolatedCodexHome | null = null;
+let upstreamCalls: string[] = [];
+
+beforeEach(() => {
+  if (existsSync(TEST_DIR)) removeTreeWithRetry(TEST_DIR);
+  mkdirSync(TEST_DIR, { recursive: true });
+  process.env.OPENCODEX_HOME = TEST_DIR;
+  delete process.env.OPENCODEX_API_AUTH_TOKEN;
+  codexHome = installIsolatedCodexHome("ocx-alpha-search-scope-");
+  upstreamCalls = [];
+  globalThis.fetch = (async (input: unknown) => {
+    const url = String(input);
+    upstreamCalls.push(url);
+    if (url.includes("exa.ai")) {
+      return Response.json({
+        results: [{ title: "OpenAI news", url: "https://openai.com/news", text: "Latest OpenAI news." }],
+      });
+    }
+    return Response.json({ encrypted_output: null, output: "search result", results: [] });
+  }) as unknown as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  codexHome?.restore();
+  codexHome = null;
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  if (previousToken === undefined) delete process.env.OPENCODEX_API_AUTH_TOKEN;
+  else process.env.OPENCODEX_API_AUTH_TOKEN = previousToken;
+  if (existsSync(TEST_DIR)) removeTreeWithRetry(TEST_DIR);
+});
+
+type Scope = { allowedProviders?: string[]; allowedModels?: string[] };
+
+function keys(scope: Scope): OcxConfig["apiKeys"] {
+  return [
+    { id: "scoped", name: "mail", key: SCOPED_KEY, createdAt: "2026-01-01T00:00:00.000Z", ...scope },
+    { id: "open", name: "coding", key: OPEN_KEY, createdAt: "2026-01-01T00:00:00.000Z" },
+  ];
+}
+
+/** A ChatGPT forward provider the caller authenticates directly, as codex does. */
+function forwardConfig(scope: Scope): OcxConfig {
+  const config = {
+    port: 0,
+    defaultProvider: "openai",
+    openaiProviderTierVersion: 2,
+    providers: {
+      openai: {
+        adapter: "openai-responses",
+        baseUrl: "https://chatgpt.com/backend-api/codex",
+        authMode: "forward",
+        codexAccountMode: "direct",
+      },
+    },
+    apiKeys: keys(scope),
+  } as OcxConfig;
+  saveConfig(config);
+  return config;
+}
+
+/** No forward candidate at all, which is the only state the sidecar fallback runs in. */
+function sidecarConfig(scope: Scope): OcxConfig {
+  const config = {
+    port: 0,
+    defaultProvider: "groq",
+    providers: {
+      groq: { adapter: "openai-chat", baseUrl: "https://api.groq.example/v1", apiKey: "gsk-x" },
+    },
+    webSearchSidecar: { backend: "exa", exaApiKey: "exa-fixture-key", model: EXA_SEARCH_MODEL },
+    apiKeys: keys(scope),
+  } as unknown as OcxConfig;
+  saveConfig(config);
+  return config;
+}
+
+function logContext(): RequestLogContext {
+  return { model: "web_search", provider: "unknown" } as RequestLogContext;
+}
+
+function forwardRequest(body: Record<string, unknown>, key = SCOPED_KEY): Request {
+  return new Request("http://127.0.0.1/v1/alpha/search", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-opencodex-api-key": key,
+      authorization: "Bearer " + CALLER_TOKEN,
+      "chatgpt-account-id": "acct-123",
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+function sidecarRequest(body: Record<string, unknown>): Request {
+  return new Request("http://127.0.0.1/v1/alpha/search", {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-opencodex-api-key": SCOPED_KEY },
+    body: JSON.stringify(body),
+  });
+}
+
+function searchBody(model?: string): Record<string, unknown> {
+  return {
+    id: "search-session",
+    ...(model ? { model } : {}),
+    commands: { search_query: [{ q: "OpenAI news" }] },
+  };
+}
+
+async function denial(response: Response): Promise<{ type: string; model: string }> {
+  const payload = await response.json() as { error: { type: string; model: string } };
+  return payload.error;
+}
+
+test("an unqualified search model cannot reach a provider outside the scope", async () => {
+  const response = await handleSearch(
+    forwardRequest(searchBody(SEARCH_MODEL)),
+    forwardConfig({ allowedProviders: ["anthropic"] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  const error = await denial(response);
+  expect(error.type).toBe(MODEL_NOT_ALLOWED_FOR_KEY);
+  expect(error.model).toBe(SEARCH_MODEL);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("an unqualified search model is checked as the destination it becomes", async () => {
+  const response = await handleSearch(
+    forwardRequest(searchBody(SEARCH_MODEL)),
+    forwardConfig({ allowedModels: ["some-other-model"] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("a search body that names no model cannot satisfy a model list", async () => {
+  const response = await handleSearch(
+    forwardRequest(searchBody()),
+    forwardConfig({ allowedModels: [SEARCH_MODEL] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  expect((await denial(response)).model).toBe(UNNAMED_DESTINATION_MODEL);
+});
+
+test("the relay still runs when the scope names its destination", async () => {
+  const response = await handleSearch(
+    forwardRequest(searchBody(SEARCH_MODEL)),
+    forwardConfig({ allowedProviders: ["openai"], allowedModels: [SEARCH_MODEL] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(200);
+  expect(upstreamCalls).toHaveLength(1);
+  expect(upstreamCalls[0]).toContain("/alpha/search");
+});
+
+test("the sidecar fallback refuses the backend it would have spent", async () => {
+  const response = await handleSearch(
+    sidecarRequest(searchBody(SEARCH_MODEL)),
+    sidecarConfig({ allowedProviders: ["openai"] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  expect((await denial(response)).type).toBe(MODEL_NOT_ALLOWED_FOR_KEY);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("the sidecar fallback is judged on the model the operator configured", async () => {
+  const response = await handleSearch(
+    sidecarRequest(searchBody(SEARCH_MODEL)),
+    sidecarConfig({ allowedProviders: ["exa"], allowedModels: [SEARCH_MODEL] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  // The caller's own selector is allowed; the backend runs a different model,
+  // and that is the one the scope is applied to.
+  expect(response.status).toBe(403);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("an allowed sidecar backend still answers the search", async () => {
+  const response = await handleSearch(
+    sidecarRequest(searchBody(SEARCH_MODEL)),
+    sidecarConfig({ allowedProviders: ["exa"], allowedModels: [EXA_SEARCH_MODEL] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(200);
+  expect(upstreamCalls).toHaveLength(1);
+  expect(upstreamCalls[0]).toContain("exa.ai");
+});
+
+test("a key with no scope keeps both search branches", async () => {
+  const response = await handleSearch(
+    forwardRequest(searchBody(SEARCH_MODEL), OPEN_KEY),
+    forwardConfig({ allowedProviders: ["anthropic"] }),
+    logContext(),
+    undefined,
+    UNSCOPED,
+  );
+  expect(response.status).toBe(200);
+  expect(upstreamCalls).toHaveLength(1);
+});
diff --git a/tests/server/api-key-scope-audio.test.ts b/tests/server/api-key-scope-audio.test.ts
new file mode 100644
index 00000000000..eaa7c916402
--- /dev/null
+++ b/tests/server/api-key-scope-audio.test.ts
@@ -0,0 +1,250 @@
+/**
+ * Per-key model and provider scope on the audio and voice data planes (#5049).
+ *
+ * None of these endpoints resolves a model through the router, so the scope
+ * landed with #5265 did not reach them. They share one upstream decision in
+ * `resolveAudioUpstream`, and the model it is given is the model the upstream
+ * will run, so the refusal is asserted once per endpoint that reaches it.
+ */
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MODEL_NOT_ALLOWED_FOR_KEY } from "../../src/server/admission-model-scope";
+import { resolveAudioClient, type AudioClient } from "../../src/server/audio-client";
+import { resolveDictationSocket } from "../../src/server/audio-dictation";
+import { handleExternalLive, resolveExternalLiveSocket } from "../../src/server/audio-live";
+import { handleAudioTranscriptions } from "../../src/server/audio-transcriptions";
+import { LIVE_AUDIO_MODEL, TRANSCRIPTION_MODEL } from "../../src/server/audio-upstream";
+import { LiveCallBindings } from "../../src/server/live-call-bindings";
+import { tryAdmitTurn } from "../../src/server/lifecycle";
+import type { RequestLogContext } from "../../src/server/request-log";
+import type { AdmissionLease } from "../../src/lib/admission";
+import type { OcxConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+const SCOPED_KEY = "ocx_data_" + "a".repeat(40);
+const OPEN_KEY = "ocx_data_" + "b".repeat(40);
+const OTHER_LIVE_MODEL = "gpt-live-1-experimental";
+
+const originalFetch = globalThis.fetch;
+const previousHome = process.env.OPENCODEX_HOME;
+let home = "";
+let upstreamCalls: string[] = [];
+let leases: AdmissionLease[] = [];
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "ocx-audio-scope-"));
+  process.env.OPENCODEX_HOME = home;
+  upstreamCalls = [];
+  leases = [];
+  globalThis.fetch = (async (input: unknown) => {
+    upstreamCalls.push(String(input));
+    return Response.json({ text: "hello" });
+  }) as unknown as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  for (const lease of leases.splice(0)) lease.release();
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  if (home) removeTreeWithRetry(home);
+  home = "";
+});
+
+type Scope = { allowedProviders?: string[]; allowedModels?: string[] };
+
+/**
+ * A keyed OpenAI platform provider and nothing else: the audio upstream then
+ * resolves without a stored ChatGPT credential, so each case exercises the
+ * scope decision rather than account selection.
+ */
+function config(scope: Scope): OcxConfig {
+  return {
+    port: 0,
+    hostname: "127.0.0.1",
+    defaultProvider: "openai-apikey",
+    providers: {
+      "openai-apikey": {
+        adapter: "openai-responses",
+        baseUrl: "https://api.openai.com/v1",
+        apiKey: "fixture-upstream-key",
+        authMode: "key",
+      },
+    },
+    apiKeys: [
+      { id: "scoped", name: "mail", key: SCOPED_KEY, createdAt: "2026-01-01T00:00:00.000Z", ...scope },
+      { id: "open", name: "coding", key: OPEN_KEY, createdAt: "2026-01-01T00:00:00.000Z" },
+    ],
+  } as OcxConfig;
+}
+
+function logContext(): RequestLogContext {
+  return { model: "unknown", provider: "unknown" } as RequestLogContext;
+}
+
+function lease(): AdmissionLease {
+  const admitted = tryAdmitTurn();
+  if (!admitted) throw new Error("the turn gate refused an idle test lease");
+  leases.push(admitted);
+  return admitted;
+}
+
+function client(cfg: OcxConfig, key = SCOPED_KEY): AudioClient {
+  const resolved = resolveAudioClient(
+    new Request("http://localhost/v1/live", { headers: { "x-opencodex-api-key": key } }),
+    cfg,
+  );
+  if (!resolved || resolved instanceof Response) throw new Error("the audio key was not admitted");
+  return resolved;
+}
+
+function transcriptionRequest(): Request {
+  const form = new FormData();
+  form.append("file", new File([new Uint8Array([82, 73, 70, 70, 0, 0])], "sample.wav", { type: "audio/wav" }));
+  form.append("model", TRANSCRIPTION_MODEL);
+  return new Request("http://localhost/v1/audio/transcriptions", {
+    method: "POST",
+    headers: { "x-opencodex-api-key": SCOPED_KEY },
+    body: form,
+  });
+}
+
+async function denial(response: Response): Promise<{ type: string; model: string }> {
+  const payload = await response.json() as { error: { type: string; model: string } };
+  return payload.error;
+}
+
+test("file transcription refuses a provider the key may not reach", async () => {
+  const cfg = config({ allowedProviders: ["some-other-provider"] });
+  const response = await handleAudioTranscriptions(
+    transcriptionRequest(),
+    cfg,
+    logContext(),
+    client(cfg).admission,
+  );
+  expect(response.status).toBe(403);
+  const error = await denial(response);
+  expect(error.type).toBe(MODEL_NOT_ALLOWED_FOR_KEY);
+  expect(error.model).toBe(TRANSCRIPTION_MODEL);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("file transcription still runs when the scope names its destination", async () => {
+  const cfg = config({ allowedProviders: ["openai-apikey"], allowedModels: [TRANSCRIPTION_MODEL] });
+  const response = await handleAudioTranscriptions(
+    transcriptionRequest(),
+    cfg,
+    logContext(),
+    client(cfg).admission,
+  );
+  expect(response.status).toBe(200);
+  expect(upstreamCalls).toHaveLength(1);
+});
+
+test("the dictation socket refuses before it resolves a credential", async () => {
+  const cfg = config({ allowedProviders: ["some-other-provider"] });
+  const resolved = await resolveDictationSocket(client(cfg), cfg, logContext(), lease());
+  expect(resolved).toBeInstanceOf(Response);
+  const response = resolved as Response;
+  expect(response.status).toBe(403);
+  expect((await denial(response)).type).toBe(MODEL_NOT_ALLOWED_FOR_KEY);
+});
+
+test("an allowed dictation key reaches its own capability error instead", async () => {
+  const cfg = config({ allowedModels: [TRANSCRIPTION_MODEL] });
+  const resolved = await resolveDictationSocket(client(cfg), cfg, logContext(), lease());
+  expect(resolved).toBeInstanceOf(Response);
+  // Streaming dictation needs a ChatGPT account; the point is that the scope is
+  // no longer what stops it.
+  expect((resolved as Response).status).toBe(400);
+});
+
+test("voice call-create refuses the live model the session names", async () => {
+  const cfg = config({ allowedModels: ["gpt-4o-transcribe-only"] });
+  const response = await handleExternalLive(
+    new Request("http://localhost/v1/live", {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-opencodex-api-key": SCOPED_KEY },
+      body: JSON.stringify({ sdp: "v=0" }),
+    }),
+    cfg,
+    logContext(),
+    { client: client(cfg), lease: lease(), bindings: new LiveCallBindings() },
+  );
+  expect(response.status).toBe(403);
+  const error = await denial(response);
+  expect(error.type).toBe(MODEL_NOT_ALLOWED_FOR_KEY);
+  expect(error.model).toBe(LIVE_AUDIO_MODEL);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("a standalone realtime socket is judged on the model in its own query", async () => {
+  const cfg = config({ allowedModels: [LIVE_AUDIO_MODEL] });
+  const resolved = await resolveExternalLiveSocket(
+    client(cfg),
+    cfg,
+    logContext(),
+    { style: "frameless-standalone", query: "model=" + OTHER_LIVE_MODEL },
+    { lease: lease(), bindings: new LiveCallBindings() },
+  );
+  expect(resolved).toBeInstanceOf(Response);
+  const response = resolved as Response;
+  expect(response.status).toBe(403);
+  expect((await denial(response)).model).toBe(OTHER_LIVE_MODEL);
+});
+
+test("a Realtime standalone socket is judged on its query too, not the default", async () => {
+  // The Frameless branch rewrites its query and was the only one read. A
+  // Realtime standalone socket forwards `model=` untouched, so reading the
+  // default here admitted a model the caller was never allowed to run.
+  const cfg = config({ allowedModels: [LIVE_AUDIO_MODEL] });
+  const resolved = await resolveExternalLiveSocket(
+    client(cfg),
+    cfg,
+    logContext(),
+    { style: "realtime-standalone", query: "intent=quicksilver&model=" + OTHER_LIVE_MODEL },
+    { lease: lease(), bindings: new LiveCallBindings() },
+  );
+  expect(resolved).toBeInstanceOf(Response);
+  expect((resolved as Response).status).toBe(403);
+  expect((await denial(resolved as Response)).model).toBe(OTHER_LIVE_MODEL);
+});
+
+test("rejoining a call is judged on the model that call settled on", async () => {
+  const cfg = config({ allowedModels: [LIVE_AUDIO_MODEL] });
+  const audio = client(cfg);
+  const bindings = new LiveCallBindings();
+  const alias = bindings.create({
+    owner: audio.owner,
+    upstreamCallId: "call-upstream",
+    joinStyle: "frameless-path",
+    providerName: "openai-apikey",
+    model: OTHER_LIVE_MODEL,
+    callerOwned: false,
+  });
+  expect(alias).not.toBeNull();
+  const resolved = await resolveExternalLiveSocket(
+    audio,
+    cfg,
+    logContext(),
+    { style: "frameless-path", callId: alias as string },
+    { lease: lease(), bindings },
+  );
+  expect(resolved).toBeInstanceOf(Response);
+  expect((resolved as Response).status).toBe(403);
+  expect((await denial(resolved as Response)).model).toBe(OTHER_LIVE_MODEL);
+});
+
+test("a key with no scope keeps every audio destination", async () => {
+  const cfg = config({ allowedProviders: ["some-other-provider"] });
+  const response = await handleAudioTranscriptions(
+    transcriptionRequest(),
+    cfg,
+    logContext(),
+    client(cfg, OPEN_KEY).admission,
+  );
+  expect(response.status).toBe(200);
+  expect(upstreamCalls).toHaveLength(1);
+});
diff --git a/tests/server/api-key-scope-images.test.ts b/tests/server/api-key-scope-images.test.ts
new file mode 100644
index 00000000000..754c87a50e1
--- /dev/null
+++ b/tests/server/api-key-scope-images.test.ts
@@ -0,0 +1,202 @@
+/**
+ * Per-key model and provider scope on the standalone Images relay (#5049).
+ *
+ * This endpoint never enters the router, so the scope landed with #5265 did not
+ * reach it: an authenticated key could spend any configured image backend. Each
+ * case below pins one of the four destinations this handler can choose and
+ * asserts the refusal happens before the paid upstream call.
+ */
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MODEL_NOT_ALLOWED_FOR_KEY, UNNAMED_DESTINATION_MODEL } from "../../src/server/admission-model-scope";
+import type { DataPlaneAdmission } from "../../src/server/auth-cors";
+import { handleImages } from "../../src/server/images";
+import type { RequestLogContext } from "../../src/server/request-log";
+import type { OcxConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+const SCOPED_KEY = "ocx_data_" + "i".repeat(40);
+const OPEN_KEY = "ocx_data_" + "o".repeat(40);
+const SCOPED: DataPlaneAdmission = { kind: "configured", keyId: "scoped", source: "bearer" };
+const UNSCOPED: DataPlaneAdmission = { kind: "configured", keyId: "open", source: "bearer" };
+
+const originalFetch = globalThis.fetch;
+const previousHome = process.env.OPENCODEX_HOME;
+let home = "";
+let upstreamCalls: string[] = [];
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "ocx-images-scope-"));
+  process.env.OPENCODEX_HOME = home;
+  upstreamCalls = [];
+  globalThis.fetch = (async (input: unknown) => {
+    upstreamCalls.push(String(input));
+    return Response.json({ created: 1, data: [{ b64_json: "aGk=" }] });
+  }) as unknown as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  if (home) removeTreeWithRetry(home);
+  home = "";
+});
+
+type Scope = { allowedProviders?: string[]; allowedModels?: string[] };
+
+function config(scope: Scope, overrides: Partial<OcxConfig> = {}): OcxConfig {
+  return {
+    port: 0,
+    hostname: "127.0.0.1",
+    defaultProvider: "openai-apikey",
+    providers: {
+      "openai-apikey": {
+        adapter: "openai-responses",
+        baseUrl: "https://api.openai.com/v1",
+        apiKey: "fixture-images-key",
+        authMode: "key",
+      },
+    },
+    apiKeys: [
+      { id: "scoped", name: "mail", key: SCOPED_KEY, createdAt: "2026-01-01T00:00:00.000Z", ...scope },
+      { id: "open", name: "coding", key: OPEN_KEY, createdAt: "2026-01-01T00:00:00.000Z" },
+    ],
+    ...overrides,
+  } as OcxConfig;
+}
+
+function imagesRequest(body: Record<string, unknown>): Request {
+  return new Request("http://localhost/v1/images/generations", {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: "Bearer " + SCOPED_KEY },
+    body: JSON.stringify(body),
+  });
+}
+
+function logContext(): RequestLogContext {
+  return { model: "image_gen", provider: "unknown" } as RequestLogContext;
+}
+
+async function denial(response: Response): Promise<{ type: string; model: string }> {
+  const payload = await response.json() as { error: { type: string; model: string } };
+  return payload.error;
+}
+
+test("a scoped key cannot relay images through a provider it may not reach", async () => {
+  const response = await handleImages(
+    imagesRequest({ model: "gpt-image-1", prompt: "a cat" }),
+    config({ allowedProviders: ["some-other-provider"] }),
+    "generations",
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  const error = await denial(response);
+  expect(error.type).toBe(MODEL_NOT_ALLOWED_FOR_KEY);
+  // The caller learns which of its own requests was refused, nothing about the destination.
+  expect(error.model).toBe("gpt-image-1");
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("the same key still reaches the destination its scope names", async () => {
+  const response = await handleImages(
+    imagesRequest({ model: "gpt-image-1", prompt: "a cat" }),
+    config({ allowedProviders: ["openai-apikey"], allowedModels: ["gpt-image-1"] }),
+    "generations",
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(200);
+  expect(upstreamCalls).toHaveLength(1);
+  expect(upstreamCalls[0]).toContain("/v1/images/generations");
+});
+
+test("a body that names no model cannot satisfy a model list", async () => {
+  const response = await handleImages(
+    imagesRequest({ prompt: "a cat" }),
+    config({ allowedModels: ["gpt-image-1"] }),
+    "generations",
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  expect((await denial(response)).model).toBe(UNNAMED_DESTINATION_MODEL);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("naming the refusal marker in a scope grants nothing", async () => {
+  // The marker is how a refusal says "nobody named a model". An operator who
+  // copies it out of that refusal into allowedModels must not thereby allow
+  // whatever the upstream would have picked.
+  const response = await handleImages(
+    imagesRequest({ prompt: "a cat" }),
+    config({ allowedModels: [UNNAMED_DESTINATION_MODEL] }),
+    "generations",
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("the xAI image bridge is a destination the scope covers", async () => {
+  const response = await handleImages(
+    imagesRequest({ model: "gpt-image-1", prompt: "a cat" }),
+    config({ allowedProviders: ["openai-apikey"] }, {
+      images: { bridgeEnabled: true },
+      providers: {
+        xai: { adapter: "openai-chat", baseUrl: "https://api.x.ai/v1", apiKey: "fixture-xai-key", authMode: "key" },
+      },
+    } as Partial<OcxConfig>),
+    "generations",
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  expect((await denial(response)).type).toBe(MODEL_NOT_ALLOWED_FOR_KEY);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("Antigravity image generation is refused on its own resolved model", async () => {
+  const response = await handleImages(
+    imagesRequest({ model: "gpt-image-1", prompt: "a cat" }),
+    config({ allowedModels: ["gpt-image-1"] }, {
+      providers: {
+        "google-antigravity": {
+          adapter: "google-antigravity",
+          baseUrl: "https://daily-cloudcode-pa.googleapis.com",
+          authMode: "oauth",
+        },
+      },
+    } as Partial<OcxConfig>),
+    "generations",
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  // The caller asked for an allowed selector; the branch resolves a different
+  // model on a different provider, which is the substitution the scope exists to catch.
+  expect(response.status).toBe(403);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("a key with no scope keeps reaching every image destination", async () => {
+  const response = await handleImages(
+    imagesRequest({ model: "gpt-image-1", prompt: "a cat" }),
+    config({ allowedProviders: ["some-other-provider"] }),
+    "generations",
+    logContext(),
+    undefined,
+    UNSCOPED,
+  );
+  expect(response.status).toBe(200);
+  expect(upstreamCalls).toHaveLength(1);
+});
diff --git a/tests/server/api-key-scope-live.test.ts b/tests/server/api-key-scope-live.test.ts
new file mode 100644
index 00000000000..15919079867
--- /dev/null
+++ b/tests/server/api-key-scope-live.test.ts
@@ -0,0 +1,235 @@
+/**
+ * Per-key model and provider scope on the native voice relay (#5049).
+ *
+ * `/v1/live` and `/v1/realtime/calls` resolve an OpenAI upstream directly and
+ * relay the call-create body verbatim, so the model the caller states in its
+ * session — or in a standalone socket query — is the destination that gets
+ * billed. Nothing here passes through the router, so the scope has to be
+ * applied where that upstream is chosen.
+ */
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MODEL_NOT_ALLOWED_FOR_KEY, UNNAMED_DESTINATION_MODEL } from "../../src/server/admission-model-scope";
+import type { DataPlaneAdmission } from "../../src/server/auth-cors";
+import { LIVE_AUDIO_MODEL } from "../../src/server/audio-upstream";
+import { handleLive, resolveLiveSidebandUpgrade } from "../../src/server/live";
+import type { RequestLogContext } from "../../src/server/request-log";
+import type { OcxConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+const SCOPED_KEY = "ocx_data_" + "l".repeat(40);
+const OPEN_KEY = "ocx_data_" + "m".repeat(40);
+const SCOPED: DataPlaneAdmission = { kind: "configured", keyId: "scoped", source: "dedicated" };
+const UNSCOPED: DataPlaneAdmission = { kind: "configured", keyId: "open", source: "dedicated" };
+const OTHER_LIVE_MODEL = "gpt-realtime-preview";
+
+const originalFetch = globalThis.fetch;
+const previousHome = process.env.OPENCODEX_HOME;
+let home = "";
+let upstreamCalls: string[] = [];
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "ocx-live-scope-"));
+  process.env.OPENCODEX_HOME = home;
+  upstreamCalls = [];
+  globalThis.fetch = (async (input: unknown) => {
+    upstreamCalls.push(String(input));
+    return new Response("v=0", { status: 200, headers: { "content-type": "application/sdp" } });
+  }) as unknown as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  if (home) removeTreeWithRetry(home);
+  home = "";
+});
+
+type Scope = { allowedProviders?: string[]; allowedModels?: string[] };
+
+function config(scope: Scope): OcxConfig {
+  return {
+    port: 0,
+    hostname: "127.0.0.1",
+    defaultProvider: "openai-apikey",
+    providers: {
+      "openai-apikey": {
+        adapter: "openai-responses",
+        baseUrl: "https://api.openai.com/v1",
+        apiKey: "fixture-upstream-key",
+        authMode: "key",
+      },
+    },
+    apiKeys: [
+      { id: "scoped", name: "mail", key: SCOPED_KEY, createdAt: "2026-01-01T00:00:00.000Z", ...scope },
+      { id: "open", name: "coding", key: OPEN_KEY, createdAt: "2026-01-01T00:00:00.000Z" },
+    ],
+  } as OcxConfig;
+}
+
+function logContext(): RequestLogContext {
+  return { model: "gpt-live", provider: "unknown" } as RequestLogContext;
+}
+
+/** A call-create the proxy admits by dedicated key, leaving Authorization for the upstream. */
+function jsonCallCreate(session?: Record<string, unknown>, key = SCOPED_KEY): Request {
+  return new Request("http://localhost/v1/live", {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-opencodex-api-key": key },
+    body: JSON.stringify({ sdp: "v=0", ...(session ? { session } : {}) }),
+  });
+}
+
+function multipartCallCreate(session: Record<string, unknown>): Request {
+  const form = new FormData();
+  form.set("sdp", "v=0");
+  form.set("session", JSON.stringify(session));
+  return new Request("http://localhost/v1/realtime/calls", {
+    method: "POST",
+    headers: { "x-opencodex-api-key": SCOPED_KEY },
+    body: form,
+  });
+}
+
+async function denial(response: Response): Promise<{ type: string; model: string }> {
+  const payload = await response.json() as { error: { type: string; model: string } };
+  return payload.error;
+}
+
+test("call-create is judged on the live model its session names", async () => {
+  const response = await handleLive(
+    jsonCallCreate({ model: OTHER_LIVE_MODEL }),
+    config({ allowedModels: [LIVE_AUDIO_MODEL] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  const error = await denial(response);
+  expect(error.type).toBe(MODEL_NOT_ALLOWED_FOR_KEY);
+  expect(error.model).toBe(OTHER_LIVE_MODEL);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("a multipart call-create states its model in the session field", async () => {
+  const response = await handleLive(
+    multipartCallCreate({ model: OTHER_LIVE_MODEL }),
+    config({ allowedModels: [LIVE_AUDIO_MODEL] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  expect((await denial(response)).model).toBe(OTHER_LIVE_MODEL);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("a call-create that names no model has no destination a model list can allow", async () => {
+  const response = await handleLive(
+    jsonCallCreate(),
+    config({ allowedModels: ["something-else"] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  expect((await denial(response)).model).toBe(UNNAMED_DESTINATION_MODEL);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("a provider-only scope still creates a call that names no model", async () => {
+  const response = await handleLive(
+    jsonCallCreate(),
+    config({ allowedProviders: ["openai-apikey"] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(200);
+  expect(upstreamCalls).toHaveLength(1);
+});
+
+test("a provider outside the scope cannot serve a voice call", async () => {
+  const response = await handleLive(
+    jsonCallCreate({ model: LIVE_AUDIO_MODEL }),
+    config({ allowedProviders: ["some-other-provider"] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(403);
+  expect(upstreamCalls).toEqual([]);
+});
+
+test("an allowed destination still reaches the upstream", async () => {
+  const response = await handleLive(
+    jsonCallCreate({ model: LIVE_AUDIO_MODEL }),
+    config({ allowedProviders: ["openai-apikey"], allowedModels: [LIVE_AUDIO_MODEL] }),
+    logContext(),
+    undefined,
+    SCOPED,
+  );
+  expect(response.status).toBe(200);
+  expect(upstreamCalls).toHaveLength(1);
+});
+
+test("a standalone realtime socket is judged on the model in its query", async () => {
+  const resolved = await resolveLiveSidebandUpgrade(
+    new Request("http://localhost/v1/realtime?model=" + OTHER_LIVE_MODEL, {
+      headers: { "x-opencodex-api-key": SCOPED_KEY },
+    }),
+    config({ allowedModels: [LIVE_AUDIO_MODEL] }),
+    logContext(),
+    { style: "realtime-standalone", query: "model=" + OTHER_LIVE_MODEL },
+    undefined,
+    SCOPED,
+  );
+  expect(resolved).toBeInstanceOf(Response);
+  expect((resolved as Response).status).toBe(403);
+  expect((await denial(resolved as Response)).model).toBe(OTHER_LIVE_MODEL);
+});
+
+test("a native join names no model, so a model list cannot admit it", async () => {
+  // This compatibility path records nothing about the calls it relays, so the
+  // model a join attaches to is unknowable here. Admitting it against an
+  // assumed default would let a key scoped to that default ride a call created
+  // for another model.
+  const resolved = await resolveLiveSidebandUpgrade(
+    new Request("http://localhost/v1/live/call-abc", { headers: { "x-opencodex-api-key": SCOPED_KEY } }),
+    config({ allowedModels: [LIVE_AUDIO_MODEL] }),
+    logContext(),
+    { style: "frameless-path", callId: "call-abc" },
+    undefined,
+    SCOPED,
+  );
+  expect(resolved).toBeInstanceOf(Response);
+  expect((resolved as Response).status).toBe(403);
+});
+
+test("a provider-only scope still joins an existing call", async () => {
+  const resolved = await resolveLiveSidebandUpgrade(
+    new Request("http://localhost/v1/live/call-abc", { headers: { "x-opencodex-api-key": SCOPED_KEY } }),
+    config({ allowedProviders: ["openai-apikey"] }),
+    logContext(),
+    { style: "frameless-path", callId: "call-abc" },
+    undefined,
+    SCOPED,
+  );
+  expect(resolved).not.toBeInstanceOf(Response);
+  expect((resolved as { upstreamWsUrl: string }).upstreamWsUrl).toContain("call-abc");
+});
+
+test("a key with no scope keeps the voice relay unrestricted", async () => {
+  const response = await handleLive(
+    jsonCallCreate({ model: OTHER_LIVE_MODEL }, OPEN_KEY),
+    config({ allowedModels: [LIVE_AUDIO_MODEL] }),
+    logContext(),
+    undefined,
+    UNSCOPED,
+  );
+  expect(response.status).toBe(200);
+  expect(upstreamCalls).toHaveLength(1);
+});
diff --git a/tests/server/claude-intercept-integration.test.ts b/tests/server/claude-intercept-integration.test.ts
new file mode 100644
index 00000000000..6dc046fe1eb
--- /dev/null
+++ b/tests/server/claude-intercept-integration.test.ts
@@ -0,0 +1,157 @@
+/**
+ * The Claude intercept pair wired into a real `startServer`: a client configured with nothing
+ * but `HTTPS_PROXY` and the local CA reaches the router's Messages handler under the loopback
+ * policy, while every other path on the intercepted host is relayed to the configured upstream
+ * and never touches the router's own routes.
+ */
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { saveConfig } from "../../src/config";
+import { startServer } from "../../src/server";
+import { findAvailablePort } from "../../src/server/ports";
+import { claudeInterceptCaCertPath } from "../../src/claude/intercept/local-ca";
+import { getClaudeInterceptState } from "../../src/claude/intercept/runtime";
+import type { OcxConfig } from "../../src/types";
+import { SERVER_BUDGET_MS } from "../helpers/test-budget";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+const previousApiToken = process.env.OPENCODEX_API_AUTH_TOKEN;
+const previousHome = process.env.OPENCODEX_HOME;
+let testDir = "";
+
+beforeEach(() => {
+  testDir = mkdtempSync(join(tmpdir(), "ocx-claude-intercept-"));
+  process.env.OPENCODEX_HOME = testDir;
+  process.env.OPENCODEX_API_AUTH_TOKEN = "public-secret";
+});
+
+afterEach(() => {
+  if (previousApiToken === undefined) delete process.env.OPENCODEX_API_AUTH_TOKEN;
+  else process.env.OPENCODEX_API_AUTH_TOKEN = previousApiToken;
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  if (testDir && existsSync(testDir)) removeTreeWithRetry(testDir);
+  testDir = "";
+});
+
+async function waitForIntercept(): Promise<NonNullable<ReturnType<typeof getClaudeInterceptState>>> {
+  for (let i = 0; i < 100; i++) {
+    const state = getClaudeInterceptState();
+    if (state) return state;
+    await Bun.sleep(20);
+  }
+  throw new Error("intercept pair did not start");
+}
+
+test("Messages through CONNECT reach the router; other paths relay to the configured upstream", async () => {
+  const upstreamHits: string[] = [];
+  const fakeUpstream = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    fetch(req) {
+      upstreamHits.push(`${req.method} ${new URL(req.url).pathname}`);
+      return Response.json({ upstream: true });
+    },
+  });
+  const interceptPort = await findAvailablePort(0, "127.0.0.1");
+  const publicPort = await findAvailablePort(0, "127.0.0.1", { reservedPort: interceptPort });
+  saveConfig({
+    port: publicPort,
+    hostname: "127.0.0.1",
+    defaultProvider: "chatgpt",
+    providers: {
+      chatgpt: { adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex", authMode: "forward" },
+    },
+    claudeCode: {
+      anthropicBaseUrl: `http://127.0.0.1:${fakeUpstream.port}`,
+      intercept: { port: interceptPort },
+    },
+  } as unknown as OcxConfig);
+  const server = startServer(publicPort);
+  try {
+    const state = await waitForIntercept();
+    expect(state.proxyPort).toBe(interceptPort);
+    expect(state.caCertPath).toBe(claudeInterceptCaCertPath(testDir));
+    const ca = readFileSync(state.caCertPath, "utf8");
+    const proxy = `http://127.0.0.1:${state.proxyPort}`;
+
+    // No opencodex admission token is sent: the intercept ingress takes the loopback policy, so
+    // the request is judged by the Messages handler (which fails on routing, since the test
+    // config has no usable provider credential) rather than refused at admission.
+    const messages = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      proxy,
+      tls: { ca },
+      headers: { "content-type": "application/json", "anthropic-version": "2023-06-01", "x-api-key": "sk-ant-not-real" },
+      body: JSON.stringify({ model: "no-such-model-for-intercept-test", max_tokens: 8, messages: [{ role: "user", content: "hi" }] }),
+    });
+    const messagesBody = await messages.json() as { type: string; error: { message: string } };
+    expect(messages.headers.get("content-type")).toContain("application/json");
+    expect(messagesBody.type).toBe("error");
+    expect(messagesBody.error.message).not.toContain("opencodex API key required");
+    expect(messagesBody.error.message).not.toContain("Unknown endpoint");
+    expect(upstreamHits).toEqual([]);
+
+    // Anything else on the intercepted host is the client's own business with Anthropic.
+    const models = await fetch("https://api.anthropic.com/v1/models", { proxy, tls: { ca } });
+    expect(await models.json()).toEqual({ upstream: true });
+    const health = await fetch("https://api.anthropic.com/healthz", { proxy, tls: { ca } });
+    expect(await health.json()).toEqual({ upstream: true });
+    expect(upstreamHits).toEqual(["GET /v1/models", "GET /healthz"]);
+  } finally {
+    await server.stop(true);
+    fakeUpstream.stop(true);
+  }
+  expect(getClaudeInterceptState()).toBeNull();
+}, SERVER_BUDGET_MS);
+
+test("an ephemeral public port starts no proxy unless intercept.port is explicit", async () => {
+  const base = {
+    hostname: "127.0.0.1",
+    defaultProvider: "chatgpt",
+    providers: {
+      chatgpt: { adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex", authMode: "forward" },
+    },
+  };
+  saveConfig({ ...base, port: 10100 } as unknown as OcxConfig);
+  const implicit = startServer(0);
+  try {
+    await Bun.sleep(100);
+    expect(getClaudeInterceptState()).toBeNull();
+  } finally {
+    await implicit.stop(true);
+  }
+
+  const proxyPort = await findAvailablePort(0, "127.0.0.1");
+  saveConfig({ ...base, port: 10100, claudeCode: { intercept: { port: proxyPort } } } as unknown as OcxConfig);
+  const explicit = startServer(0);
+  try {
+    const state = await waitForIntercept();
+    expect(state.proxyPort).toBe(proxyPort);
+  } finally {
+    await explicit.stop(true);
+  }
+}, SERVER_BUDGET_MS);
+
+test("intercept.enabled=false starts no proxy", async () => {
+  const publicPort = await findAvailablePort(0, "127.0.0.1");
+  saveConfig({
+    port: publicPort,
+    hostname: "127.0.0.1",
+    defaultProvider: "chatgpt",
+    providers: {
+      chatgpt: { adapter: "openai-responses", baseUrl: "https://chatgpt.com/backend-api/codex", authMode: "forward" },
+    },
+    claudeCode: { intercept: { enabled: false } },
+  } as unknown as OcxConfig);
+  const server = startServer(publicPort);
+  try {
+    await Bun.sleep(100);
+    expect(getClaudeInterceptState()).toBeNull();
+    expect(existsSync(join(testDir, "claude-intercept"))).toBe(false);
+  } finally {
+    await server.stop(true);
+  }
+}, SERVER_BUDGET_MS);
diff --git a/tests/server/companion-settings.test.ts b/tests/server/companion-settings.test.ts
new file mode 100644
index 00000000000..37c5ae649a7
--- /dev/null
+++ b/tests/server/companion-settings.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, mock, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  applyCompanionSettingsPatch,
+  DEFAULT_COMPANION_SETTINGS,
+  loadCompanionSettings,
+  saveCompanionSettings,
+} from "../../src/companion/settings";
+import type { OcxConfig } from "../../src/types";
+
+const opened: string[] = [];
+mock.module("../../src/lib/open-url", () => ({
+  openUrl: (url: string) => {
+    opened.push(url);
+  },
+}));
+const { resetCompanionPresenceForTests } = await import("../../src/server/management/companion-routes");
+const { handleManagementAPI } = await import("../../src/server/management-api");
+
+const config = { port: 10100, defaultProvider: "openai", providers: {} } as OcxConfig;
+async function withHome<T>(run: (home: string) => Promise<T> | T): Promise<T> {
+  const home = mkdtempSync(join(tmpdir(), "ocx-companion-"));
+  const old = process.env.OPENCODEX_HOME;
+  process.env.OPENCODEX_HOME = home;
+  try { return await run(home); } finally {
+    if (old === undefined) delete process.env.OPENCODEX_HOME; else process.env.OPENCODEX_HOME = old;
+    rmSync(home, { recursive: true, force: true });
+  }
+}
+async function callPath(path: string, method: string, body?: unknown, userAgent?: string): Promise<{ status: number; body: any }> {
+  const url = new URL(`http://127.0.0.1:10100${path}`);
+  const req = new Request(url, {
+    method,
+    headers: {
+      host: "127.0.0.1:10100",
+      ...(userAgent ? { "user-agent": userAgent } : {}),
+      ...(body === undefined ? {} : { "content-type": "application/json" }),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const response = await handleManagementAPI(req, url, config, {}, "admin-token");
+  return { status: response?.status ?? 404, body: response ? await response.json() : null };
+}
+async function call(method: string, body?: unknown, userAgent?: string): Promise<{ status: number; body: any }> {
+  return callPath("/api/companion/settings", method, body, userAgent);
+}
+
+describe("companion settings", () => {
+  test("defaults, corrupt files, validation, and roundtrip persistence", async () => {
+    await withHome(home => {
+      expect(loadCompanionSettings().settings).toEqual(DEFAULT_COMPANION_SETTINGS);
+      writeFileSync(join(home, "companion.json"), "{");
+      expect(loadCompanionSettings().settings).toEqual(DEFAULT_COMPANION_SETTINGS);
+      expect(loadCompanionSettings().corrupt).toBe(true);
+      expect(applyCompanionSettingsPatch(DEFAULT_COMPANION_SETTINGS, { unknown: true })).toEqual({ error: expect.any(String) });
+      expect(applyCompanionSettingsPatch(DEFAULT_COMPANION_SETTINGS, { menuBarTemplate: "x".repeat(201) })).toEqual({ error: expect.any(String) });
+      const updated = applyCompanionSettingsPatch(DEFAULT_COMPANION_SETTINGS, { showChart: false });
+      if ("error" in updated) throw new Error(updated.error);
+      saveCompanionSettings(updated);
+      expect(loadCompanionSettings().settings.showChart).toBe(false);
+    });
+  });
+
+  test("GET, PUT, and reset are routed", async () => {
+    await withHome(async () => {
+      expect((await call("GET")).status).toBe(200);
+      expect((await call("PUT", { settings: { showToday: false } })).body.settings.showToday).toBe(false);
+      expect((await call("PUT", { reset: true })).body.settings).toEqual(DEFAULT_COMPANION_SETTINGS);
+      expect((await call("PUT", { settings: { bad: true } })).status).toBe(400);
+    });
+  });
+
+  test("GET reports corrupt persisted settings without overwriting them", async () => {
+    await withHome(async home => {
+      writeFileSync(join(home, "companion.json"), "{");
+      const result = await call("GET");
+      expect(result.status).toBe(200);
+      expect(result.body.corrupt).toBe(true);
+      expect(readFileSync(join(home, "companion.json"), "utf8")).toBe("{");
+    });
+  });
+
+  test("GET records menu bar presence only for the companion user agent", async () => {
+    await withHome(async () => {
+      resetCompanionPresenceForTests();
+      const initial = await call("GET");
+      expect(initial.body.companion.lastSeenAt).toBeNull();
+      const ordinary = await call("GET", undefined, "Mozilla/5.0");
+      expect(ordinary.body.companion.lastSeenAt).toBeNull();
+      const companion = await call("GET", undefined, "OpenCodexMenuBar/2.60.0");
+      expect(companion.body.companion.lastSeenAt).toBeNumber();
+      expect(companion.body.companion.kind).toBe("menuBar");
+      resetCompanionPresenceForTests();
+      const desktop = await call("GET", undefined, "OpenCodexDesktop/2.61.0");
+      expect(desktop.body.companion.lastSeenAt).toBeNumber();
+      expect(desktop.body.companion.kind).toBe("desktop");
+    });
+  });
+
+  test("opens only validated local dashboard paths in the browser", async () => {
+    await withHome(async () => {
+      opened.length = 0;
+      for (const path of ["https://x", "//x", 42]) {
+        const result = await callPath("/api/companion/open-in-browser", "POST", { path });
+        expect(result.status).toBe(400);
+        expect(result.body).toEqual({ error: "invalid path" });
+        expect(opened).toEqual([]);
+      }
+      const result = await callPath("/api/companion/open-in-browser", "POST", { path: "/#/usage" });
+      expect(result.status).toBe(200);
+      expect(result.body).toEqual({ ok: true, url: "http://127.0.0.1:10100/#/usage" });
+      expect(opened).toEqual(["http://127.0.0.1:10100/#/usage"]);
+    });
+  });
+});
diff --git a/tests/server/loopback-listener-integration.test.ts b/tests/server/loopback-listener-integration.test.ts
index 29a10a44135..150c1da8cbe 100644
--- a/tests/server/loopback-listener-integration.test.ts
+++ b/tests/server/loopback-listener-integration.test.ts
@@ -813,11 +813,11 @@ describe("composite listener shutdown", () => {
         async () => { ran.push("primary"); throw failure; },
         async () => { ran.push("loopback"); },
       ],
-      async () => { ran.push("lifecycle"); },
+      async listenersStopped => { ran.push(`lifecycle:${listenersStopped}`); },
     )).rejects.toBe(failure);
     // The whole point: a rejected primary stop must not strand the loopback socket or skip
     // the native lifecycle release.
-    expect(ran).toEqual(["primary", "loopback", "lifecycle"]);
+    expect(ran).toEqual(["primary", "loopback", "lifecycle:false"]);
   });
 
   test("two failures are reported together rather than one hiding the other", async () => {
@@ -848,8 +848,10 @@ describe("composite listener shutdown", () => {
   });
 
   test("an all-clear shutdown resolves", async () => {
-    await expect(runListenerShutdown([async () => {}, async () => {}], async () => {}))
+    let listenersStopped: boolean | undefined;
+    await expect(runListenerShutdown([async () => {}, async () => {}], async stopped => { listenersStopped = stopped; }))
       .resolves.toBeUndefined();
+    expect(listenersStopped).toBe(true);
   });
 });
 
diff --git a/tests/server/management-metrics-export.test.ts b/tests/server/management-metrics-export.test.ts
index cccc37dc546..560874e661b 100644
--- a/tests/server/management-metrics-export.test.ts
+++ b/tests/server/management-metrics-export.test.ts
@@ -16,7 +16,15 @@ import {
   type RequestLogContext,
   type RequestLogEntry,
 } from "../../src/server/request-log";
-import { createRequestMetricsOwner } from "../../src/server/request-metrics";
+import {
+  createRequestMetricsOwner,
+  REQUEST_DURATION_BUCKETS_SECONDS,
+  REQUEST_METRICS_PROTOCOLS,
+  REQUEST_METRICS_RECOVERY_CLASSES,
+  REQUEST_METRICS_FAILURE_CAUSES,
+  REQUEST_METRICS_RESULTS,
+  REQUEST_TTFT_BUCKETS_SECONDS,
+} from "../../src/server/request-metrics";
 import { startServer } from "../../src/server";
 import type { OcxConfig } from "../../src/types";
 import type { AttemptRecoveryKind } from "../../src/usage/log";
@@ -339,6 +347,31 @@ describe("request metrics aggregation", () => {
     expect(sampleValue(output, 'opencodex_recoveries_total{protocol="responses",recovery="rate_limit"}')).toBe(2);
   });
 
+  test("the four refusals an operator responds to differently get four different classes", () => {
+    const metrics = createRequestMetricsOwner(123);
+    addFinalRequestLog("refusal-classes", Date.now() - 1_000, {
+      model: "m", provider: "p", inboundProtocol: "responses", requestMetricsRecorder: metrics,
+      attempts: [
+        attempt(1, ["opaque-blob-rejection"]),
+        { ...attempt(1, ["rate-limit-429"]), ordinal: 2 },
+        { ...attempt(1, ["reasoning-effort-downgrade"]), ordinal: 3 },
+        { ...attempt(1, ["image-413"]), ordinal: 4 },
+      ],
+    } as RequestLogContext, 400, undefined, () => {});
+
+    const output = metrics.snapshot();
+    // A rejected opaque blob is a ciphertext refusal, not a payload problem: the payload was fine
+    // and the stale encrypted state was not. Counting it as payload alongside an oversize image
+    // told an operator to look at the wrong thing.
+    expect(sampleValue(output, 'opencodex_recoveries_total{protocol="responses",recovery="ciphertext"}')).toBe(1);
+    expect(sampleValue(output, 'opencodex_recoveries_total{protocol="responses",recovery="payload"}')).toBe(1);
+    expect(sampleValue(output, 'opencodex_recoveries_total{protocol="responses",recovery="rate_limit"}')).toBe(1);
+    expect(sampleValue(output, 'opencodex_recoveries_total{protocol="responses",recovery="effort_downgrade"}')).toBe(1);
+    expect(sampleValue(output, 'opencodex_recoveries_total{protocol="responses",recovery="quota"}')).toBe(0);
+    expect(sampleValue(output, 'opencodex_recoveries_total{protocol="responses",recovery="policy"}')).toBe(0);
+    expect(sampleValue(output, 'opencodex_recoveries_total{protocol="responses",recovery="other"}')).toBe(0);
+  });
+
   test("a failed terminal carried over HTTP 200 is never counted as completed", () => {
     const metrics = createRequestMetricsOwner(123);
     metrics.recordFinalRequest({
@@ -405,6 +438,7 @@ describe("request metrics aggregation", () => {
       toolBody: canaries[8],
     } as unknown as RequestLogContext;
     addFinalRequestLog(canaries[0]!, Date.now() - 1, logCtx, 400, undefined, () => {});
+    const beforeFanOut = metrics.snapshot().split("\n").filter(line => line && !line.startsWith("#")).length;
     for (let index = 0; index < 64; index += 1) {
       addFinalRequestLog(`request-${index}`, Date.now() - 1, {
         model: `model-${index}`,
@@ -417,7 +451,24 @@ describe("request metrics aggregation", () => {
     const output = metrics.snapshot();
     for (const canary of canaries) expect(output).not.toContain(canary);
     const samples = output.split("\n").filter(line => line && !line.startsWith("#"));
-    expect(samples).toHaveLength(453);
+    // The property, stated directly: 64 requests carrying 64 distinct models, providers, keys and
+    // account labels add no series at all. A dynamic label map would show up here as growth.
+    expect(samples).toHaveLength(beforeFanOut);
+    // And the absolute size, derived from the closed vocabularies rather than restated as a
+    // literal. The literal was correct and went stale the moment a bounded label value was added,
+    // which is the failure mode this repository keeps hitting in merges.
+    const perHistogram = (bounds: readonly number[]): number => bounds.length + 1 + 2;
+    const cells = REQUEST_METRICS_PROTOCOLS.length * REQUEST_METRICS_RESULTS.length;
+    expect(samples).toHaveLength(
+      cells
+      + REQUEST_METRICS_PROTOCOLS.length
+      + REQUEST_METRICS_PROTOCOLS.length * REQUEST_METRICS_RECOVERY_CLASSES.length
+      + REQUEST_METRICS_PROTOCOLS.length * REQUEST_METRICS_FAILURE_CAUSES.length
+      + cells * perHistogram(REQUEST_DURATION_BUCKETS_SECONDS)
+      + cells * perHistogram(REQUEST_TTFT_BUCKETS_SECONDS)
+      + cells
+      + 1,
+    );
   });
 
   test("text exposition has deterministic HELP/TYPE groups and cumulative +Inf buckets", () => {
@@ -431,10 +482,15 @@ describe("request metrics aggregation", () => {
       .toBeLessThan(output.indexOf("opencodex_request_duration_seconds_bucket"));
     const helpLines = output.split("\n").filter(line => line.startsWith("# HELP "));
     const typeLines = output.split("\n").filter(line => line.startsWith("# TYPE "));
-    expect(helpLines).toHaveLength(7);
-    expect(typeLines).toHaveLength(7);
-    expect(new Set(helpLines.map(line => line.split(" ")[2])).size).toBe(7);
-    expect(new Set(typeLines.map(line => line.split(" ")[2])).size).toBe(7);
+    // Every metric name the exporter emits, read from the exposition rather than counted by
+    // hand: the literal was correct until a metric was added, which is the same staleness the
+    // sample arithmetic above avoids.
+    const metricNames = new Set(helpLines.map(line => line.split(" ")[2]));
+    expect(helpLines).toHaveLength(metricNames.size);
+    expect(typeLines).toHaveLength(metricNames.size);
+    expect(new Set(typeLines.map(line => line.split(" ")[2]))).toEqual(metricNames);
+    // Each name appears exactly once in each group, which is what deterministic grouping means.
+    expect(helpLines.length).toBeGreaterThan(REQUEST_METRICS_PROTOCOLS.length);
     expect(sampleValue(output, 'opencodex_request_duration_seconds_bucket{protocol="responses",result="completed",le="+Inf"}'))
       .toBe(sampleValue(output, 'opencodex_request_duration_seconds_count{protocol="responses",result="completed"}'));
     expect(metrics.snapshot()).toBe(output);
diff --git a/tests/server/management-provider-reset-replay.test.ts b/tests/server/management-provider-reset-replay.test.ts
new file mode 100644
index 00000000000..27f7f2c2df5
--- /dev/null
+++ b/tests/server/management-provider-reset-replay.test.ts
@@ -0,0 +1,51 @@
+import { expect, test } from "bun:test";
+import { providerManagementConfigError } from "../../src/server/auth-cors";
+
+// Lives apart from management-provider-validation.test.ts because that file sits at its
+// file-size ratchet cap; the helpers it needs are small enough to repeat here.
+const canonicalDirect = {
+  adapter: "openai-responses",
+  baseUrl: "https://chatgpt.com/backend-api/codex",
+  authMode: "forward",
+  codexAccountMode: "direct",
+} as const;
+
+test("provider management validates retryOnReset bounds and unknown keys", () => {
+  const base = { adapter: "openai-responses", baseUrl: "https://api.openai.com/v1" };
+  expect(providerManagementConfigError("custom", { ...base, retryOnReset: {} })).toBeNull();
+  expect(providerManagementConfigError("custom", { ...base, retryOnReset: { enabled: true, replacements: 2 } })).toBeNull();
+  expect(providerManagementConfigError("custom", { ...base, retryOnReset: { replacements: 0 } }))
+    .toContain("retryOnReset.replacements is invalid");
+  expect(providerManagementConfigError("custom", { ...base, retryOnReset: { replacements: 3 } }))
+    .toContain("retryOnReset.replacements is invalid");
+  // The old field name from the pre-rework branch is rejected rather than silently ignored:
+  // `attempts` was a per-leg send count and this is a per-request replacement count.
+  expect(providerManagementConfigError("custom", { ...base, retryOnReset: { attempts: 2 } }))
+    .toContain("retryOnReset has unrecognized field");
+  expect(providerManagementConfigError("custom", { ...base, retryOnReset: true }))
+    .toContain("retryOnReset is invalid");
+  // The canonical openai row is the main target of this policy, and a full-object write
+  // compares it against the seed with an exact key match: the field must be admitted
+  // there like requestPacing is, while its value is still validated.
+  expect(providerManagementConfigError("openai", { ...canonicalDirect, retryOnReset: { replacements: 2 } })).toBeNull();
+  expect(providerManagementConfigError("openai", { ...canonicalDirect, retryOnReset: { replacements: 3 } }))
+    .toContain("retryOnReset.replacements is invalid");
+  // A secret-shaped unknown field name and a secret-shaped provider name are both redacted.
+  const secretError = providerManagementConfigError("custom", { ...base, retryOnReset: { "sk-super-secret-9876": true } })!;
+  expect(secretError).toContain("retryOnReset has unrecognized field");
+  expect(secretError).not.toContain("sk-super-secret-9876");
+  const secretNameError = providerManagementConfigError("sk-super-secret-9876", { ...base, retryOnReset: { replacements: 0 } })!;
+  expect(secretNameError).toContain("retryOnReset.replacements is invalid");
+  expect(secretNameError).not.toContain("sk-super-secret-9876");
+  expect(secretNameError).toContain("[REDACTED]");
+});
+
+test("retryOn429 keeps its own field name after the formatter was shared", () => {
+  // The two validators now run through one body. A shared formatter that reported the wrong
+  // field name would send an operator to the wrong key in their config.
+  const base = { adapter: "openai-responses", baseUrl: "https://api.openai.com/v1" };
+  expect(providerManagementConfigError("custom", { ...base, retryOn429: { attempts: 0 } }))
+    .toContain("retryOn429.attempts is invalid");
+  expect(providerManagementConfigError("custom", { ...base, retryOn429: { nope: 1 } }))
+    .toContain("retryOn429 has unrecognized field");
+});
diff --git a/tests/server/memory-watchdog.test.ts b/tests/server/memory-watchdog.test.ts
index 918503456ce..dc1e0f45c97 100644
--- a/tests/server/memory-watchdog.test.ts
+++ b/tests/server/memory-watchdog.test.ts
@@ -300,36 +300,31 @@ describe("GET /api/system/memory", () => {
       return await res!.json() as { bunRuntimeSource?: unknown; bunRevision?: unknown };
     };
     try {
-      for (const source of ["override", "bundled", "process"]) {
-        process.env.OCX_BUN_RUNTIME_SOURCE = source;
-        // Source alone is not enough: the marker must name THIS executable.
-        expect((await read()).bunRuntimeSource).toBeUndefined();
-        process.env.OCX_BUN_RUNTIME_PATH = process.execPath;
-        expect((await read()).bunRuntimeSource).toBe(source);
-        delete process.env.OCX_BUN_RUNTIME_PATH;
-      }
-      // A mismatched recorded path describes another binary — stay absent.
-      process.env.OCX_BUN_RUNTIME_SOURCE = "override";
-      process.env.OCX_BUN_RUNTIME_PATH = "/usr/local/bin/definitely-not-this-bun";
-      expect((await read()).bunRuntimeSource).toBeUndefined();
-      delete process.env.OCX_BUN_RUNTIME_PATH;
-      delete process.env.OCX_BUN_RUNTIME_SOURCE;
-      // An unset or unrecognized marker must leave the field absent rather than
-      // shipping a value doctor would then have to distrust.
-      const unset = await read();
-      expect(unset.bunRuntimeSource).toBeUndefined();
-      expect(typeof unset.bunRevision).toBe("string");
+      // The env-marker matrix itself — every allowlisted source, the pair contract,
+      // a mismatched recorded path, and absent or unrecognized markers — is exercised
+      // directly against the serialization target in
+      // tests/ci-workflows/bun-runtime.test.ts ("reportedBunRuntimeSource (#848
+      // launch-time provenance)"), with assertions identical to the ones this test
+      // used to route through eight full memory snapshots (~600 ms each on the
+      // shared CI runners, over this test's own deadline twice in unrelated PRs).
+      // What only this test can still prove is the wiring: the route answers THIS
+      // field from THAT function. One read per wire shape is the whole cost of that.
+      process.env.OCX_BUN_RUNTIME_SOURCE = "bundled";
+      process.env.OCX_BUN_RUNTIME_PATH = process.execPath;
+      const reported = await read();
+      expect(reported.bunRuntimeSource).toBe("bundled");
+      expect(typeof reported.bunRevision).toBe("string");
 
-      process.env.OCX_BUN_RUNTIME_SOURCE = "system";
+      // Without the marker pair the field is absent, never a guessed value.
+      delete process.env.OCX_BUN_RUNTIME_SOURCE;
+      delete process.env.OCX_BUN_RUNTIME_PATH;
       expect((await read()).bunRuntimeSource).toBeUndefined();
     } finally {
       if (inherited === undefined) delete process.env.OCX_BUN_RUNTIME_SOURCE;
       else process.env.OCX_BUN_RUNTIME_SOURCE = inherited;
       delete process.env.OCX_BUN_RUNTIME_PATH;
     }
-    // The route costs ~600 ms per read on the shared CI runners, and this test makes
-    // eight of them — marginally over bun's 5 s default on a loaded box.
-  }, 20_000);
+  });
 
   test("GET system memory includes privacy-safe appOwnedBytes scalars", async () => {
     registerDefaultAppOwnedMemoryStores();
diff --git a/tests/server/provider-egress-management-validation.test.ts b/tests/server/provider-egress-management-validation.test.ts
new file mode 100644
index 00000000000..5c0db7fe2d6
--- /dev/null
+++ b/tests/server/provider-egress-management-validation.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { REDACTED_PROVIDER_FIELDS, providerManagementConfigError } from "../../src/server/auth-cors";
+import { PROVIDER_EGRESS_DIRECT } from "../../src/lib/provider-egress";
+
+/**
+ * The management write boundary for the per-provider egress fields.
+ *
+ * A sibling of `management-provider-validation.test.ts` rather than an addition to it: that
+ * file sits at its recorded line cap, and the cap only ever moves downward.
+ */
+function validate(provider: Record<string, unknown>): string | null {
+  return providerManagementConfigError("vendor", { adapter: "openai-responses", baseUrl: "https://provider.example/v1", ...provider });
+}
+
+describe("provider egress at the management write boundary", () => {
+  test("the accepted forms are admitted", () => {
+    for (const proxy of [PROVIDER_EGRESS_DIRECT, "http://egress.example:3128", "https://egress.example:3129", "socks5://127.0.0.1:1080", null]) {
+      expect(validate({ proxy })).toBeNull();
+    }
+    expect(validate({ noProxy: "internal.example" })).toBeNull();
+    expect(validate({ noProxy: ["internal.example", "10.0.0.1"] })).toBeNull();
+    expect(validate({})).toBeNull();
+  });
+
+  test("an unusable value is rejected at the write rather than at the first request", () => {
+    for (const proxy of ["", "   ", "not a url", "ftp://egress.example", "socks4://127.0.0.1:1080"]) {
+      expect(validate({ proxy })).not.toBeNull();
+    }
+    expect(validate({ noProxy: [42] })).not.toBeNull();
+  });
+
+  test("a rejection never echoes the value, because a proxy URL carries credentials", () => {
+    // A `.test` host: a credentialed proxy URL reads as `password@host` to the privacy scanner,
+    // and that domain is on its allowed list for fixtures.
+    const error = validate({ proxy: "ftp://operator:hunter2@egress.test:3128" });
+    expect(error).not.toBeNull();
+    for (const fragment of ["operator", "hunter2", "egress.test"]) {
+      expect(error).not.toContain(fragment);
+    }
+  });
+
+  test("the proxy field is classified as credential-bearing and never leaves in a DTO", () => {
+    // A proxy URL routinely embeds `user:password@`, so it is redacted like `apiKey` and the
+    // dashboard editor may not write it. Asserting the classification here is what keeps a
+    // later reclassification from quietly publishing the credential.
+    expect(REDACTED_PROVIDER_FIELDS).toContain("proxy");
+    expect(REDACTED_PROVIDER_FIELDS).not.toContain("noProxy");
+  });
+});
diff --git a/tests/server/proxy-liveness.test.ts b/tests/server/proxy-liveness.test.ts
index d675f04c8b8..ec47ab6de97 100644
--- a/tests/server/proxy-liveness.test.ts
+++ b/tests/server/proxy-liveness.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { createServer } from "node:net";
 import {
   createReadinessGate,
   runStartupReadinessSync,
@@ -7,7 +8,9 @@ import {
   DEFAULT_PROBE_TIMEOUT_MS,
   findLiveProxy,
   isOpencodexHealthz,
+  isConnectionRefused,
   loopbackProbeHosts,
+  probeEndpointLiveness,
   probeHostname,
   probePortOwner,
   probeReadiness,
@@ -90,6 +93,96 @@ describe("probeHostname", () => {
   });
 });
 
+describe("probeEndpointLiveness", () => {
+  test("classifies identity, foreign, non-200, refusal, timeout, and invalid ports", async () => {
+    const endpoint = { port: 10100, hostname: "127.0.0.1" };
+    const fakeFetch = (body: unknown, status = 200) => (async () => healthz(body, status)) as typeof fetch;
+    expect(await probeEndpointLiveness(endpoint, { fetchFn: fakeFetch(OURS) })).toBe("live");
+    expect(await probeEndpointLiveness(endpoint, { fetchFn: fakeFetch({ status: "ok" }) })).toBe("dead");
+    expect(await probeEndpointLiveness(endpoint, { fetchFn: fakeFetch(OURS, 503) })).toBe("unknown");
+    const refusedServer = createServer();
+    await new Promise<void>((resolve, reject) => {
+      refusedServer.once("error", reject);
+      refusedServer.listen(0, "127.0.0.1", () => resolve());
+    });
+    const refusedPort = (refusedServer.address() as { port: number }).port;
+    await new Promise<void>((resolve, reject) => {
+      refusedServer.close(error => error ? reject(error) : resolve());
+    });
+    expect(await probeEndpointLiveness({ port: refusedPort, hostname: "127.0.0.1" })).toBe("dead");
+    expect(await probeEndpointLiveness(endpoint, {
+      fetchFn: (async () => { throw new DOMException("aborted", "AbortError"); }) as typeof fetch,
+    })).toBe("unknown");
+    expect(await probeEndpointLiveness(endpoint, {
+      fetchFn: (async () => { throw new Error("connection reset"); }) as typeof fetch,
+    })).toBe("unknown");
+    expect(await probeEndpointLiveness({ port: 0 }, { fetchFn: fakeFetch(OURS) })).toBe("dead");
+  });
+
+  test("checks both loopback families sequentially", async () => {
+    const seen: string[] = [];
+    const fetchFn = (async (url: string) => {
+      seen.push(url);
+      if (url.startsWith("http://127.0.0.1:10100")) {
+        throw Object.assign(new Error("refused"), { code: "ECONNREFUSED" });
+      }
+      return healthz(OURS);
+    }) as typeof fetch;
+    expect(await probeEndpointLiveness({ port: 10100, hostname: "::" }, { fetchFn })).toBe("live");
+    expect(seen).toEqual([
+      "http://127.0.0.1:10100/healthz",
+      "http://[::1]:10100/healthz",
+    ]);
+
+    seen.length = 0;
+    const refused = (async (url: string) => {
+      seen.push(url);
+      throw Object.assign(new Error("refused"), { code: "ECONNREFUSED" });
+    }) as typeof fetch;
+    expect(await probeEndpointLiveness({ port: 10100, hostname: "::" }, { fetchFn: refused })).toBe("dead");
+    expect(seen).toEqual([
+      "http://127.0.0.1:10100/healthz",
+      "http://[::1]:10100/healthz",
+    ]);
+
+    seen.length = 0;
+    const mixed = (async (url: string) => {
+      seen.push(url);
+      if (url.startsWith("http://127.0.0.1:10100")) {
+        throw Object.assign(new Error("refused"), { code: "ECONNREFUSED" });
+      }
+      throw new DOMException("timed out", "TimeoutError");
+    }) as typeof fetch;
+    expect(await probeEndpointLiveness({ port: 10100, hostname: "::" }, { fetchFn: mixed })).toBe("unknown");
+    expect(seen).toEqual([
+      "http://127.0.0.1:10100/healthz",
+      "http://[::1]:10100/healthz",
+    ]);
+  });
+});
+
+describe("isConnectionRefused", () => {
+  test("recognizes aggregate socket refusals", () => {
+    const refused = Object.assign(new Error("refused"), { code: "ECONNREFUSED" });
+    expect(isConnectionRefused(new AggregateError([refused]))).toBe(true);
+    expect(isConnectionRefused(new AggregateError([
+      Object.assign(new Error("timeout"), { code: "ETIMEDOUT" }),
+    ]))).toBe(false);
+  });
+
+  test("a mixed aggregate is not proof of absence", () => {
+    // Happy-eyeballs style fan-out puts every address in one error. If one address refused and
+    // another never answered, the endpoint's state is unknown: the refusal speaks only for the
+    // address that produced it.
+    const refused = Object.assign(new Error("refused"), { code: "ECONNREFUSED" });
+    const timedOut = Object.assign(new Error("timeout"), { code: "ETIMEDOUT" });
+    expect(isConnectionRefused(new AggregateError([refused, timedOut]))).toBe(false);
+    expect(isConnectionRefused(new AggregateError([timedOut, refused]))).toBe(false);
+    expect(isConnectionRefused(new AggregateError([refused, refused]))).toBe(true);
+    expect(isConnectionRefused(new AggregateError([]))).toBe(false);
+  });
+});
+
 describe("proxyIdentityAt", () => {
   test("returns the reported pid for our proxy", async () => {
     const identity = await proxyIdentityAt(10100, {}, { fetchFn: (async () => healthz(OURS)) as typeof fetch });
diff --git a/tests/server/replay-refusal-parity.test.ts b/tests/server/replay-refusal-parity.test.ts
new file mode 100644
index 00000000000..0c6975ccb13
--- /dev/null
+++ b/tests/server/replay-refusal-parity.test.ts
@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { saveConfig } from "../../src/config";
+import { startServer } from "../../src/server";
+import {
+  REPLAY_REFUSAL_NO_RETRY_HEADER,
+  REPLAY_REFUSAL_NO_RETRY_VALUE,
+  REPLAY_REFUSED_STATUS,
+  UPSTREAM_RESET_REPLAY_REFUSED_CODE,
+} from "../../src/lib/upstream-retry";
+import { DEFAULT_RETRYABLE_429_RETRY_AFTER_SEC } from "../../src/lib/retry-after";
+import { installIsolatedCodexHome, type IsolatedCodexHome } from "../helpers/isolated-codex-home";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import type { OcxConfig } from "../../src/types";
+
+/**
+ * The acceptance unit for the ambiguous-resend refusal is not the shape of one response: it is
+ * how many times the turn physically reaches upstream when a real client is allowed to retry.
+ * A single `fetch` cannot see that, because a client with retries enabled is the thing that
+ * resends -- the proxy answered correctly and the duplicate inference happened anyway.
+ *
+ * So these cases run the proxy over a real socket, count the sends at the upstream boundary,
+ * and drive it with a client that retries the way the published SDKs do. The four surfaces
+ * are asserted against one expectation because a client cannot tell them apart: it sent one
+ * turn and the turn may already have executed, whichever endpoint carried it.
+ */
+const UPSTREAM_HOST = "replay-refusal-parity.example.test";
+const originalFetch = globalThis.fetch;
+let testDir = "";
+let previousHome: string | undefined;
+let isolatedCodexHome: IsolatedCodexHome | null = null;
+
+beforeEach(() => {
+  previousHome = process.env.OPENCODEX_HOME;
+  isolatedCodexHome = installIsolatedCodexHome("ocx-replay-refusal-");
+  testDir = mkdtempSync(join(tmpdir(), "ocx-replay-refusal-"));
+  process.env.OPENCODEX_HOME = testDir;
+  globalThis.fetch = originalFetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  isolatedCodexHome?.restore();
+  isolatedCodexHome = null;
+  if (testDir) removeTreeWithRetry(testDir);
+});
+
+/**
+ * The retry rule of the official clients, written as they write it.
+ *
+ * The header name and its two accepted values are deliberately literals here rather than the
+ * constants this repository exports. This function stands in for the third party: it has to
+ * keep believing what `openai` and `anthropic` believe -- an explicit verdict first, then the
+ * 408/409/429/5xx table -- even if our own constant were changed to something no client reads.
+ */
+function sdkWouldRetry(response: Response): boolean {
+  const verdict = response.headers.get("x-should-retry");
+  if (verdict === "true") return true;
+  if (verdict === "false") return false;
+  return response.status === 408 || response.status === 409
+    || response.status === 429 || response.status >= 500;
+}
+
+/** One logical request through a client whose retries are enabled. */
+async function sendWithClientRetries(
+  url: URL,
+  body: Record<string, unknown>,
+  maxRetries = 2,
+): Promise<{ response: Response; attempts: number; json: { error?: { code?: string } } }> {
+  let attempts = 0;
+  for (;;) {
+    attempts += 1;
+    const response = await originalFetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (attempts > maxRetries || !sdkWouldRetry(response)) {
+      return { response, attempts, json: await response.json() as { error?: { code?: string } } };
+    }
+    // Release the body before the next attempt, as the SDKs do.
+    await response.text();
+  }
+}
+
+/**
+ * Count physical upstream sends and answer each one as the fixture dictates. Everything not
+ * addressed to the fixture host -- the client's own calls included -- keeps the real fetch.
+ */
+function countingUpstream(answer: () => Response): () => number {
+  let sends = 0;
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input
+      : input instanceof URL ? input.href
+        : input.url;
+    if (!url.includes(UPSTREAM_HOST)) return originalFetch(input as RequestInfo, init);
+    sends += 1;
+    return answer();
+  }) as typeof fetch;
+  return () => sends;
+}
+
+/** A half-closed pooled socket: the request has left, and nothing comes back. */
+function preHeaderReset(): never {
+  throw Object.assign(
+    new Error("The socket connection was closed unexpectedly."),
+    { code: "ECONNRESET" },
+  );
+}
+
+function parityConfig(): OcxConfig {
+  const provider = (apiKey: string, adapter: string) => ({
+    adapter,
+    baseUrl: `https://${UPSTREAM_HOST}/v1`,
+    authMode: "key",
+    apiKey,
+    models: ["model"],
+  });
+  return {
+    port: 0,
+    defaultProvider: "native",
+    providers: {
+      // Native Chat keeps the caller on the Chat wire; the bridged row translates through
+      // Responses and back, which is the surface that used to lose the refusal.
+      native: provider("sk-native", "openai-chat"),
+      bridged: provider("sk-bridged", "openai-responses"),
+    },
+  } as unknown as OcxConfig;
+}
+
+const CHAT_TURN = { messages: [{ role: "user", content: "ping" }] };
+const CLAUDE_TURN = { max_tokens: 64, messages: [{ role: "user", content: "ping" }] };
+const RESPONSES_TURN = { input: [{ role: "user", content: [{ type: "input_text", text: "ping" }] }] };
+
+test("every HTTP surface answers an ambiguous reset with one send and no client resend", async () => {
+  saveConfig(parityConfig());
+  const sends = countingUpstream(preHeaderReset);
+  const server = startServer(0);
+  const surfaces = [
+    { name: "native Chat", path: "/v1/chat/completions", body: { model: "native/model", ...CHAT_TURN } },
+    { name: "translated Chat", path: "/v1/chat/completions", body: { model: "bridged/model", ...CHAT_TURN } },
+    { name: "Responses", path: "/v1/responses", body: { model: "bridged/model", ...RESPONSES_TURN } },
+    { name: "routed Claude Messages", path: "/v1/messages", body: { model: "bridged/model", ...CLAUDE_TURN } },
+  ];
+  try {
+    for (const surface of surfaces) {
+      const before = sends();
+      const { response, attempts, json } = await sendWithClientRetries(
+        new URL(surface.path, server.url),
+        surface.body,
+      );
+      // The number this refusal exists to hold at one, per logical request.
+      expect({ surface: surface.name, sends: sends() - before, attempts })
+        .toEqual({ surface: surface.name, sends: 1, attempts: 1 });
+      expect({ surface: surface.name, status: response.status, code: json.error?.code }).toEqual({
+        surface: surface.name,
+        status: REPLAY_REFUSED_STATUS,
+        code: UPSTREAM_RESET_REPLAY_REFUSED_CODE,
+      });
+      // No wait to honour, and no automatic resend of a turn that may already have run.
+      expect(response.headers.get("Retry-After")).toBeNull();
+      expect(response.headers.get(REPLAY_REFUSAL_NO_RETRY_HEADER)).toBe(REPLAY_REFUSAL_NO_RETRY_VALUE);
+    }
+  } finally {
+    await server.stop(true);
+  }
+});
+
+/**
+ * The control that keeps the assertion above honest. A client double that never resends would
+ * pin "one send" for any answer at all, so the same client has to be shown resending a real
+ * rate limit -- the answer a refusal was indistinguishable from on the translated surfaces.
+ */
+test("the same client still resends an ordinary upstream rate limit", async () => {
+  saveConfig(parityConfig());
+  const sends = countingUpstream(() => new Response(
+    JSON.stringify({ error: { message: "Too many requests", type: "rate_limit_error" } }),
+    { status: 429, headers: { "content-type": "application/json" } },
+  ));
+  const server = startServer(0);
+  try {
+    const { response, attempts } = await sendWithClientRetries(
+      new URL("/v1/messages", server.url),
+      { model: "bridged/model", ...CLAUDE_TURN },
+    );
+    expect(response.status).toBe(429);
+    expect(response.headers.get("Retry-After")).toBe(String(DEFAULT_RETRYABLE_429_RETRY_AFTER_SEC));
+    expect(response.headers.get(REPLAY_REFUSAL_NO_RETRY_HEADER)).toBeNull();
+    expect(attempts).toBe(3);
+    expect(sends()).toBeGreaterThan(1);
+  } finally {
+    await server.stop(true);
+  }
+});
diff --git a/tests/server/server-gui-bundle-freshness.test.ts b/tests/server/server-gui-bundle-freshness.test.ts
new file mode 100644
index 00000000000..16860c1e08b
--- /dev/null
+++ b/tests/server/server-gui-bundle-freshness.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  inspectGuiBundleFreshness,
+  newestModifiedMs,
+  staleGuiBundleLines,
+} from "../../src/server/gui-freshness";
+
+/** Write `name` under `root` with an explicit mtime, creating parents as needed. */
+function writeAt(root: string, name: string, secondsSinceEpoch: number): string {
+  const path = join(root, name);
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, "x");
+  utimesSync(path, secondsSinceEpoch, secondsSinceEpoch);
+  return path;
+}
+
+describe("gui bundle freshness", () => {
+  test("sources newer than the bundle are stale, and the advice names the rebuild", () => {
+    const root = mkdtempSync(join(tmpdir(), "ocx-gui-fresh-"));
+    writeAt(root, "dist/assets/index-AAAAAAAA.js", 1_000_000);
+    writeAt(root, "src/pages/Usage.tsx", 2_000_000);
+
+    const freshness = inspectGuiBundleFreshness({
+      bundlePath: join(root, "dist"),
+      sourcePath: join(root, "src"),
+    });
+
+    expect(freshness.stale).toBe(true);
+    const lines = staleGuiBundleLines(freshness);
+    expect(lines.length).toBeGreaterThan(0);
+    expect(lines.join("\n")).toContain("bun run build:gui");
+  });
+
+  test("a bundle rebuilt after its sources is not stale and says nothing", () => {
+    const root = mkdtempSync(join(tmpdir(), "ocx-gui-fresh-"));
+    writeAt(root, "src/pages/Usage.tsx", 1_000_000);
+    writeAt(root, "dist/assets/index-BBBBBBBB.js", 2_000_000);
+
+    const freshness = inspectGuiBundleFreshness({
+      bundlePath: join(root, "dist"),
+      sourcePath: join(root, "src"),
+    });
+
+    expect(freshness.stale).toBe(false);
+    expect(staleGuiBundleLines(freshness)).toEqual([]);
+  });
+
+  test("an unknown side is never stale, because a packaged install ships no sources", () => {
+    const root = mkdtempSync(join(tmpdir(), "ocx-gui-fresh-"));
+    writeAt(root, "dist/assets/index-CCCCCCCC.js", 2_000_000);
+
+    const missingSources = inspectGuiBundleFreshness({
+      bundlePath: join(root, "dist"),
+      sourcePath: join(root, "src"),
+    });
+    expect(missingSources.sourceModifiedMs).toBeNull();
+    expect(missingSources.stale).toBe(false);
+
+    const missingBundle = inspectGuiBundleFreshness({
+      bundlePath: null,
+      sourcePath: join(root, "dist"),
+    });
+    expect(missingBundle.bundleModifiedMs).toBeNull();
+    expect(missingBundle.stale).toBe(false);
+  });
+
+  test("node_modules cannot make a tree look newer than its own files", () => {
+    const root = mkdtempSync(join(tmpdir(), "ocx-gui-fresh-"));
+    writeAt(root, "src/pages/Usage.tsx", 1_000_000);
+    writeAt(root, "src/node_modules/dep/index.js", 9_000_000);
+
+    expect(newestModifiedMs(join(root, "src"))).toBe(1_000_000_000);
+  });
+});
diff --git a/tests/server/spend-ledger-lifecycle.test.ts b/tests/server/spend-ledger-lifecycle.test.ts
index 17154d46b8f..85607f05376 100644
--- a/tests/server/spend-ledger-lifecycle.test.ts
+++ b/tests/server/spend-ledger-lifecycle.test.ts
@@ -64,7 +64,7 @@ test("a failed start keeps the lease until every listener has actually stopped",
   lifecycle.track(second.server);
   expect(spendLedgerOwnerSnapshot().ownership).toBe("held");
 
-  lifecycle.releaseAfterFailedStart();
+  const rollback = lifecycle.releaseAfterFailedStart();
   // Newest first, and both asked before anything is awaited.
   expect(stopOrder).toEqual(["second", "first"]);
   await drainContinuations();
@@ -76,7 +76,7 @@ test("a failed start keeps the lease until every listener has actually stopped",
   expect(spendLedgerOwnerSnapshot().ownership).toBe("held");
 
   second.settle();
-  await drainContinuations();
+  await rollback;
   expect(spendLedgerOwnerSnapshot().ownership).toBe("unheld");
 });
 
@@ -87,7 +87,7 @@ test("a listener whose stop rejects still stops the rest and still returns the d
   lifecycle.track(healthy.server);
   lifecycle.track(failing.server);
 
-  lifecycle.releaseAfterFailedStart();
+  const rollback = lifecycle.releaseAfterFailedStart();
   expect(stopOrder).toEqual(["failing", "healthy"]);
 
   failing.settle();
@@ -96,6 +96,10 @@ test("a listener whose stop rejects still stops the rest and still returns the d
   expect(spendLedgerOwnerSnapshot().ownership).toBe("held");
 
   healthy.settle();
-  await drainContinuations();
+  await expect(rollback).rejects.toThrow("failed-start listener rollback was uncertain");
+  expect(spendLedgerOwnerSnapshot().ownership).toBe("held");
+  // Explicit test cleanup. Production keeps this owner until process exit because the
+  // rejected stop cannot prove the listener released its socket.
+  lifecycle.release();
   expect(spendLedgerOwnerSnapshot().ownership).toBe("unheld");
 });
diff --git a/tests/service/autostart-health.test.ts b/tests/service/autostart-health.test.ts
index 293f21f4cec..b681fa7a775 100644
--- a/tests/service/autostart-health.test.ts
+++ b/tests/service/autostart-health.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { collectStartupHealth, deriveStartupHealth, formatStartupRoutingDetail, startupHealthSummary } from "../../src/codex/autostart-health";
+import { collectStartupHealth, deriveStartupHealth, formatStartupRoutingDetail, injectedRoutingRestartWarningLines, startupHealthSummary } from "../../src/codex/autostart-health";
 import { unusedProxyWarningLines } from "../../src/cli/status";
 import { classifyCodexRouting, hasInjectedCodexRouting } from "../../src/codex/inject";
 import { isCodexClientProcess, listCodexClientProcesses } from "../../src/codex/native-profile-processes";
@@ -396,6 +396,37 @@ describe("routing visibility (#2411)", () => {
     expect(unusedProxyWarningLines({ proxyUp: true, routingKind: "custom-local" })).toEqual([]);
     expect(unusedProxyWarningLines({ proxyUp: true, routingKind: "unknown" })).toEqual([]);
   });
+
+  // #5261: setup writes routing that outlives the session and then ends on a success line.
+  // The warning reuses the health model rather than re-deriving the condition, so it cannot
+  // disagree with what status and doctor say about the same install.
+  test("injectedRoutingRestartWarningLines speaks exactly when the install is restart-unsafe", () => {
+    const atRisk = deriveStartupHealth(base);
+    expect(atRisk.status).toBe("at-risk");
+    const lines = injectedRoutingRestartWarningLines(atRisk);
+    expect(lines.length).toBeGreaterThan(0);
+    const joined = lines.join(" ");
+    expect(joined).toContain("survives a restart");
+    expect(joined).toContain(startupHealthSummary(atRisk));
+    // The way out that does not require the proxy to come back first.
+    expect(joined).toContain("ocx restore");
+
+    // A CLI-only shim still leaves Codex Desktop uncovered, which is the reported shape.
+    const shimmed = deriveStartupHealth({ ...base, shimInstalled: true, shimHealthy: true });
+    expect(shimmed.status).toBe("at-risk");
+    expect(injectedRoutingRestartWarningLines(shimmed).length).toBeGreaterThan(0);
+    // ...and the warning must stay true in that case: a healthy shim DOES restart the proxy, for
+    // CLI launches. Claiming nothing will would contradict the summary line printed beneath it.
+    expect(injectedRoutingRestartWarningLines(shimmed).join(" ")).not.toContain("nothing here will restart");
+    expect(injectedRoutingRestartWarningLines(shimmed).join(" ")).toContain(startupHealthSummary(shimmed));
+
+    // Native routing has no opencodex restart dependency, so there is nothing to warn about.
+    expect(injectedRoutingRestartWarningLines(deriveStartupHealth({ ...base, routingKind: "native" }))).toEqual([]);
+    // Neither does a viable service, which is the state the warning is steering toward.
+    const served = deriveStartupHealth({ ...base, serviceInstalled: true, serviceViable: true, serviceEnabled: true, serviceRunning: true });
+    expect(served.status).toBe("protected");
+    expect(injectedRoutingRestartWarningLines(served)).toEqual([]);
+  });
 });
 
 // #4550: configured routing is not adopted routing. A Codex client that started
diff --git a/tests/service/launchd-repair.test.ts b/tests/service/launchd-repair.test.ts
index c6c186c1188..abbdf0fe393 100644
--- a/tests/service/launchd-repair.test.ts
+++ b/tests/service/launchd-repair.test.ts
@@ -1052,7 +1052,10 @@ describe("the surfaces around the repair (#4236 defects 1f, 1h, 2)", () => {
     expect(filter).toContain("isProtectedHomeUnderTest(dirname(path))");
     expect(filter).toContain("paths.filter(");
     expect(filter).toContain("refusing to write service install state");
-    expect(slice(state, "function writeServiceInstallState(", "function readServiceInstallState("))
+    // The fail-loud path resolution moved into the compare-and-swap writer when ownership
+    // became a preserved field. Same invariant, one layer down: nothing commits the record
+    // without resolving the write paths that refuse to write nowhere.
+    expect(slice(state, "export function swapServiceInstallState(", "/** The recorded owner of ONE"))
       .toContain("serviceStateWritePaths()");
   });
 
diff --git a/tests/service/process-state.test.ts b/tests/service/process-state.test.ts
index d785e295681..248317fd24a 100644
--- a/tests/service/process-state.test.ts
+++ b/tests/service/process-state.test.ts
@@ -96,6 +96,23 @@ describe("proxy process-state ownership", () => {
     expect(isOcxStartCommandLine("opencodex update --tag latest")).toBe(false);
   });
 
+  test("recognizes the Windows standalone executable, whatever its case or path shape", () => {
+    // scripts/build-standalone.ts and desktop/scripts/prepare-sidecar.ts both emit ocx.exe
+    // on Windows targets, and the bundled sidecar is copied as ocx-<triple>.exe. A quoted
+    // install path with spaces is the realistic WMIC/PowerShell command line for it.
+    expect(isOcxCommandLine('"C:/Program Files/OpenCodex/bin/ocx.exe" start --port 10100')).toBe(true);
+    expect(isOcxCommandLine('"C:\\Program Files\\OpenCodex\\bin\\OCX.EXE" start')).toBe(true);
+    expect(isOcxCommandLine("C:/tools/ocx.exe stop")).toBe(true);
+    expect(isOcxCommandLine("ocx.exe")).toBe(true);
+    expect(isOcxCommandLine("opencodex.exe status")).toBe(true);
+    expect(isOcxStartCommandLine('"C:/Program Files/OpenCodex/bin/ocx.exe" start')).toBe(true);
+    // Lookalikes stay foreign: the token boundary around the executable name is the whole
+    // defence, and widening it for .exe must not widen it for neighbours.
+    expect(isOcxCommandLine("not-ocx.exe start")).toBe(false);
+    expect(isOcxCommandLine("myocx.exe")).toBe(false);
+    expect(isOcxCommandLine("ocx.exes start")).toBe(false);
+  });
+
   test("the ownership probe distinguishes a real owner from a reused PID", () => {
     // The stop-side teardown recovery asks this about a PID recorded in a receipt. Bare
     // liveness said "still running" for any process that inherited the number, so the
diff --git a/tests/service/service-ownership-compatibility.test.ts b/tests/service/service-ownership-compatibility.test.ts
new file mode 100644
index 00000000000..6a216aa3be3
--- /dev/null
+++ b/tests/service/service-ownership-compatibility.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, test } from "bun:test";
+import {
+  assessServiceTakeoverCompatibility,
+  registeredManagingCliInvocation,
+  type ManagingCliObservation,
+} from "../../src/service/ownership-compatibility";
+import type { ServiceInstallState, ServiceOwnershipSubject } from "../../src/service/state";
+
+const SUBJECT: ServiceOwnershipSubject = { kind: "none", revision: 7 };
+const OWNERSHIP_AWARE_STATE: ServiceInstallState = {
+  version: 2,
+  codexHome: "/codex",
+  opencodexHome: "/opencodex",
+  backend: "scheduler",
+  revision: 7,
+  ownershipProtocolVersion: 1,
+};
+
+const absent: ManagingCliObservation = { status: "absent" };
+const observed = (version: string, identity = `manager-${version}`): ManagingCliObservation => ({
+  status: "observed", version, identity,
+});
+
+function assess(options: {
+  state?: ServiceInstallState | null;
+  service?: ManagingCliObservation;
+  path?: ManagingCliObservation;
+} = {}) {
+  return assessServiceTakeoverCompatibility({
+    state: options.state === undefined ? OWNERSHIP_AWARE_STATE : options.state,
+    subject: SUBJECT,
+    managers: {
+      "service-registration": options.service ?? observed("2.61.0", "registered-manager"),
+      path: options.path ?? observed("2.61.0", "path-manager"),
+    },
+  });
+}
+
+describe("permanent takeover compatibility", () => {
+  test("the preserved registration resolves to the exact baked invocation", () => {
+    expect(registeredManagingCliInvocation({
+      ...OWNERSHIP_AWARE_STATE,
+      bunPath: "/runtime/bun",
+      cliPath: "/package/src/cli/index.ts",
+    })).toEqual({
+      status: "resolved", executable: "/runtime/bun", args: ["/package/src/cli/index.ts"],
+    });
+    expect(registeredManagingCliInvocation({
+      ...OWNERSHIP_AWARE_STATE,
+      launcherPath: "/bin/ocx",
+    })).toEqual({ status: "resolved", executable: "/bin/ocx", args: [] });
+  });
+
+  test("every managing CLI must be ownership-aware", () => {
+    expect(assess({ path: observed("2.60.0") })).toMatchObject({
+      kind: "blocked", reason: "managing-cli-unsupported",
+    });
+    expect(assess({ service: observed("2.61.0"), path: observed("2.62.0") })).toMatchObject({
+      kind: "supported", protocolVersion: 1,
+    });
+  });
+
+  test("unknown, malformed and prerelease observations do not authorize takeover", () => {
+    expect(assess({ path: { status: "unknown", reason: "probe timed out" } })).toMatchObject({
+      kind: "blocked", reason: "managing-cli-unknown",
+    });
+    for (const version of ["garbage", "2.61.0-preview.1", "2.60.99"]) {
+      expect(assess({ path: observed(version) })).toMatchObject({
+        kind: "blocked", reason: "managing-cli-unsupported",
+      });
+    }
+  });
+
+  test("a preserved service registration needs the state protocol marker too", () => {
+    expect(assess({ state: { ...OWNERSHIP_AWARE_STATE, ownershipProtocolVersion: undefined } }))
+      .toMatchObject({ kind: "blocked", reason: "service-protocol-unsupported" });
+    expect(assess({ state: null, service: absent, path: observed("2.61.0") }))
+      .toMatchObject({ kind: "supported" });
+  });
+
+  test("an unobserved manager set cannot retroactively protect an older CLI", () => {
+    expect(assess({ state: null, service: absent, path: absent })).toMatchObject({
+      kind: "blocked", reason: "managing-cli-unobserved",
+    });
+  });
+
+  test("the compatibility token binds both manager identities and the approved subject", () => {
+    const original = assess();
+    const replacedPath = assess({ path: observed("2.61.0", "different-path-manager") });
+    const differentSubject = assessServiceTakeoverCompatibility({
+      state: OWNERSHIP_AWARE_STATE,
+      subject: { kind: "none", revision: 8 },
+      managers: {
+        "service-registration": observed("2.61.0", "registered-manager"),
+        path: observed("2.61.0", "path-manager"),
+      },
+    });
+    expect(original.kind).toBe("supported");
+    expect(replacedPath.kind).toBe("supported");
+    expect(differentSubject.kind).toBe("supported");
+    if (original.kind === "supported" && replacedPath.kind === "supported" && differentSubject.kind === "supported") {
+      expect(replacedPath.token).not.toBe(original.token);
+      expect(differentSubject.token).not.toBe(original.token);
+    }
+  });
+});
diff --git a/tests/service/service-ownership-handover.test.ts b/tests/service/service-ownership-handover.test.ts
new file mode 100644
index 00000000000..c79a907711a
--- /dev/null
+++ b/tests/service/service-ownership-handover.test.ts
@@ -0,0 +1,146 @@
+/**
+ * Who may hand the runtime back, and what refuses to take it.
+ *
+ * The maintainer decision behind this: the user's npm service registration is KEPT, never
+ * deleted. So the recorded owner is the only thing standing between a takeover the user
+ * consented to and the next `ocx service repair` — which runs incidentally, from a tray
+ * helper, from `ocx update`, from a doctor suggestion — re-enabling and restarting the npm
+ * launcher without saying a word about it.
+ */
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+import { foreignServiceOwnerRefusal, repairService, unknownServiceOwnerRefusal } from "../../src/service/repair";
+import type { ServiceDiagnostic } from "../../src/service/diagnostics";
+import type { ServiceOwnershipResolution } from "../../src/service/state";
+
+const INSTALLED: ServiceDiagnostic = {
+  supported: true, installed: true, enabled: true, running: true, viable: true,
+  startable: true, stale: false, conflict: false, backend: "launchd", summary: "installed",
+};
+
+const DESKTOP_CLAIM = { owner: "desktop", installId: "app-install-a", consentGeneration: 2 } as const;
+const DESKTOP: ServiceOwnershipResolution = { kind: "owned", ownership: DESKTOP_CLAIM, revision: 4 };
+const UNKNOWN: ServiceOwnershipResolution = { kind: "unknown", reason: "a service state path could not be read (EACCES)" };
+
+describe("repair under an owner that is not this CLI", () => {
+  test("refuses before it asserts, writes, stops or starts anything", async () => {
+    const touched: string[] = [];
+    await expect(repairService({
+      platform: "darwin",
+      diagnose: () => INSTALLED,
+      readOwnership: () => DESKTOP,
+      assertEnv: () => { touched.push("assertEnv"); },
+      assertAuth: () => { touched.push("assertAuth"); },
+      repairLaunchd: () => { touched.push("repairLaunchd"); },
+      restartLaunchd: () => { touched.push("restartLaunchd"); },
+    })).rejects.toThrow(/desktop app owns the runtime/);
+    // A repair that has already rewritten the assets has changed the thing it was
+    // supposed to leave alone, so the gate has to sit in front of every seam.
+    expect(touched).toEqual([]);
+  });
+
+  test("restart refuses on the same terms", async () => {
+    await expect(repairService({
+      platform: "darwin",
+      verb: "restart",
+      diagnose: () => INSTALLED,
+      readOwnership: () => DESKTOP,
+      repairLaunchd: () => { throw new Error("must not run"); },
+      restartLaunchd: () => { throw new Error("must not run"); },
+    })).rejects.toThrow(/desktop app owns the runtime/);
+  });
+
+  /**
+   * Collapsing "I could not read the claim" into "there is no claim" is how a permissions
+   * error reactivates a consented takeover. Only true absence may mean nobody owns it.
+   */
+  test("an unreadable or contradictory record refuses too, rather than reading as CLI-owned", async () => {
+    const touched: string[] = [];
+    await expect(repairService({
+      platform: "darwin",
+      diagnose: () => INSTALLED,
+      readOwnership: () => UNKNOWN,
+      assertEnv: () => { touched.push("assertEnv"); },
+      repairLaunchd: () => { touched.push("repairLaunchd"); },
+    })).rejects.toThrow(/could not be determined/);
+    expect(touched).toEqual([]);
+  });
+
+  test("both refusals name the untouched registration and the way back", () => {
+    const foreign = foreignServiceOwnerRefusal(DESKTOP_CLAIM);
+    expect(foreign).toContain("app-install-a");
+    expect(foreign).toContain("consent generation 2");
+    expect(foreign).toContain("not re-enabled, not rewritten and not restarted");
+    expect(foreign).toContain("ocx service install");
+
+    const unknown = unknownServiceOwnerRefusal("a service state path could not be read (EACCES)");
+    expect(unknown).toContain("EACCES");
+    expect(unknown).toContain("ocx service install");
+    // Both take the verb, so `start` does not report itself as a repair.
+    expect(foreignServiceOwnerRefusal(DESKTOP_CLAIM, "start")).toContain("Background service start stopped");
+    expect(unknownServiceOwnerRefusal("nothing parsed", "start")).toContain("Background service start stopped");
+  });
+
+  test("a CLI owner repairs normally, and so does a record with no claim at all", async () => {
+    const resolutions: ServiceOwnershipResolution[] = [
+      { kind: "none", revision: 0 },
+      { kind: "owned", ownership: { owner: "cli", installId: "npm-install", consentGeneration: 4 }, revision: 8 },
+    ];
+    for (const resolution of resolutions) {
+      let repaired = false;
+      await repairService({
+        platform: "darwin",
+        diagnose: () => INSTALLED,
+        readOwnership: () => resolution,
+        assertEnv: () => {},
+        assertAuth: () => {},
+        repairLaunchd: () => { repaired = true; },
+      });
+      expect(repaired).toBe(true);
+    }
+  });
+
+  test("an uninstalled service still reports that first", async () => {
+    await expect(repairService({
+      platform: "darwin",
+      diagnose: () => ({ ...INSTALLED, installed: false }),
+      readOwnership: () => DESKTOP,
+    })).rejects.toThrow(/not installed/);
+  });
+});
+
+describe("which service verbs are gated", () => {
+  const cli = readFileSync(repoPath("src", "service", "cli.ts"), "utf8");
+  const between = (from: string, to: string): string => cli.slice(cli.indexOf(from), cli.indexOf(to));
+  const installCase = between("case \"install\":", "case \"start\":");
+  const startCase = between("case \"start\":", "case \"stop\"");
+
+  /**
+   * Releasing first meant a cancelled UAC prompt, a failed registration or an aborted
+   * cleanup left the retained npm registration looking CLI-owned, so the next incidental
+   * repair would reactivate it.
+   */
+  test("install releases the marker only after the registration succeeded", () => {
+    expect(installCase).toContain("releaseServiceOwner(ownershipBeforeInstall");
+    expect(installCase.indexOf("installServiceSafely")).toBeLessThan(installCase.indexOf("releaseServiceOwner(ownershipBeforeInstall"));
+    // The failure branch leaves before the release.
+    expect(installCase.indexOf("Service install cleanup failed")).toBeLessThan(installCase.indexOf("releaseServiceOwner(ownershipBeforeInstall"));
+  });
+
+  test("start refuses on the same terms, because it activates the registration", () => {
+    expect(startCase).toContain("resolveServiceOwnership()");
+    expect(startCase).toContain("foreignServiceOwnerRefusal");
+    expect(startCase).toContain("unknownServiceOwnerRefusal");
+    // Reported, not thrown: the Windows tray drives this through a caller that does not catch.
+    expect(startCase).toContain("process.exitCode = 1;");
+  });
+
+  test("stop and uninstall stay ungated, and nothing else releases the marker", () => {
+    const deactivating = cli.slice(cli.indexOf("case \"stop\""));
+    expect(deactivating).not.toContain("resolveServiceOwnership");
+    expect(deactivating).not.toContain("releaseServiceOwner");
+    expect(startCase).not.toContain("releaseServiceOwner");
+    expect(readFileSync(repoPath("src", "service", "repair.ts"), "utf8")).not.toContain("releaseServiceOwner");
+  });
+});
diff --git a/tests/service/service-ownership-state.test.ts b/tests/service/service-ownership-state.test.ts
new file mode 100644
index 00000000000..94a1aa140b4
--- /dev/null
+++ b/tests/service/service-ownership-state.test.ts
@@ -0,0 +1,611 @@
+/**
+ * Durable runtime ownership in the shared service install state.
+ *
+ * The behaviour under test is the one the plan calls R4: every install, repair, update and
+ * stop path reaches service-state.json through `writeServiceInstallState`, which used to
+ * rebuild the whole record and replace the file. Ownership recorded by a desktop takeover
+ * therefore lasted until the next repair — from a tray helper, from `ocx update`, from a
+ * doctor suggestion — and nothing said it had gone.
+ */
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { createTempHome, type TempHome } from "../helpers/temp-home";
+import { repoPath } from "../helpers/repo-root";
+import {
+  desktopOwnsService,
+  inspectServiceStateEvidence,
+  ownershipGrantedTo,
+  parseServiceInstallState,
+  parseServiceOwnership,
+  readServiceInstallState,
+  recordServiceOwner,
+  releaseServiceOwner,
+  removeServiceInstallStateRecords,
+  resolveServiceOwnership,
+  resolveServiceState,
+  ServiceOwnershipSubjectMismatchError,
+  ServiceTakeoverCompatibilityChangedError,
+  ServiceStateConflictError,
+  serviceOwnership,
+  serviceStatePath,
+  serviceStatePaths,
+  swapServiceInstallState,
+  writeServiceInstallState,
+  type RecordServiceOwnerDeps,
+  type ServiceOwner,
+  type ServiceStateSwapDeps,
+} from "../../src/service/state";
+import { assessServiceTakeoverCompatibility, type ManagingCliObservation } from "../../src/service/ownership-compatibility";
+import {
+  OWNERSHIP_MUTATION_LEASE_TOKEN_ENV,
+  ownershipMutationLeaseChildEnvironment,
+  unprivilegedOwnershipMutationEnvironment,
+} from "../../src/service/ownership-mutation-lease.mjs";
+
+let home: TempHome;
+/**
+ * `serviceStatePaths()` deliberately includes the legacy `~/.opencodex/service-state.json`
+ * entry so an install made before OPENCODEX_HOME existed can still be found, and a write
+ * lands on BOTH. Under the suite that second path is the shared sandbox home, which outlives
+ * this file: a claim recorded here reappeared in `tests/service/service.test.ts` and in the
+ * dashboard update worker's tests, where the repair gate and the restart veto then fired on
+ * state those files never wrote. This fixture restores every state path it touched.
+ */
+let statePathSnapshot: { path: string; content: string | null }[] = [];
+
+beforeEach(() => {
+  home = createTempHome("ocx-service-ownership-");
+  statePathSnapshot = serviceStatePaths().map(path => ({
+    path,
+    content: existsSync(path) ? readFileSync(path, "utf8") : null,
+  }));
+});
+
+afterEach(() => {
+  for (const { path, content } of statePathSnapshot) {
+    if (content === null) { if (existsSync(path)) unlinkSync(path); }
+    else writeFileSync(path, content);
+  }
+  home.remove();
+});
+
+const DESKTOP = { owner: "desktop", installId: "app-install-a" } as const;
+const COMPATIBLE_MANAGERS: Readonly<Record<"service-registration" | "path", ManagingCliObservation>> = {
+  "service-registration": { status: "absent" },
+  path: { status: "observed", version: "2.61.0", identity: "path-manager-a" },
+};
+
+function grantServiceOwner(
+  claim: { owner: ServiceOwner; installId: string },
+  deps: ServiceStateSwapDeps & Pick<Partial<RecordServiceOwnerDeps>, "observeManagers"> = {},
+) {
+  const request = approvedOwnerRequest(claim);
+  const { observeManagers = () => COMPATIBLE_MANAGERS, ...swapDeps } = deps;
+  return recordServiceOwner(request, { ...swapDeps, observeManagers });
+}
+
+function approvedOwnerRequest(
+  claim: { owner: ServiceOwner; installId: string },
+  managers = COMPATIBLE_MANAGERS,
+) {
+  const expectedSubject = resolveServiceOwnership();
+  if (expectedSubject.kind === "unknown") throw new Error(expectedSubject.reason);
+  const resolved = resolveServiceState();
+  if (resolved.kind === "unknown") throw new Error(resolved.reason);
+  const expectedCompatibility = assessServiceTakeoverCompatibility({
+    state: resolved.kind === "state" ? resolved.state : null,
+    subject: expectedSubject,
+    managers,
+  });
+  if (expectedCompatibility.kind !== "supported") throw new Error(expectedCompatibility.detail);
+  return { ...claim, expectedSubject, expectedCompatibility };
+}
+
+function releaseCurrentOwner(deps: ServiceStateSwapDeps = {}) {
+  const expected = resolveServiceOwnership();
+  if (expected.kind === "unknown") throw new Error(expected.reason);
+  return releaseServiceOwner(expected, deps);
+}
+
+describe("ownership survives every install-state writer", () => {
+  test("a repair over a desktop takeover keeps the owner, the install id and the generation", () => {
+    const claimed = grantServiceOwner(DESKTOP);
+    expect(claimed.ownership).toEqual({ owner: "desktop", installId: "app-install-a", consentGeneration: 1 });
+
+    // What a repair does: rebuild the install provenance and write it.
+    writeServiceInstallState("scheduler", null);
+
+    const after = readServiceInstallState();
+    expect(after?.ownership).toEqual(claimed.ownership);
+    // The provenance half really was refreshed, so this is preservation rather than a
+    // write that quietly did nothing.
+    expect(after?.bunPath).toBeTruthy();
+    expect(after?.backend).toBe("scheduler");
+    expect(after?.ownershipProtocolVersion).toBe(1);
+    expect(desktopOwnsService()).toBe(true);
+  });
+
+  test("a native-backend switch preserves the claim too", () => {
+    grantServiceOwner(DESKTOP);
+    writeServiceInstallState("native");
+    const after = readServiceInstallState();
+    expect(after?.backend).toBe("native");
+    expect(after?.ownership?.installId).toBe("app-install-a");
+  });
+
+  test("the writer that every subsystem calls preserves rather than rebuilds", () => {
+    const source = readFileSync(repoPath("src", "service", "state.ts"), "utf8");
+    const writer = source.slice(
+      source.indexOf("export function writeServiceInstallState("),
+      source.indexOf("export function readServiceInstallState("),
+    );
+    expect(writer).toContain("swapServiceInstallState(");
+    expect(writer).toContain("current?.ownership");
+  });
+
+  /**
+   * The conversion R4 asks for is one function deep because every writer already routes
+   * through it. This is what keeps that true: a module that composed the record itself, or
+   * reached for the raw swap, would reintroduce the replace-the-file behaviour in a place
+   * nobody would think to look.
+   */
+  test("no service module composes or commits the install record itself", () => {
+    for (const file of ["orchestration.ts", "launchd.ts", "systemd.ts", "windows-ops.ts", "windows-scheduler.ts", "repair.ts"]) {
+      const source = readFileSync(repoPath("src", "service", file), "utf8");
+      expect(source).toContain("writeServiceInstallState");
+      expect(source).not.toContain("swapServiceInstallState");
+      expect(source).not.toContain("service-state.json");
+      expect(source).not.toMatch(/version:\s*2/);
+    }
+  });
+});
+
+describe("consent generation and the comparison rule", () => {
+  test("a grant increments once; the same installation relaunching does not", () => {
+    expect(grantServiceOwner(DESKTOP).ownership.consentGeneration).toBe(1);
+    expect(grantServiceOwner(DESKTOP).ownership.consentGeneration).toBe(1);
+    expect(grantServiceOwner({ owner: "desktop", installId: "app-install-b" }).ownership.consentGeneration).toBe(2);
+    expect(grantServiceOwner({ owner: "cli", installId: "app-install-b" }).ownership.consentGeneration).toBe(3);
+  });
+
+  test("a grant belongs to one installation, not to the kind of owner", () => {
+    const ownership = grantServiceOwner(DESKTOP).ownership;
+    expect(ownershipGrantedTo(ownership, "desktop", "app-install-a")).toBe(true);
+    // A reinstalled app carries a different id and must ask for consent again.
+    expect(ownershipGrantedTo(ownership, "desktop", "app-install-b")).toBe(false);
+    expect(ownershipGrantedTo(ownership, "cli", "app-install-a")).toBe(false);
+    expect(ownershipGrantedTo(null, "desktop", "app-install-a")).toBe(false);
+  });
+
+  test("an install id is required, because an empty one would match nothing and claim everything", () => {
+    expect(() => grantServiceOwner({ owner: "desktop", installId: "" })).toThrow(/install id/);
+  });
+
+  test("releasing returns the dropped claim and creates no record when there is none", () => {
+    expect(releaseCurrentOwner()).toBeNull();
+    expect(existsSync(serviceStatePath())).toBe(false);
+
+    writeServiceInstallState("scheduler", null);
+    grantServiceOwner(DESKTOP);
+    expect(releaseCurrentOwner()).toEqual({ owner: "desktop", installId: "app-install-a", consentGeneration: 1 });
+    expect(serviceOwnership()).toBeNull();
+    expect(desktopOwnsService()).toBe(false);
+    // The install record itself is untouched: releasing ownership is not an uninstall.
+    expect(readServiceInstallState()?.bunPath).toBeTruthy();
+  });
+
+  test("claiming with no install state writes no install provenance it cannot vouch for", () => {
+    grantServiceOwner(DESKTOP);
+    const record = readServiceInstallState();
+    expect(record?.ownership?.owner).toBe("desktop");
+    expect(record?.bunPath).toBeUndefined();
+    expect(record?.launcherPath).toBeUndefined();
+  });
+});
+
+describe("the compare-and-swap", () => {
+  test("a revocation that lands while a provenance writer waits is not resurrected", () => {
+    grantServiceOwner(DESKTOP);
+    let revoked = false;
+    writeServiceInstallState("scheduler", null, {
+      beforeCommit: attempt => {
+        if (attempt === 0 && !revoked) {
+          revoked = true;
+          releaseCurrentOwner();
+        }
+      },
+    });
+    expect(readServiceInstallState()?.ownership).toBeUndefined();
+    expect(readServiceInstallState()?.consentGenerationCeiling).toBe(1);
+  });
+
+  test("authority commit survives a mirror failure and the next writer repairs the mirror", () => {
+    const mirror = home.path("active", "service-state.json");
+    const authority = home.path("default", "service-state.json");
+    mkdirSync(home.path("active"), { recursive: true });
+    mkdirSync(home.path("default"), { recursive: true });
+    const initial = {
+      version: 2, codexHome: home.codexHome, opencodexHome: home.root, backend: "scheduler",
+      revision: 1, ownership: { owner: "desktop", installId: "app-install-a", consentGeneration: 1 },
+      consentGenerationCeiling: 1,
+    } as const;
+    const bytes = `${JSON.stringify(initial, null, 2)}\n`;
+    writeFileSync(mirror, bytes);
+    writeFileSync(authority, bytes);
+    const degraded: string[] = [];
+    releaseServiceOwner({ kind: "owned", ownership: initial.ownership, revision: 1 }, {
+      paths: [mirror, authority],
+      commitStateFile: (path, serialized, validate) => {
+        validate();
+        if (path === mirror) throw new Error("mirror unavailable");
+        writeFileSync(path, serialized);
+      },
+      onMirrorError: path => degraded.push(path),
+    });
+    expect(degraded).toEqual([mirror]);
+    expect(resolveServiceOwnership(inspectServiceStateEvidence([mirror, authority])))
+      .toEqual({ kind: "none", revision: 2 });
+    expect(JSON.parse(readFileSync(mirror, "utf8")).ownership.installId).toBe("app-install-a");
+
+    writeServiceInstallState("scheduler", null, { paths: [mirror, authority] });
+    expect(readFileSync(mirror, "utf8")).toBe(readFileSync(authority, "utf8"));
+    expect(resolveServiceOwnership(inspectServiceStateEvidence([mirror, authority])).kind).toBe("none");
+  });
+
+  test("an authority publication failure leaves both prior records unchanged", () => {
+    const mirror = home.path("active-state.json");
+    const authority = home.path("authority-state.json");
+    const initial = JSON.stringify({
+      version: 2, codexHome: home.codexHome, opencodexHome: home.root, backend: "scheduler", revision: 4,
+    });
+    writeFileSync(mirror, initial);
+    writeFileSync(authority, initial);
+    expect(() => swapServiceInstallState(current => ({ ...current!, launcherPath: "/next/ocx" }), {
+      paths: [mirror, authority],
+      commitStateFile: () => { throw new Error("rename refused"); },
+    })).toThrow(/rename refused/);
+    expect(readFileSync(mirror, "utf8")).toBe(initial);
+    expect(readFileSync(authority, "utf8")).toBe(initial);
+  });
+
+  test("a mirror deletion failure keeps the authority, so a revoked claim cannot migrate back", () => {
+    const mirror = home.path("active-delete.json");
+    const authority = home.path("authority-delete.json");
+    writeFileSync(mirror, JSON.stringify({
+      version: 2, codexHome: home.codexHome, opencodexHome: home.root, backend: "scheduler", revision: 4,
+      ownership: { owner: "desktop", installId: "revoked", consentGeneration: 1 },
+    }));
+    writeFileSync(authority, JSON.stringify({
+      version: 2, codexHome: home.codexHome, opencodexHome: home.root, backend: "scheduler", revision: 5,
+      consentGenerationCeiling: 1,
+    }));
+    expect(() => removeServiceInstallStateRecords({
+      paths: [mirror, authority],
+      unlink: path => {
+        if (path === mirror) throw new Error("mirror delete refused");
+        unlinkSync(path);
+      },
+    })).toThrow(/mirror delete refused/);
+    expect(existsSync(authority)).toBe(true);
+    expect(resolveServiceOwnership(inspectServiceStateEvidence([mirror, authority])))
+      .toEqual({ kind: "none", revision: 5 });
+  });
+
+  test("a writer that lands inside the commit window is detected and the swap recomputes", () => {
+    writeServiceInstallState("scheduler", null);
+    const before = readServiceInstallState()?.revision ?? 0;
+
+    const result = swapServiceInstallState(current => ({ ...current!, launcherPath: "/opt/ocx" }), {
+      beforeCommit: attempt => {
+        // Exactly one interleaved writer, on the first attempt only.
+        if (attempt === 0) grantServiceOwner(DESKTOP);
+      },
+    });
+
+    // Both survive: the late claim because the swap re-read it, the launcher because the
+    // swap re-applied its own change to the newer base.
+    expect(result?.launcherPath).toBe("/opt/ocx");
+    expect(result?.ownership?.installId).toBe("app-install-a");
+    expect(readServiceInstallState()).toEqual(result!);
+    expect(result!.revision!).toBeGreaterThan(before + 1);
+  });
+
+  test("a swap that never wins gives up instead of overwriting the record", () => {
+    writeServiceInstallState("scheduler", null);
+    let competitors = 0;
+    expect(() => swapServiceInstallState(current => ({ ...current!, launcherPath: "/opt/ocx" }), {
+      attempts: 3,
+      beforeCommit: () => { competitors += 1; grantServiceOwner({ owner: "desktop", installId: "app-" + competitors }); },
+    })).toThrow(ServiceStateConflictError);
+
+    expect(competitors).toBe(3);
+    // The last competitor's record stands, unmodified by the swap that lost.
+    const final = readServiceInstallState();
+    expect(final?.ownership?.installId).toBe("app-3");
+    expect(final?.launcherPath).toBeUndefined();
+  });
+
+  test("every commit bumps the revision", () => {
+    writeServiceInstallState("scheduler", null);
+    const first = readServiceInstallState()?.revision;
+    writeServiceInstallState("scheduler", null);
+    expect(readServiceInstallState()?.revision).toBe(first! + 1);
+  });
+
+  test("a mutation that returns null writes nothing", () => {
+    writeServiceInstallState("scheduler", null);
+    const before = readFileSync(serviceStatePath(), "utf8");
+    expect(swapServiceInstallState(() => null)?.revision).toBe(readServiceInstallState()?.revision);
+    expect(readFileSync(serviceStatePath(), "utf8")).toBe(before);
+  });
+
+  test("exhausted revision refuses before publishing an unreadable successor", () => {
+    writeFileSync(serviceStatePath(), JSON.stringify({
+      version: 2, codexHome: home.codexHome, opencodexHome: home.root,
+      backend: "scheduler", revision: Number.MAX_SAFE_INTEGER,
+    }));
+    const before = readFileSync(serviceStatePath(), "utf8");
+    expect(() => swapServiceInstallState(current => ({ ...current!, launcherPath: "/next/ocx" })))
+      .toThrow(/revision is exhausted/);
+    expect(readFileSync(serviceStatePath(), "utf8")).toBe(before);
+  });
+
+  /**
+   * Unreadable is not absent. Reading a directory is the portable way to produce that
+   * answer; a real one is a permission the process does not have. Either way the swap has
+   * no base to preserve from, and computing one from an empty record is exactly how an
+   * ownership claim would be erased by a writer that was never allowed to see it.
+   */
+  test("an unreadable record refuses the write instead of erasing what it cannot read", () => {
+    const unreadable = home.path("state-as-a-directory");
+    mkdirSync(unreadable, { recursive: true });
+    expect(() => swapServiceInstallState(() => ({
+      version: 2, codexHome: home.codexHome, opencodexHome: home.root, backend: "scheduler",
+    }), { paths: [unreadable] })).toThrow(/could not be read/);
+  });
+});
+
+describe("the consented subject is a precondition", () => {
+  test("a delayed service-install release cannot delete a successor claim", () => {
+    const first = grantServiceOwner(DESKTOP);
+    const successor = grantServiceOwner({ owner: "desktop", installId: "app-install-b" });
+    expect(() => releaseServiceOwner(first, { allowRevisionAdvance: true }))
+      .toThrow(ServiceOwnershipSubjectMismatchError);
+    expect(resolveServiceOwnership()).toEqual(successor);
+  });
+
+  test("a revocation during the internal retry invalidates the approval", () => {
+    grantServiceOwner(DESKTOP);
+    const request = approvedOwnerRequest({ owner: "desktop", installId: "app-install-b" });
+    let revoked = false;
+    expect(() => recordServiceOwner(request, {
+      observeManagers: () => COMPATIBLE_MANAGERS,
+      beforeCommit: attempt => {
+        if (attempt === 0 && !revoked) {
+          revoked = true;
+          releaseCurrentOwner();
+        }
+      },
+    })).toThrow(ServiceOwnershipSubjectMismatchError);
+    expect(resolveServiceOwnership().kind).toBe("none");
+  });
+
+  test("a revision-only change requires fresh approval even when the owner is unchanged", () => {
+    writeServiceInstallState("scheduler", null);
+    const request = approvedOwnerRequest(DESKTOP);
+    let changed = false;
+    expect(() => recordServiceOwner(request, {
+      observeManagers: () => COMPATIBLE_MANAGERS,
+      beforeCommit: attempt => {
+        if (attempt === 0 && !changed) {
+          changed = true;
+          writeServiceInstallState("scheduler", null);
+        }
+      },
+    })).toThrow(ServiceOwnershipSubjectMismatchError);
+    expect(readServiceInstallState()?.ownership).toBeUndefined();
+  });
+
+  test("managing CLI compatibility is re-observed immediately before the grant", () => {
+    const request = approvedOwnerRequest(DESKTOP);
+    expect(() => recordServiceOwner(request, {
+      observeManagers: () => ({
+        "service-registration": { status: "absent" },
+        path: { status: "observed", version: "2.60.0", identity: "path-manager-old" },
+      }),
+    })).toThrow(ServiceTakeoverCompatibilityChangedError);
+    expect(readServiceInstallState()?.ownership).toBeUndefined();
+  });
+});
+
+describe("parsing", () => {
+  const valid = { version: 2, codexHome: "/c", opencodexHome: "/o", backend: "scheduler" };
+
+  test("a malformed ownership claim invalidates the record rather than being dropped", () => {
+    expect(parseServiceInstallState({ ...valid, ownership: { owner: "desktop", installId: "a", consentGeneration: 1 } })?.ownership?.owner).toBe("desktop");
+    expect(parseServiceInstallState({ ...valid, ownership: { owner: "desktop", installId: "a" } })).toBeNull();
+    expect(parseServiceInstallState({ ...valid, ownership: { owner: "root", installId: "a", consentGeneration: 1 } })).toBeNull();
+    expect(parseServiceInstallState({ ...valid, ownership: { owner: "cli", installId: "", consentGeneration: 1 } })).toBeNull();
+    expect(parseServiceInstallState({ ...valid, ownership: { owner: "cli", installId: "a", consentGeneration: -1 } })).toBeNull();
+    expect(parseServiceInstallState({ ...valid, ownership: "desktop" })).toBeNull();
+  });
+
+  test("the revision must be a non-negative integer, and absent still parses", () => {
+    expect(parseServiceInstallState({ ...valid, revision: 0 })?.revision).toBe(0);
+    expect(parseServiceInstallState({ ...valid, revision: 1.5 })).toBeNull();
+    expect(parseServiceInstallState({ ...valid, revision: -1 })).toBeNull();
+    expect(parseServiceInstallState({ ...valid, revision: Number.MAX_SAFE_INTEGER })).not.toBeNull();
+    expect(parseServiceInstallState({
+      ...valid,
+      ownership: { owner: "desktop", installId: "a", consentGeneration: Number.MAX_SAFE_INTEGER },
+    })).not.toBeNull();
+    expect(parseServiceInstallState(valid)?.revision).toBeUndefined();
+  });
+
+  test("a validated claim is returned as-is so a newer writer's fields survive a preserve", () => {
+    const ownership = { owner: "desktop", installId: "a", consentGeneration: 1, grantedBy: "first-launch" };
+    expect(parseServiceOwnership(ownership)).toBe(ownership as never);
+  });
+
+  test("a record written before this field existed reads as CLI-owned, not unowned-and-free", () => {
+    writeFileSync(serviceStatePath(), JSON.stringify({ ...valid, codexHome: home.codexHome, opencodexHome: home.root }));
+    expect(serviceOwnership()).toBeNull();
+    expect(desktopOwnsService()).toBe(false);
+  });
+});
+
+describe("the record is read fail-closed", () => {
+  test("unreadable at any path is unknown, not unowned", () => {
+    const unreadable = home.path("unreadable-state");
+    mkdirSync(unreadable, { recursive: true });
+    const resolution = resolveServiceOwnership(inspectServiceStateEvidence([serviceStatePath(), unreadable]));
+    expect(resolution.kind).toBe("unknown");
+  });
+
+  test("a corrupt anchor is unknown; corrupt legacy leftovers are ignored", () => {
+    writeFileSync(serviceStatePath(), "not json");
+    expect(resolveServiceOwnership(inspectServiceStateEvidence([serviceStatePath()])).kind).toBe("unknown");
+    unlinkSync(serviceStatePath());
+
+    // The second path is the legacy default-home entry. Junk left there by an old version
+    // must not be able to block every repair on the machine.
+    grantServiceOwner(DESKTOP);
+    const legacy = home.path("legacy-service-state.json");
+    writeFileSync(legacy, "{ broken");
+    const resolution = resolveServiceOwnership(inspectServiceStateEvidence([legacy, serviceStatePath()]));
+    expect(resolution).toEqual({
+      kind: "owned",
+      ownership: { owner: "desktop", installId: "app-install-a", consentGeneration: 1 },
+      revision: expect.any(Number),
+    });
+  });
+
+  test("paths that name different owners are unknown", () => {
+    grantServiceOwner(DESKTOP);
+    const other = home.path("other-service-state.json");
+    const record = JSON.parse(readFileSync(serviceStatePath(), "utf8"));
+    writeFileSync(other, JSON.stringify({ ...record, ownership: { ...record.ownership, installId: "app-install-b" } }));
+    expect(resolveServiceOwnership(inspectServiceStateEvidence([serviceStatePath(), other])).kind).toBe("unknown");
+  });
+
+  test("absent everywhere is the only thing that means no claim", () => {
+    expect(resolveServiceOwnership(inspectServiceStateEvidence([serviceStatePath()])))
+      .toEqual({ kind: "none", revision: 0 });
+  });
+
+  /**
+   * Pre-existing, and it is why this had to be fixed here: cliEntry() returns null for a
+   * standalone binary, so every standalone install wrote a record its own parser rejected.
+   * After ownership moved into that record, an unparseable record reads as "nobody owns the
+   * runtime" — the exact demotion the claim exists to prevent.
+   */
+  test("a standalone install record parses, so its ownership is readable at all", () => {
+    const standalone = { version: 2, codexHome: "/c", opencodexHome: "/o", bunPath: "/b", cliPath: null, backend: "scheduler" };
+    expect(parseServiceInstallState(standalone)).not.toBeNull();
+    expect(parseServiceInstallState(JSON.parse(JSON.stringify(standalone)))).not.toBeNull();
+    expect(parseServiceInstallState({ ...standalone, cliPath: "" })).toBeNull();
+  });
+});
+
+describe("the generation cannot be reused", () => {
+  test("a release keeps the high-water mark so the next grant does not repeat it", () => {
+    expect(grantServiceOwner(DESKTOP).ownership.consentGeneration).toBe(1);
+    releaseCurrentOwner();
+    expect(readServiceInstallState()?.consentGenerationCeiling).toBe(1);
+    // Without the ceiling this would be 1 again, and an app-local record still holding the
+    // first 1 would read the second grant as its own prior consent.
+    expect(grantServiceOwner(DESKTOP).ownership.consentGeneration).toBe(2);
+  });
+
+  test("an ordinary install-state write carries the ceiling forward", () => {
+    grantServiceOwner(DESKTOP);
+    releaseCurrentOwner();
+    writeServiceInstallState("scheduler", null);
+    expect(readServiceInstallState()?.consentGenerationCeiling).toBe(1);
+    expect(grantServiceOwner({ owner: "desktop", installId: "app-install-b" }).ownership.consentGeneration).toBe(2);
+  });
+});
+
+describe("the anchor lock", () => {
+  test("delegation is granted only to selected child environments", () => {
+    const parent = { KEEP: "yes", [OWNERSHIP_MUTATION_LEASE_TOKEN_ENV]: "stale" };
+    const delegated = ownershipMutationLeaseChildEnvironment(parent, "current");
+    const unprivileged = unprivilegedOwnershipMutationEnvironment(parent);
+    expect(delegated).toEqual({ KEEP: "yes", [OWNERSHIP_MUTATION_LEASE_TOKEN_ENV]: "current" });
+    expect(unprivileged).toEqual({ KEEP: "yes" });
+    expect(parent[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV]).toBe("stale");
+  });
+
+  test("a live update lease blocks ownership mutation before the state lock is touched", () => {
+    const leasePath = serviceStatePath() + ".mutation.lock";
+    const processInstance = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";
+    const token = "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb";
+    mkdirSync(leasePath, { recursive: true });
+    writeFileSync(`${leasePath}/v1-777-${processInstance}-${token}.json`, JSON.stringify({
+      version: 1, pid: 777, processInstance, token, createdAt: 1,
+    }));
+    expect(() => writeServiceInstallState("scheduler", null, {
+      paths: [serviceStatePath()],
+      mutationLease: { waitMs: 0, now: () => 1_000_000, processAlive: () => true },
+    })).toThrow(/runtime mutation lease/);
+    expect(existsSync(serviceStatePath())).toBe(false);
+  });
+
+  test("a crashed incomplete update lease is reclaimed only after the stale grace", () => {
+    const leasePath = serviceStatePath() + ".mutation.lock";
+    mkdirSync(leasePath, { recursive: true });
+    writeServiceInstallState("scheduler", null, {
+      paths: [serviceStatePath()],
+      mutationLease: {
+        waitMs: 0,
+        now: () => Date.now() + 60_000,
+        processAlive: () => false,
+      },
+    });
+    expect(readServiceInstallState()?.backend).toBe("scheduler");
+  });
+
+  test("age never evicts a holder whose PID is still alive", () => {
+    const lockPath = serviceStatePath() + ".lock";
+    const processInstance = "11111111-1111-4111-8111-111111111111";
+    const token = "22222222-2222-4222-8222-222222222222";
+    mkdirSync(lockPath, { recursive: true });
+    writeFileSync(`${lockPath}/v1-777-${processInstance}-${token}.json`, JSON.stringify({
+      version: 1, pid: 777, processInstance, token, createdAt: 1,
+    }));
+    expect(() => swapServiceInstallState(() => ({
+      version: 2, codexHome: home.codexHome, opencodexHome: home.root, backend: "scheduler",
+    }), {
+      paths: [serviceStatePath()],
+      lockWaitMs: 0,
+      lockHooks: { now: () => 1_000_000, processAlive: () => true },
+    })).toThrow(/another process owns/);
+    // Nothing was written: the swap never reached a commit.
+    expect(existsSync(serviceStatePath())).toBe(false);
+  });
+
+  test("a late release cannot remove a successor lock", () => {
+    const statePath = serviceStatePath();
+    const lockPath = `${statePath}.lock`;
+    const successorInstance = "33333333-3333-4333-8333-333333333333";
+    const successorToken = "44444444-4444-4444-8444-444444444444";
+    swapServiceInstallState(current => ({
+      ...(current ?? { version: 2, codexHome: home.codexHome, opencodexHome: home.root, backend: "scheduler" }),
+      launcherPath: "/opt/ocx",
+    }), {
+      paths: [statePath],
+      lockHooks: {
+        beforeRelease: () => {
+          for (const entry of readdirSync(lockPath)) unlinkSync(`${lockPath}/${entry}`);
+          rmSync(lockPath, { recursive: true });
+          mkdirSync(lockPath, { recursive: true });
+          writeFileSync(`${lockPath}/v1-888-${successorInstance}-${successorToken}.json`, JSON.stringify({
+            version: 1, pid: 888, processInstance: successorInstance, token: successorToken, createdAt: 2,
+          }));
+        },
+      },
+    });
+    expect(existsSync(`${lockPath}/v1-888-${successorInstance}-${successorToken}.json`)).toBe(true);
+  });
+
+});
diff --git a/tests/service/service-start-environment.test.ts b/tests/service/service-start-environment.test.ts
index a858e4f90a9..6157bee3e97 100644
--- a/tests/service/service-start-environment.test.ts
+++ b/tests/service/service-start-environment.test.ts
@@ -28,7 +28,12 @@ test("service start refuses a changed install environment before it starts the l
 
   const body = source.slice(source.indexOf("export async function serviceCommand"));
   expect(body).toContain('case "start":');
-  const startCase = body.slice(body.indexOf('case "start":'));
-  expect(startCase).toMatch(/assertServiceEnvironmentMatchesInstall\(\);\s*ops\.start\(\);/);
+  const startCase = body.slice(body.indexOf('case "start":'), body.indexOf('case "stop"'));
+  const guardAt = startCase.indexOf("assertServiceEnvironmentMatchesInstall();");
+  const launchAt = startCase.indexOf("ops.start();");
+  expect(guardAt).toBeGreaterThan(-1);
+  expect(launchAt).toBeGreaterThan(guardAt);
+  // The runtime-ownership refusal now sits between them. It can only PREVENT the start, so
+  // the invariant is unchanged: nothing reaches the service manager before the guard has run.
+  expect(startCase.slice(guardAt, launchAt)).not.toContain("ops.");
 });
-
diff --git a/tests/service/shutdown-launcher.test.ts b/tests/service/shutdown-launcher.test.ts
index edda9ecb5b0..c8cf5b2d98b 100644
--- a/tests/service/shutdown-launcher.test.ts
+++ b/tests/service/shutdown-launcher.test.ts
@@ -7,6 +7,7 @@ import { join } from "node:path";
 import { claimOwnedServiceHome } from "../helpers/owned-service-home";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
 import { repoPath } from "../helpers/repo-root";
+import { OCX_ROUTING_MARKER_LINE } from "../../src/codex/injected-marker";
 
 /**
  * Regression: `ocx start` + Ctrl-C must NOT orphan the Bun proxy.
@@ -152,7 +153,7 @@ describe.skipIf(!runnable)("ocx launcher graceful shutdown", () => {
         }
         expect(existsSync(join(home, "ocx.pid"))).toBe(true);
         const injected = readFileSync(codexConfig, "utf8");
-        expect(injected).toContain("# Auto-injected by opencodex");
+        expect(injected).toContain(OCX_ROUTING_MARKER_LINE);
         expect(injected).toContain(`openai_base_url = "http://127.0.0.1:${port}/v1"`);
         expect(injected).not.toContain("model_providers.opencodex");
 
diff --git a/tests/service/standalone-service.test.ts b/tests/service/standalone-service.test.ts
new file mode 100644
index 00000000000..3f29882a0da
--- /dev/null
+++ b/tests/service/standalone-service.test.ts
@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+import { buildServiceShellCommand } from "../../src/service/health";
+import { buildWinswXml } from "../../src/lib/winsw";
+import { cliEntry } from "../../src/service/state";
+import { buildWindowsServiceScript } from "../../src/service/windows-taskxml";
+
+const runtime = {
+  path: "/opt/opencodex/ocx",
+  source: "standalone" as const,
+  overrideEnv: "OPENCODEX_BUN_PATH" as const,
+};
+
+test("standalone service entries invoke the executable without a source CLI", () => {
+  const entry = cliEntry(runtime);
+  expect(entry).toEqual({ bun: runtime.path, bunRuntimeSource: "standalone", cli: null });
+  expect(buildServiceShellCommand(entry.bun, entry.cli, 10177)).toContain(
+    "exec '/opt/opencodex/ocx' start --port 10177",
+  );
+  expect(buildWindowsServiceScript(entry, 10177)).toContain(
+    '"%OCX_BUN%" start --port 10177',
+  );
+  expect(buildWindowsServiceScript(entry, 10177)).not.toContain('"%OCX_BUN%" "%OCX_CLI%" start');
+  expect(buildWinswXml(entry, { OCX_BAKE_PORT: "10177" })).toContain(
+    "<arguments>start --port 10177</arguments>",
+  );
+});
diff --git a/tests/update/update-desktop-owner.test.ts b/tests/update/update-desktop-owner.test.ts
new file mode 100644
index 00000000000..004266a7df4
--- /dev/null
+++ b/tests/update/update-desktop-owner.test.ts
@@ -0,0 +1,273 @@
+/**
+ * What an update may do to a runtime it does not own.
+ *
+ * Two updaters reach the same situation: the Bun path in src/update/index.ts and the npm
+ * and pnpm path in bin/ocx.mjs. Both stop the proxy and then run `ocx service repair`, and
+ * under a desktop owner both halves are wrong — the running server is the app's bundled
+ * sidecar, and the repair re-enables the npm launcher the takeover superseded. The rule is
+ * one plain-ESM module for the reason #3008 recorded: two lanes deciding separately is how
+ * a fix ships on one side only.
+ */
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+import {
+  inspectPackageRuntimeLiveness,
+  planStoppedRuntimeRecovery,
+  planUpdateRuntimeHandling,
+} from "../../src/update/runtime-ownership.mjs";
+import { parseInstallStateRecord, selectAuthoritativeServiceState } from "../../src/service/install-state-contract.mjs";
+
+describe("the runtime-ownership veto", () => {
+  test("a desktop owner stops both the stop and the service refresh, and says so", () => {
+    const plan = planUpdateRuntimeHandling({
+      ownership: { owner: "desktop", installId: "app-install-a", consentGeneration: 3 },
+      serviceInstalled: true,
+    });
+    expect(plan.mayReplacePackage).toBe(false);
+    expect(plan.mayStopRuntime).toBe(false);
+    expect(plan.mayRestoreService).toBe(false);
+    expect(plan.notice).toContain("app-install-a");
+    expect(plan.notice).toContain("consent generation 3");
+    expect(plan.notice).toContain("neither re-enabled nor restarted");
+  });
+
+  test("a CLI owner and an unowned runtime both take the ordinary path", () => {
+    for (const ownership of [null, { owner: "cli", installId: "npm-install", consentGeneration: 1 }]) {
+      expect(planUpdateRuntimeHandling({ ownership, serviceInstalled: true }))
+        .toEqual({ mayReplacePackage: true, mayStopRuntime: true, mayRestoreService: true, notice: null });
+      expect(planUpdateRuntimeHandling({ ownership, serviceInstalled: false }))
+        .toEqual({ mayReplacePackage: true, mayStopRuntime: true, mayRestoreService: false, notice: null });
+    }
+  });
+
+  test("an owner this version does not recognise is treated as foreign, not as our own", () => {
+    const plan = planUpdateRuntimeHandling({
+      ownership: { owner: "something-newer", installId: "x", consentGeneration: 1 },
+      serviceInstalled: true,
+    });
+    expect(plan.mayReplacePackage).toBe(false);
+    expect(plan.mayStopRuntime).toBe(false);
+  });
+});
+
+describe("stopped runtime recovery authority", () => {
+  const base = {
+    stopAttempted: true,
+    ownership: null,
+    ownershipUnknown: false,
+    sameOwner: true,
+    liveness: "dead" as const,
+    serviceInstalled: false,
+    launcherUsable: true,
+    hadRuntimeState: true,
+  };
+
+  test("only the same readable CLI owner with dead endpoints can restart", () => {
+    expect(planStoppedRuntimeRecovery(base)).toEqual({ action: "direct", reason: "same-cli-owner" });
+    expect(planStoppedRuntimeRecovery({ ...base, serviceInstalled: true })).toEqual({
+      action: "service", reason: "same-cli-owner",
+    });
+  });
+
+  test("foreign, unknown and live outcomes never revive the stopped runtime", () => {
+    expect(planStoppedRuntimeRecovery({ ...base, sameOwner: false })).toEqual({
+      action: "none", reason: "ownership-transferred",
+    });
+    expect(planStoppedRuntimeRecovery({ ...base, ownershipUnknown: true })).toEqual({
+      action: "manual", reason: "ownership-unknown",
+    });
+    for (const liveness of ["live", "unknown"] as const) {
+      expect(planStoppedRuntimeRecovery({ ...base, liveness })).toEqual({
+        action: "manual", reason: `runtime-${liveness}`,
+      });
+    }
+  });
+});
+
+describe("replacement runtime inspection", () => {
+  const capturedTarget = { hostname: "127.0.0.1", port: 10100 };
+
+  test("the fresh runtime record is read and probed before the captured stop target", () => {
+    const currentTarget = { hostname: "127.0.0.1", port: 10200 };
+    const events: string[] = [];
+    const result = inspectPackageRuntimeLiveness({
+      capturedTarget,
+      readCurrentTarget: () => { events.push("read-current"); return { kind: "target", target: currentTarget }; },
+      probe: target => {
+        events.push(`probe:${target.port}`);
+        return target === currentTarget ? "live" : "dead";
+      },
+    });
+    expect(events).toEqual(["read-current", `probe:${currentTarget.port}`, `probe:${capturedTarget.port}`]);
+    expect(result).toEqual({ current: "live", captured: "dead", overall: "live" });
+  });
+
+  test("an absent current record stays distinct from a dead captured endpoint", () => {
+    const events: string[] = [];
+    const result = inspectPackageRuntimeLiveness({
+      capturedTarget,
+      readCurrentTarget: () => { events.push("read-current"); return { kind: "absent" }; },
+      probe: target => { events.push(`probe:${target.port}`); return "dead"; },
+    });
+    expect(events).toEqual(["read-current", `probe:${capturedTarget.port}`]);
+    expect(result).toEqual({ current: "absent", captured: "dead", overall: "dead" });
+  });
+
+  test("an unreadable current record fails closed even when the captured endpoint is dead", () => {
+    const events: string[] = [];
+    const result = inspectPackageRuntimeLiveness({
+      capturedTarget,
+      readCurrentTarget: () => { events.push("read-current"); return { kind: "unknown" }; },
+      probe: target => { events.push(`probe:${target.port}`); return "dead"; },
+    });
+    expect(events).toEqual(["read-current", `probe:${capturedTarget.port}`]);
+    expect(result).toEqual({ current: "unknown", captured: "dead", overall: "unknown" });
+  });
+});
+
+describe("the Node and Bun paths share one full-record authority", () => {
+  const state = (revision: number, installId = "desktop-a") => ({
+    version: 2, codexHome: "/codex", opencodexHome: "/opencodex", backend: "scheduler",
+    revision, ownership: { owner: "desktop" as const, installId, consentGeneration: 1 },
+  });
+
+  test("a complete record is required before ownership is projected", () => {
+    expect(parseInstallStateRecord(state(1))?.ownership?.installId).toBe("desktop-a");
+    expect(parseInstallStateRecord({ ownership: state(1).ownership })).toBeNull();
+  });
+
+  test("the default-home authority wins over an older active-home mirror", () => {
+    const selected = selectAuthoritativeServiceState([
+      { path: "active", kind: "valid", state: state(4, "old-owner") },
+      { path: "default", kind: "valid", state: { ...state(5), ownership: undefined } },
+    ]);
+    expect(selected).toMatchObject({ kind: "state", revision: 5, needsRepair: true });
+    if (selected.kind === "state") expect(selected.state.ownership).toBeUndefined();
+  });
+
+  test("same-or-newer mirror disagreement is unknown rather than a vote", () => {
+    expect(selectAuthoritativeServiceState([
+      { path: "active", kind: "valid", state: state(5, "other-owner") },
+      { path: "default", kind: "valid", state: state(5) },
+    ])).toMatchObject({ kind: "unknown" });
+  });
+
+  test("an absent authority imports one valid legacy record, while unreadable authority refuses", () => {
+    expect(selectAuthoritativeServiceState([
+      { path: "active", kind: "valid", state: state(3) },
+      { path: "default", kind: "absent" },
+    ])).toMatchObject({ kind: "state", revision: 3, needsRepair: true });
+    expect(selectAuthoritativeServiceState([
+      { path: "active", kind: "valid", state: state(3) },
+      { path: "default", kind: "unreadable", reason: "EACCES" },
+    ])).toMatchObject({ kind: "unknown" });
+  });
+});
+
+describe("both updaters consult the shared rule", () => {
+  const bunPath = readFileSync(repoPath("src", "update", "index.ts"), "utf8");
+  const launcher = readFileSync(repoPath("bin", "ocx.mjs"), "utf8");
+
+  test("the Bun updater gates its stop, its refresh and its restart hint", () => {
+    expect(bunPath).toContain("from \"./runtime-ownership.mjs\"");
+    expect(bunPath).toContain("if (runtimePlan.mayStopRuntime && (serviceWasInstalled || readPid() || readRuntimePort() || pendingTeardownOutstanding()))");
+    expect(bunPath).toContain("if (!runtimePlan.mayReplacePackage)");
+    expect(bunPath).toContain("if (postInstallPlan.mayRestoreService) {");
+  });
+
+  test("the npm launcher gates its stop, its refresh and its failure recovery", () => {
+    expect(launcher).toContain("from \"../src/update/runtime-ownership.mjs\"");
+    expect(launcher).toContain("if (stopNeeded && !runtimePlan.mayStopRuntime)");
+    expect(launcher).toContain("if (stopNeeded) {");
+    expect(launcher).toContain("if (!runtimePlan.mayReplacePackage)");
+    expect(launcher).toContain("planStoppedRuntimeRecovery({");
+    expect(launcher).toContain("if (postInstallPlan.mayRestoreService) {");
+  });
+
+  test("neither updater reimplements the decision", () => {
+    for (const source of [bunPath, launcher]) {
+      expect(source).toContain("planUpdateRuntimeHandling({");
+      expect(source).not.toMatch(/owner\s*!==\s*"cli"/);
+    }
+  });
+
+  /**
+   * The launcher's own reader is what made the two lanes disagree, so its absence is the
+   * property worth pinning: no JSON.parse of the state record, no claim validation, and the
+   * contract module imported instead.
+   */
+  test("the launcher reads the record only through the shared contract", () => {
+    expect(launcher).toContain('from "../src/service/install-state-contract.mjs"');
+    expect(launcher).toContain("selectAuthoritativeServiceState(");
+    expect(launcher).toContain("serviceStateFilesFor(");
+    expect(launcher).not.toContain("parsed.ownership");
+    const reader = launcher.slice(launcher.indexOf("const readOwnership = () =>"), launcher.indexOf("const ownershipIdentity ="));
+    expect(reader).not.toContain("consentGeneration");
+    // The authoritative reader delegates to the same module rather than keeping a twin.
+    const state = readFileSync(repoPath("src", "service", "state.ts"), "utf8");
+    expect(state).toContain('from "./install-state-contract.mjs"');
+    expect(state).toContain("return parseInstallStateRecord(value)");
+    expect(state).toContain("selectAuthoritativeServiceState(");
+  });
+});
+
+describe("an unreadable record is not an unowned runtime", () => {
+  test("unknown ownership vetoes both halves and points at the way back", () => {
+    const plan = planUpdateRuntimeHandling({ ownership: null, ownershipUnknown: true, serviceInstalled: true });
+    expect(plan.mayReplacePackage).toBe(false);
+    expect(plan.mayStopRuntime).toBe(false);
+    expect(plan.mayRestoreService).toBe(false);
+    expect(plan.notice).toContain("could not be determined");
+    expect(plan.notice).toContain("ocx service install");
+  });
+
+  test("the desktop notice also says how to clear a stale marker", () => {
+    const plan = planUpdateRuntimeHandling({
+      ownership: { owner: "desktop", installId: "a", consentGeneration: 1 },
+      serviceInstalled: true,
+    });
+    expect(plan.notice).toContain("ocx service install");
+  });
+});
+
+describe("every updater re-reads ownership before it starts a proxy directly", () => {
+  const bunPath = readFileSync(repoPath("src", "update", "index.ts"), "utf8");
+  const launcher = readFileSync(repoPath("bin", "ocx.mjs"), "utf8");
+  const worker = readFileSync(repoPath("src", "update", "job.ts"), "utf8");
+
+  /**
+   * Ownership is sampled before a package install that can take minutes. If the app claims
+   * the runtime during it, the post-update repair refuses — and both callers used to read
+   * that refusal as a generic failure and start an npm proxy beside the app's sidecar.
+   */
+  test("the two package updaters re-resolve before the direct-start fallback", () => {
+    for (const source of [bunPath, launcher]) {
+      const fallbackAt = source.indexOf("starting the proxy directly instead");
+      expect(fallbackAt).toBeGreaterThan(-1);
+      const recheckAt = source.lastIndexOf("planUpdateRuntimeHandling({", fallbackAt);
+      expect(recheckAt).toBeGreaterThan(-1);
+      expect(source.slice(recheckAt, fallbackAt)).toContain("nowOwned.mayStopRuntime");
+    }
+  });
+
+  /**
+   * The dashboard is a third lane. It defaults to restarting, and after the package updater
+   * correctly left a foreign-owned runtime alone it would reclaim the port, run the repair
+   * that now refuses, and fall through to a direct start.
+   */
+  test("the dashboard worker checks before it restarts anything", () => {
+    const restartAt = worker.indexOf("if (restart) {");
+    const handoffAt = worker.indexOf("finishGuiUpdateRestart(", restartAt);
+    const gateAt = worker.indexOf("runUpdateRestartWithOwnershipLease(", restartAt);
+    expect(gateAt).toBeGreaterThan(restartAt);
+    expect(gateAt).toBeLessThan(handoffAt);
+    expect(worker.slice(gateAt)).toContain("outcome.kind === \"veto\"");
+    expect(worker.slice(gateAt)).toContain("restarted: false");
+    // The veto is the shared rule, not a second opinion about ownership.
+    const veto = readFileSync(repoPath("src", "update", "restart-ownership.ts"), "utf8");
+    expect(veto).toContain("planUpdateRuntimeHandling({");
+    expect(veto).toContain("resolveServiceOwnership");
+    expect(veto).toContain("acquireOwnershipMutationLease");
+  });
+});
diff --git a/tests/update/update-stop-classification.test.ts b/tests/update/update-stop-classification.test.ts
index f14334dff5a..13ddae767aa 100644
--- a/tests/update/update-stop-classification.test.ts
+++ b/tests/update/update-stop-classification.test.ts
@@ -316,8 +316,10 @@ describe("stop failure classification (#3008)", () => {
     expect(cli).toMatch(/if \(stopFailed\) process\.exitCode = 1;\s*\n\s*else if \(historyOnlyFailure\) process\.exitCode = STOP_HISTORY_INCOMPLETE_EXIT_CODE;/);
     // The code is set rather than exited inline so the dispatcher still receives the
     // return value and decides what happens next. The deferred code (#4718) sits between
-    // them and obeys the same rule, so the function still ends by returning.
-    expect(cli).toMatch(/process\.exitCode = STOP_HISTORY_INCOMPLETE_EXIT_CODE;[\s\S]*?\n\s*return !stopFailed;\n\}/);
+    // them and obeys the same rule, so the function still ends by returning. The return
+    // is a structured outcome since the stop summary landed: ok preserves the old
+    // boolean exactly, and the summary derives from the same signals.
+    expect(cli).toMatch(/process\.exitCode = STOP_HISTORY_INCOMPLETE_EXIT_CODE;[\s\S]*?\n\s*return \{ ok: !stopFailed, summary \};\n\}/);
     // The deferred code never outranks an ordinary failure, and it is only reachable when
     // this run can still prove the obligations left behind are the ones it chose to keep.
     expect(cli).toMatch(/else if \(historyDeferredNonces\) \{/);
diff --git a/tests/update/update-stop-first.test.ts b/tests/update/update-stop-first.test.ts
index 0c21fce698c..f2e1ebc809d 100644
--- a/tests/update/update-stop-first.test.ts
+++ b/tests/update/update-stop-first.test.ts
@@ -534,7 +534,9 @@ describe("update stops the running proxy before replacing files", () => {
     expect(stopAt).toBeGreaterThan(-1);
     expect(updateAt).toBeGreaterThan(-1);
     expect(stopAt).toBeLessThan(updateAt);
-    expect(updateSource).toContain("if (serviceWasInstalled || readPid() || readRuntimePort() || pendingTeardownOutstanding())");
+    // The four signals are now inside a runtime-ownership veto: a desktop-owned runtime is
+    // not stopped at all. Every original reason to stop still reaches the gate unchanged.
+    expect(updateSource).toContain("if (runtimePlan.mayStopRuntime && (serviceWasInstalled || readPid() || readRuntimePort() || pendingTeardownOutstanding()))");
   });
 
   test("integrity pre-flight runs BEFORE the stop so anomalous metadata never unloads the proxy", () => {
@@ -600,9 +602,9 @@ describe("update stops the running proxy before replacing files", () => {
     expect(updateSource).toContain("serviceReinstallArgs()");
     expect(launcherSource).toContain("aborting the update");
     expect(launcherSource).toContain('"service", "repair"');
-    // The launcher still reads service-state.json for service-installed detection, and
-    // for the backend choice on the genuinely-absent install fallback.
-    expect(launcherSource).toContain('"service-state.json"');
+    // The launcher reads the shared active/default state-path set for service-installed
+    // detection and the authoritative backend on the genuinely-absent install fallback.
+    expect(launcherSource).toContain("serviceStateFilesFor");
     // That marker can be STALE, so the fallback asks for structured state rather than
     // parsing a failure message; bin/ocx.mjs is plain Node and cannot import
     // diagnoseService(), so it reads startup.serviceInstalled from `status --json`.
@@ -783,8 +785,10 @@ esac
     // A pending-teardown receipt is a fourth reason to stop: after a parent crashed
     // mid-deferral the service, pid and runtime records can all be absent while shared
     // client config still points at a proxy that is gone (#3008).
-    expect(updateSource).toContain("if (serviceWasInstalled || readPid() || readRuntimePort() || pendingTeardownOutstanding())");
-    expect(launcherSource).toContain("if (serviceWasInstalled || hasRuntimeState || hasPendingTeardown)");
+    expect(updateSource).toContain("if (runtimePlan.mayStopRuntime && (serviceWasInstalled || readPid() || readRuntimePort() || pendingTeardownOutstanding()))");
+    expect(launcherSource).toContain("const stopNeeded = serviceWasInstalled || hasRuntimeState || hasPendingTeardown");
+    expect(launcherSource).toContain("if (stopNeeded && !runtimePlan.mayStopRuntime)");
+    expect(launcherSource).toContain("if (stopNeeded) {");
     // The rule now lives in the shared post-stop decision both lanes import (#3008): a
     // history-only stop proceeds, every other nonzero status and any surviving runtime
     // state aborts. Pinned by tests/update/update-stop-classification.test.ts.
@@ -792,6 +796,41 @@ esac
     expect(launcherSource).toContain("hasRuntimeState: stillHasRuntimeState");
   });
 
+  test("the Node updater holds one authority from stop permission through replacement", () => {
+    const leaseAt = launcherSource.indexOf("const updateLease = acquireOwnershipMutationLease(");
+    const lockedPlanAt = launcherSource.indexOf("const lockedPlan = planUpdateRuntimeHandling(", leaseAt);
+    const stopAt = launcherSource.indexOf('[launcher, "stop"]', lockedPlanAt);
+    const replacementAt = launcherSource.indexOf("const replacementOwnership = readOwnership()", stopAt);
+    const releaseAt = launcherSource.indexOf("releaseUpdateLease()", replacementAt);
+    expect(leaseAt).toBeGreaterThan(-1);
+    expect(lockedPlanAt).toBeGreaterThan(leaseAt);
+    expect(stopAt).toBeGreaterThan(lockedPlanAt);
+    expect(replacementAt).toBeGreaterThan(stopAt);
+    expect(releaseAt).toBeGreaterThan(replacementAt);
+    const stopEnvAt = launcherSource.indexOf("env: mutationChildEnvironment()", stopAt);
+    expect(stopEnvAt).toBeGreaterThan(stopAt);
+    expect(stopEnvAt).toBeLessThan(replacementAt);
+    expect(launcherSource.slice(lockedPlanAt, stopAt)).toContain("!runtimePlan.mayStopRuntime");
+    const packageReplacement = launcherSource.slice(stopAt, launcherSource.indexOf("const postInstallPlan", stopAt));
+    expect(packageReplacement.match(/unprivilegedOwnershipMutationEnvironment/g)).toHaveLength(2);
+  });
+
+  test("replacement refusal reaches owner-aware recovery before releasing authority", () => {
+    const refusalAt = launcherSource.indexOf("replacementOwnership.subjectToken !== initialOwnership.subjectToken");
+    const recoverAt = launcherSource.indexOf('recoverStoppedRuntimeAfterFailure("replacement was refused")', refusalAt);
+    const releaseAt = launcherSource.indexOf("releaseUpdateLease()", recoverAt);
+    expect(refusalAt).toBeGreaterThan(-1);
+    expect(recoverAt).toBeGreaterThan(refusalAt);
+    expect(releaseAt).toBeGreaterThan(recoverAt);
+    const recovery = launcherSource.slice(
+      launcherSource.indexOf("function recoverStoppedRuntimeAfterFailure("),
+      launcherSource.indexOf("const hasPendingTeardown", launcherSource.indexOf("function recoverStoppedRuntimeAfterFailure(")),
+    );
+    expect(recovery).toContain("planStoppedRuntimeRecovery");
+    expect(recovery).toContain("sameOwner:");
+    expect(recovery).toContain("currentPackageRuntimeLiveness()");
+  });
+
   test("GUI worker update children use pipe stdio so background updates do not open consoles", () => {
     expect(updateSource).toContain("function updateChildStdio()");
     expect(updateSource).toContain('process.env.OCX_SERVICE === "1"');
diff --git a/tests/usage/cache-diagnostic.test.ts b/tests/usage/cache-diagnostic.test.ts
new file mode 100644
index 00000000000..4e61d7976d4
--- /dev/null
+++ b/tests/usage/cache-diagnostic.test.ts
@@ -0,0 +1,209 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { captureCodexAffinityDiagnostic } from "../../src/codex/affinity-debug";
+import { getDebugLogEntries, resetDebugLogBufferForTests } from "../../src/lib/debug-log-buffer";
+import { resetDebugSettingsForTests, setDebugSettings } from "../../src/lib/debug-settings";
+import {
+  appendFinalCacheDiagnostic,
+  cacheDiagnosticPath,
+  CACHE_DEBUG_KEEP_LINES,
+  CACHE_DEBUG_MAX_LINES,
+  observeInbound,
+  observeOutbound,
+  rebindCacheDiagnosticBodyAlias,
+  tagCacheDiagnosticValue,
+} from "../../src/usage/cache-diagnostic";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+let testDir = "";
+let previousHome: string | undefined;
+let previousDebug: string | undefined;
+
+beforeEach(() => {
+  previousHome = process.env.OPENCODEX_HOME;
+  previousDebug = process.env.OPENCODEX_CACHE_DEBUG;
+  testDir = mkdtempSync(join(tmpdir(), "ocx-cache-debug-"));
+  process.env.OPENCODEX_HOME = testDir;
+  resetDebugSettingsForTests();
+  resetDebugLogBufferForTests();
+});
+
+afterEach(() => {
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  if (previousDebug === undefined) delete process.env.OPENCODEX_CACHE_DEBUG;
+  else process.env.OPENCODEX_CACHE_DEBUG = previousDebug;
+  resetDebugSettingsForTests();
+  resetDebugLogBufferForTests();
+  if (testDir) removeTreeWithRetry(testDir);
+});
+
+function append(
+  requestId: string,
+  draft = observeInbound({}, new Headers()),
+  cache: { raw?: number; value?: number; provenance?: "observed" | "synthesized" | "unknown" } = {},
+): void {
+  appendFinalCacheDiagnostic({
+    requestId,
+    protocol: "responses",
+    provider: "openai",
+    model: "gpt-test",
+    ...(cache.raw !== undefined ? { rawCacheCounterValue: cache.raw } : {}),
+    ...(cache.value !== undefined ? { normalizedCacheValue: cache.value } : {}),
+    cacheProvenance: cache.provenance ?? "unknown",
+    draft,
+  });
+}
+
+function records(): Array<Record<string, unknown>> {
+  return readFileSync(cacheDiagnosticPath(), "utf8").split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line));
+}
+
+interface DiagnosticRecord {
+  requestId: string;
+  promptCacheKey: { inbound: { present: boolean; source?: string; tag?: string } };
+  session: { inboundHeader: { tag?: string } };
+  prefix: {
+    inbound: { messages: { tags: string[] } };
+    outbound: { messages: { tags: string[] } };
+    firstDivergentBlock?: { section: string; index: number };
+  };
+  cache: {
+    rawUpstream: { present: boolean; value?: number; field?: string };
+    normalized: { present: boolean; value?: number; provenance: string };
+  };
+}
+
+function diagnosticRecords(): DiagnosticRecord[] {
+  return records() as unknown as DiagnosticRecord[];
+}
+
+describe("cache diagnostic", () => {
+  test("is disabled by default", () => {
+    delete process.env.OPENCODEX_CACHE_DEBUG;
+    append("disabled");
+    expect(existsSync(cacheDiagnosticPath())).toBe(false);
+  });
+
+  test("writes only presence, process tags, counts, and bounded metadata", () => {
+    process.env.OPENCODEX_CACHE_DEBUG = "1";
+    const cacheKey = "raw-cache-key-sentinel";
+    const session = "raw-session-sentinel";
+    const prompt = "raw-prompt-sentinel";
+    const inbound = { prompt_cache_key: cacheKey, input: [{ role: "user", content: prompt }] };
+    const draft = observeInbound(inbound, new Headers({ session_id: session }));
+    observeOutbound(inbound, inbound, { session_id: session });
+    append("privacy", draft);
+
+    const text = readFileSync(cacheDiagnosticPath(), "utf8");
+    expect(text).not.toContain(cacheKey);
+    expect(text).not.toContain(session);
+    expect(text).not.toContain(prompt);
+    const record = diagnosticRecords()[0];
+    expect(record.promptCacheKey.inbound).toMatchObject({ present: true, source: "caller" });
+    expect(record.promptCacheKey.inbound.tag).toMatch(/^[0-9a-f]{12}$/);
+    expect(record.session.inboundHeader.tag).toMatch(/^[0-9a-f]{12}$/);
+    expect(record.prefix.inbound.messages.tags[0]).toMatch(/^[0-9a-f]{12}$/);
+    if (process.platform !== "win32") expect(statSync(cacheDiagnosticPath()).mode & 0o777).toBe(0o600);
+  });
+
+  test("fingerprints equal bodies equally and locates the first changed message", () => {
+    process.env.OPENCODEX_CACHE_DEBUG = "1";
+    const first = { input: [{ role: "user", content: "first" }] };
+    const same = { input: [{ role: "user", content: "first" }] };
+    const changed = { input: [{ role: "user", content: "changed" }] };
+    const equalDraft = observeInbound(first, new Headers());
+    observeOutbound(first, same, {});
+    append("equal", equalDraft);
+    const changedDraft = observeInbound(first, new Headers());
+    observeOutbound(first, changed, {});
+    append("changed", changedDraft);
+
+    const [equal, different] = diagnosticRecords();
+    expect(equal.prefix.inbound.messages.tags).toEqual(equal.prefix.outbound.messages.tags);
+    expect(equal.prefix.firstDivergentBlock).toBeUndefined();
+    expect(different.prefix.firstDivergentBlock).toEqual({ section: "messages", index: 0 });
+  });
+
+  test("a rebuilt request body stays bound to the same draft through an alias", () => {
+    process.env.OPENCODEX_CACHE_DEBUG = "1";
+    // The previous-response expansion rebuilds the body object after the inbound
+    // observation; the adapter seam sees only the rebuilt one.
+    const inbound = { input: [{ role: "user", content: "literal-inbound" }] };
+    const rebuilt = { input: [{ role: "user", content: "literal-inbound" }, { role: "user", content: "expanded" }] };
+    const draft = observeInbound(inbound, new Headers());
+    rebindCacheDiagnosticBodyAlias(rebuilt, draft);
+    observeOutbound(rebuilt, rebuilt, {});
+    append("aliased", draft);
+
+    const [record] = diagnosticRecords();
+    expect(record.prefix.inbound.messages.tags).toHaveLength(1);
+    expect(record.prefix.outbound.messages.tags).toHaveLength(2);
+    expect(record.prefix.firstDivergentBlock).toEqual({ section: "messages", index: 1 });
+  });
+
+  test("observation never mutates the live request body", () => {
+    process.env.OPENCODEX_CACHE_DEBUG = "1";
+    // An array-valued instructions field aliases the body's own array in the block
+    // splitter; appending system/developer content into it would rewrite the request
+    // the adapter is about to send upstream.
+    const body = {
+      instructions: ["standing-instruction"],
+      input: [
+        { role: "system", content: "system-note" },
+        { role: "user", content: "hello" },
+      ],
+    };
+    const before = JSON.stringify(body);
+    const draft = observeInbound(body, new Headers());
+    observeOutbound(body, body, {});
+    append("immutability", draft);
+
+    expect(JSON.stringify(body)).toBe(before);
+    const [record] = diagnosticRecords();
+    expect(record.prefix.inbound.messages.tags).toHaveLength(1);
+  });
+
+  test("keeps an observed upstream zero distinct from an absent counter", () => {
+    process.env.OPENCODEX_CACHE_DEBUG = "1";
+    append("zero", observeInbound({}, new Headers()), { raw: 0, value: 0, provenance: "observed" });
+    append("absent", observeInbound({}, new Headers()), { provenance: "unknown" });
+
+    const [zero, absent] = diagnosticRecords();
+    expect(zero.cache.rawUpstream).toEqual({ present: true, value: 0 });
+    expect(zero.cache.normalized).toEqual({ present: true, value: 0, provenance: "observed" });
+    expect(absent.cache.rawUpstream).toEqual({ present: false });
+    expect(absent.cache.normalized).toEqual({ present: false, provenance: "unknown" });
+  });
+
+  test("retains the newest records after crossing the rolling limit", () => {
+    process.env.OPENCODEX_CACHE_DEBUG = "1";
+    for (let index = 0; index <= CACHE_DEBUG_MAX_LINES; index += 1) append(`request-${index}`);
+    const kept = diagnosticRecords();
+    expect(kept).toHaveLength(CACHE_DEBUG_KEEP_LINES);
+    expect(kept[0].requestId).toBe(`request-${CACHE_DEBUG_MAX_LINES + 1 - CACHE_DEBUG_KEEP_LINES}`);
+    expect(kept.at(-1)?.requestId).toBe(`request-${CACHE_DEBUG_MAX_LINES}`);
+  });
+
+  test("uses tags that cannot be joined to affinity-debug output", () => {
+    const value = "same-private-value";
+    setDebugSettings({ debug: true });
+    captureCodexAffinityDiagnostic({
+      inboundHeaders: new Headers({ session_id: value }),
+      outboundHeaders: {},
+      authKind: "pool",
+      accountMode: "pool",
+      fixedAccount: false,
+      credentialSubstituted: false,
+      accountGatedModel: false,
+      wireModelNormalized: false,
+      status: 200,
+    });
+    const line = getDebugLogEntries().at(-1)!.line;
+    const payload = JSON.parse(line.slice("[ocx:codex:affinity] ".length)) as { inbound: Array<{ tag: string }> };
+    expect(tagCacheDiagnosticValue("session_id", value)).toMatch(/^[0-9a-f]{12}$/);
+    expect(tagCacheDiagnosticValue("session_id", value)).not.toBe(payload.inbound[0].tag);
+  });
+});
diff --git a/tests/usage/request-outcome-agreement.test.ts b/tests/usage/request-outcome-agreement.test.ts
new file mode 100644
index 00000000000..7b1b49dbf65
--- /dev/null
+++ b/tests/usage/request-outcome-agreement.test.ts
@@ -0,0 +1,291 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { repoPath } from "../helpers/repo-root";
+import {
+  REQUEST_OUTCOME_CLASSES,
+  REQUEST_CLOSE_REASONS,
+  REQUEST_TERMINAL_STATUSES,
+  classifyRequestOutcome,
+  requestPhysicalSends,
+  requestSettledSends,
+  requestUnresolvedSends,
+  type RequestOutcomeFacts,
+} from "../../src/usage/request-outcome";
+import {
+  REQUEST_METRICS_RESULTS,
+  REQUEST_METRICS_FAILURE_CAUSES,
+  REQUEST_METRICS_PROTOCOLS,
+  createRequestMetricsOwner,
+} from "../../src/server/request-metrics";
+import { ATTEMPT_RECOVERY_KIND_ROSTER } from "../../src/usage/telemetry-contract";
+
+/**
+ * The durable ledger, the Prometheus exporter and the dashboard have to answer "how did this
+ * request end" and "how many times did it reach upstream" the same way. They did not: the
+ * exporter kept a private classifier and the dashboard read the numeric status alone, so an
+ * incomplete 200 was a metric incident and a green row at the same time.
+ *
+ * None of these cases can be satisfied by a request that returned 200 -- several of them are
+ * specifically about a 200 that must NOT read as success.
+ */
+
+const LOCALES = ["en", "ko", "ja", "zh", "zh-TW", "de", "fr", "ru", "tr", "vi"] as const;
+
+function sampleValue(snapshot: string, series: string): number {
+  const line = snapshot.split("\n").find(row => row.startsWith(series + " "));
+  return line === undefined ? Number.NaN : Number(line.slice(series.length + 1));
+}
+
+/**
+ * Every combination a terminal can arrive in, read from the modules that declare them rather
+ * than written out. A restated list is how a member added later leaves this cross product green
+ * without ever being exercised.
+ */
+const TERMINAL_STATUSES = [undefined, ...REQUEST_TERMINAL_STATUSES] as const;
+const CLOSE_REASONS = [undefined, ...REQUEST_CLOSE_REASONS] as const;
+const STATUSES = [101, 200, 204, 399, 400, 429, 499, 500, 502] as const;
+
+describe("terminal classification is stated once", () => {
+  test("the exporter labels every fact exactly as the shared classifier does", () => {
+    const disagreements: string[] = [];
+    for (const status of STATUSES) {
+      for (const terminalStatus of TERMINAL_STATUSES) {
+        for (const closeReason of CLOSE_REASONS) {
+          const facts: RequestOutcomeFacts = {
+            status,
+            ...(terminalStatus ? { terminalStatus } : {}),
+            ...(closeReason ? { closeReason } : {}),
+          };
+          const metrics = createRequestMetricsOwner(1);
+          metrics.recordFinalRequest({
+            protocol: "responses",
+            durationMs: 1,
+            status,
+            ...(terminalStatus ? { terminalStatus } : {}),
+            ...(closeReason ? { closeReason } : {}),
+          });
+          const snapshot = metrics.snapshot();
+          const expected = classifyRequestOutcome(facts);
+          const observed = REQUEST_METRICS_RESULTS.filter(result => sampleValue(
+            snapshot,
+            `opencodex_logical_requests_total{protocol="responses",result="${result}"}`,
+          ) === 1);
+          if (observed.length !== 1 || observed[0] !== expected) {
+            disagreements.push(`${status}/${terminalStatus ?? "-"}/${closeReason ?? "-"}: `
+              + `exporter ${observed.join("+") || "none"} != ${expected}`);
+          }
+        }
+      }
+    }
+    expect(disagreements).toEqual([]);
+  });
+
+  test("the exporter's label set IS the shared vocabulary, not a copy of it", () => {
+    expect(REQUEST_METRICS_RESULTS).toBe(REQUEST_OUTCOME_CLASSES);
+  });
+
+  /**
+   * The three cases the disagreement actually showed up in. Written as literals because each one
+   * is a specific incident shape, not a member of a roster that could grow.
+   */
+  test("a 200 that never delivered an answer does not read as success", () => {
+    expect(classifyRequestOutcome({ status: 200, terminalStatus: "incomplete" })).toBe("incomplete");
+    expect(classifyRequestOutcome({ status: 502, terminalStatus: "incomplete" })).toBe("incomplete");
+    expect(classifyRequestOutcome({ status: 200, closeReason: "client_cancel" })).toBe("aborted");
+    expect(classifyRequestOutcome({ status: 200 })).toBe("completed");
+  });
+
+  test("the dashboard calls the shared classifier instead of reading the status", () => {
+    const page = readFileSync(repoPath("gui", "src", "pages", "Logs.tsx"), "utf8");
+    expect(page).toContain("classifyRequestOutcome");
+    expect(page).toContain("request-outcome");
+  });
+});
+
+describe("send totals agree across surfaces", () => {
+  /**
+   * The budget charged four sends while the attempt rows account for three. Both numbers are
+   * real and they answer different questions, so the surfaces have to agree about WHICH one the
+   * send total is. An earlier draft returned max(sends, reserved) here, which is defensible on
+   * its own and made the dashboard say four while the exporter said three -- two defensible
+   * formulas are still two answers.
+   */
+  const spend = { sends: 3, settled: 3, unresolved: 1, reserved: 4 };
+
+  test("the reported total is the recorded one, with the unexplained part beside it", () => {
+    expect(requestPhysicalSends(spend)).toBe(3);
+    expect(requestSettledSends(spend)).toBe(3);
+    expect(requestUnresolvedSends(spend)).toBe(1);
+  });
+
+  test("the exporter's send total is the number the dashboard shows", () => {
+    const metrics = createRequestMetricsOwner(1);
+    metrics.recordFinalRequest({
+      protocol: "responses",
+      status: 200,
+      durationMs: 1,
+      terminalStatus: "completed",
+      attempts: [
+        { sendCount: 2, recoveryKinds: [] },
+        { sendCount: 1, recoveryKinds: ["connection-reset"] },
+      ],
+      spendSends: spend.sends,
+    });
+    const exported = sampleValue(
+      metrics.snapshot(),
+      'opencodex_physical_sends_total{protocol="responses"}',
+    );
+    expect(exported).toBe(requestPhysicalSends(spend));
+  });
+
+  test("an absent or malformed spend record reports nothing rather than guessing", () => {
+    expect(requestPhysicalSends(undefined)).toBe(0);
+    expect(requestUnresolvedSends(undefined)).toBe(0);
+    expect(requestPhysicalSends({ sends: -2, settled: -1, unresolved: 0 })).toBe(0);
+  });
+
+  test("the dashboard shows the send total and the unresolved remainder", () => {
+    const page = readFileSync(repoPath("gui", "src", "pages", "Logs.tsx"), "utf8");
+    expect(page).toContain("requestPhysicalSends");
+    expect(page).toContain("requestUnresolvedSends");
+  });
+});
+
+describe("the dashboard reaches only browser-safe contract modules", () => {
+  /**
+   * A type-only import still pulls the imported file's whole import graph into the dashboard's
+   * TypeScript project, and that project sets `erasableSyntaxOnly`. Importing these names from
+   * `src/usage/log.ts` dragged `node:fs`, `node:crypto` and the config barrel into the browser
+   * build, where a parameter property fails to compile. The page must reach the leaf instead.
+   */
+  test("it imports the vocabulary from the contract leaf, not the ledger module", () => {
+    const page = readFileSync(repoPath("gui", "src", "pages", "Logs.tsx"), "utf8");
+    expect(page).toContain("src/usage/telemetry-contract");
+    expect(page).not.toContain("src/usage/log");
+  });
+
+  test("the contract leaf has no imports at all", () => {
+    const contract = readFileSync(repoPath("src", "usage", "telemetry-contract.ts"), "utf8");
+    expect(contract.match(/^\s*import\s/gm)).toBeNull();
+  });
+
+  test("the outcome module reaches nothing but the contract", () => {
+    const outcome = readFileSync(repoPath("src", "usage", "request-outcome.ts"), "utf8");
+    const specifiers = [...outcome.matchAll(/from "([^"]+)"/g)].map(match => match[1]!);
+    expect(specifiers).toEqual(["./telemetry-contract"]);
+  });
+});
+
+describe("the dashboard recovery roster cannot drift from the durable one", () => {
+  /**
+   * The defect this replaces: the page declared its own nine-member union while the ledger wrote
+   * thirteen, so four real causes rendered as "Unknown recovery reason". A source oracle rather
+   * than a type check, because the page is compiled by a different project.
+   */
+  test("every durable recovery kind has a dashboard label", () => {
+    const page = readFileSync(repoPath("gui", "src", "pages", "Logs.tsx"), "utf8");
+    const block = page.slice(page.indexOf("const RECOVERY_KIND_KEYS"), page.indexOf("} as const satisfies Record<AttemptRecoveryKind"));
+    const missing = ATTEMPT_RECOVERY_KIND_ROSTER.filter(kind => !block.includes(`"${kind}":`));
+    expect(missing).toEqual([]);
+  });
+
+  test("the page derives the union rather than restating it", () => {
+    const page = readFileSync(repoPath("gui", "src", "pages", "Logs.tsx"), "utf8");
+    // Matched without depending on how the import is wrapped: the property is that the name
+    // arrives from the contract leaf, not that it sits first on a single line.
+    expect(/import type \{[^}]*\bAttemptRecoveryKind\b[^}]*\}\s*from\s*"[^"]*usage\/telemetry-contract"/s.test(page)).toBe(true);
+    expect(page).not.toContain('type AttemptRecoveryKind =');
+  });
+
+  test("every label key the page names exists in all ten catalogs", () => {
+    const page = readFileSync(repoPath("gui", "src", "pages", "Logs.tsx"), "utf8");
+    const keys = [...new Set([...page.matchAll(/"(logs\.detail\.(?:attempt\.recovery|outcome|sends|cause|stage|resend)\.[a-zA-Z0-9]+)"/g)]
+      .map(match => match[1]!))];
+    expect(keys.length).toBeGreaterThan(ATTEMPT_RECOVERY_KIND_ROSTER.length);
+    const gaps: string[] = [];
+    for (const locale of LOCALES) {
+      const catalog = readFileSync(repoPath("gui", "src", "i18n", `${locale}.ts`), "utf8");
+      for (const key of keys) if (!catalog.includes(`"${key}"`)) gaps.push(`${locale}:${key}`);
+    }
+    expect(gaps).toEqual([]);
+  });
+});
+
+describe("the exporter stays bounded", () => {
+  test("no series carries a user, model, account or request identifier", () => {
+    const metrics = createRequestMetricsOwner(1);
+    for (let index = 0; index < 32; index += 1) {
+      metrics.recordFinalRequest({
+        protocol: "responses", status: 200, durationMs: 5, terminalStatus: "completed",
+        attempts: [{ sendCount: 1, recoveryKinds: ["rate-limit-429"] }],
+      });
+    }
+    const snapshot = metrics.snapshot();
+    const labels = [...new Set([...snapshot.matchAll(/([a-z_]+)="/g)].map(match => match[1]!))];
+    expect(labels.sort()).toEqual(["cause", "le", "protocol", "recovery", "result"]);
+  });
+
+  /**
+   * The cause label is a counter label and never a histogram one. Fifteen causes across four
+   * protocols is a fixed sixty series; the same label on a histogram would multiply that by the
+   * bucket count to answer a question nobody asked.
+   */
+  test("the failure cause labels a counter and no histogram", () => {
+    const snapshot = createRequestMetricsOwner(1).snapshot();
+    const causeLines = snapshot.split("\n").filter(line => line.includes('cause="'));
+    expect(causeLines.length).toBe(
+      REQUEST_METRICS_PROTOCOLS.length * REQUEST_METRICS_FAILURE_CAUSES.length,
+    );
+    expect(causeLines.every(line => line.startsWith("opencodex_request_failures_total{"))).toBe(true);
+    expect(causeLines.some(line => line.includes("_bucket") || line.includes("le="))).toBe(false);
+  });
+});
+
+describe("the failure cause is derived once and reported everywhere", () => {
+  /**
+   * The recorder derives the cause; the exporter counts the value it was handed. Two derivations
+   * of one answer is the disagreement this batch exists to remove, so this asserts the exporter
+   * has no opinion of its own -- a fact carrying a cause the status alone would classify
+   * differently is still counted under the cause it was given.
+   */
+  test("the exporter counts the recorder's cause rather than re-deriving one", () => {
+    for (const cause of REQUEST_METRICS_FAILURE_CAUSES) {
+      const metrics = createRequestMetricsOwner(1);
+      metrics.recordFinalRequest({
+        protocol: "responses", status: 200, durationMs: 1, terminalStatus: "failed", failureCause: cause,
+      });
+      const snapshot = metrics.snapshot();
+      expect(sampleValue(snapshot, `opencodex_request_failures_total{protocol="responses",cause="${cause}"}`)).toBe(1);
+    }
+  });
+
+  test("a request that delivered its answer contributes to no cause series", () => {
+    const metrics = createRequestMetricsOwner(1);
+    metrics.recordFinalRequest({ protocol: "responses", status: 200, durationMs: 1, terminalStatus: "completed" });
+    const snapshot = metrics.snapshot();
+    for (const cause of REQUEST_METRICS_FAILURE_CAUSES) {
+      expect(sampleValue(snapshot, `opencodex_request_failures_total{protocol="responses",cause="${cause}"}`)).toBe(0);
+    }
+  });
+
+  test("every cause the recorder can derive has a dashboard label", () => {
+    const page = readFileSync(repoPath("gui", "src", "pages", "Logs.tsx"), "utf8");
+    const block = page.slice(page.indexOf("const FAILURE_CAUSE_KEYS"), page.indexOf("} as const satisfies Record<RequestFailureCause"));
+    const missing = REQUEST_METRICS_FAILURE_CAUSES.filter(cause => !block.includes(`"${cause}":`));
+    expect(missing).toEqual([]);
+  });
+
+  /**
+   * The verdict is computed at read time and must not appear in a durable shape. A row written
+   * by an older build would otherwise assert a permission the current tables refuse, and there
+   * would be no way to correct it.
+   */
+  test("the resend verdict is never persisted", () => {
+    const ledger = readFileSync(repoPath("src", "usage", "log.ts"), "utf8");
+    expect(ledger).toContain("failureStage");
+    expect(ledger).toContain("failureCause");
+    expect(ledger).not.toContain("resendPermission");
+    const dto = readFileSync(repoPath("src", "server", "management", "shared.ts"), "utf8");
+    expect(dto).toContain("resendPermission");
+  });
+});
diff --git a/tests/usage/usage-attempt-delivery.test.ts b/tests/usage/usage-attempt-delivery.test.ts
new file mode 100644
index 00000000000..f5681baf7a2
--- /dev/null
+++ b/tests/usage/usage-attempt-delivery.test.ts
@@ -0,0 +1,161 @@
+import { describe, expect, test } from "bun:test";
+import {
+  attemptDeliveryRecorder,
+  bindAttemptDeliveryRecorder,
+  classifyRelayedResponseEvent,
+  createAttemptDeliverySummary,
+  normalizeAttemptDeliverySummary,
+  type AttemptDeliveryTarget,
+} from "../../src/usage/attempt-delivery";
+import { normalizeUsageEntryForTest, type PersistedUsageEntry } from "../../src/usage/log";
+
+const COUNTERS = Object.keys(createAttemptDeliverySummary());
+
+describe("attempt delivery summary", () => {
+  test("the recorder credits the attempt that is live when the event arrives", () => {
+    let active: AttemptDeliveryTarget | undefined = {};
+    const first = active;
+    const scope = {};
+    const recorder = bindAttemptDeliveryRecorder(scope, () => active);
+    recorder.noteAdapterEvent();
+    recorder.noteRelayedEvent({ semanticBytes: 4, terminal: true });
+
+    // A key-account change seals the attempt and starts a fresh one mid-request. A recorder
+    // holding a reference would keep crediting the sealed row.
+    const second: AttemptDeliveryTarget = {};
+    active = second;
+    recorder.noteAdapterEvent();
+
+    expect(first.deliverySummary).toEqual({
+      adapterEvents: 1, relayedEvents: 1, semanticBytes: 4, sideEffectEvents: 0, terminalEvents: 1,
+    });
+    expect(second.deliverySummary).toEqual({
+      adapterEvents: 1, relayedEvents: 0, semanticBytes: 0, sideEffectEvents: 0, terminalEvents: 0,
+    });
+  });
+
+  test("a scope with no attempt records nothing and does not throw", () => {
+    const scope = {};
+    const recorder = bindAttemptDeliveryRecorder(scope, () => undefined);
+    expect(() => { recorder.noteAdapterEvent(); recorder.noteRelayedEvent(); }).not.toThrow();
+    expect(attemptDeliveryRecorder(scope)).toBe(recorder);
+    expect(attemptDeliveryRecorder(undefined)).toBeUndefined();
+    expect(attemptDeliveryRecorder({})).toBeUndefined();
+  });
+
+  test("semantic bytes count delivered UTF-8, never the text itself", () => {
+    const observation = classifyRelayedResponseEvent("response.output_text.delta", { delta: "한글" });
+    expect(observation.semanticBytes).toBe(6);
+    expect(JSON.stringify(observation)).not.toContain("한글");
+  });
+
+  test("one tool call is one side effect, whatever carried its arguments", () => {
+    const target: AttemptDeliveryTarget = {};
+    const recorder = bindAttemptDeliveryRecorder({}, () => target);
+    recorder.noteRelayedEvent(classifyRelayedResponseEvent("response.output_item.added", {
+      item: { type: "function_call", name: "lookup" },
+    }));
+    recorder.noteRelayedEvent(classifyRelayedResponseEvent("response.function_call_arguments.delta", { delta: "{}" }));
+    recorder.noteRelayedEvent(classifyRelayedResponseEvent("response.output_item.done", {
+      item: { type: "function_call", name: "lookup" },
+    }));
+    expect(target.deliverySummary!.sideEffectEvents).toBe(1);
+    expect(target.deliverySummary!.relayedEvents).toBe(3);
+  });
+
+  test("framing and control frames are relayed events but not semantic or terminal ones", () => {
+    for (const name of ["response.created", "response.heartbeat", "response.output_item.done"]) {
+      const observation = classifyRelayedResponseEvent(name, {});
+      expect(observation.semanticBytes).toBeUndefined();
+      expect(observation.terminal).toBeUndefined();
+      expect(observation.sideEffect).toBeUndefined();
+    }
+    for (const name of ["response.completed", "response.incomplete", "response.failed"]) {
+      expect(classifyRelayedResponseEvent(name, {}).terminal).toBe(true);
+    }
+  });
+
+  test("a summary survives the ledger round trip and an invalid one is dropped whole", () => {
+    const row = (deliverySummary: unknown): PersistedUsageEntry => ({
+      requestId: "req", timestamp: 1, provider: "openai", model: "m", status: 200,
+      durationMs: 1, usageStatus: "unreported",
+      attempts: [{
+        ordinal: 1, provider: "openai", model: "m", adapter: "openai", status: 200,
+        durationMs: 1, sendCount: 1, recoveryKinds: [], usageStatus: "unreported",
+        deliverySummary,
+      } as never],
+    });
+    const good = { adapterEvents: 5, relayedEvents: 4, semanticBytes: 12, sideEffectEvents: 1, terminalEvents: 1 };
+    expect(normalizeUsageEntryForTest(row(good)).attempts![0]!.deliverySummary).toEqual(good);
+
+    // Half a summary is how a loss signal becomes a false one, so a bad count drops all five.
+    for (const broken of [
+      { ...good, relayedEvents: -1 },
+      { ...good, semanticBytes: 1.5 },
+      { ...good, terminalEvents: "1" },
+      { adapterEvents: 1 },
+      null,
+      [],
+    ]) {
+      expect(normalizeUsageEntryForTest(row(broken)).attempts![0]!.deliverySummary).toBeUndefined();
+    }
+    // An attempt written before the field existed still reads back.
+    const legacy = normalizeUsageEntryForTest(row(undefined));
+    expect(legacy.attempts![0]!.deliverySummary).toBeUndefined();
+    expect(legacy.attempts![0]!.ordinal).toBe(1);
+  });
+
+  test("the normalizer requires every declared counter, so a new one cannot be forgotten", () => {
+    const complete = createAttemptDeliverySummary();
+    expect(normalizeAttemptDeliverySummary(complete)).toEqual(complete);
+    for (const key of COUNTERS) {
+      const missing: Record<string, number> = { ...complete };
+      delete missing[key];
+      expect(normalizeAttemptDeliverySummary(missing)).toBeUndefined();
+    }
+  });
+
+  test("the summary carries counts only, so no content can ride it", () => {
+    const target: AttemptDeliveryTarget = {};
+    const recorder = bindAttemptDeliveryRecorder({}, () => target);
+    recorder.noteRelayedEvent(classifyRelayedResponseEvent("response.output_text.delta", {
+      delta: "the user's private prompt",
+    }));
+    const serialized = JSON.stringify(target.deliverySummary);
+    expect(serialized).not.toContain("private");
+    expect(Object.values(target.deliverySummary!).every(value => typeof value === "number")).toBe(true);
+  });
+
+  test("a buffered response does not read as total relay loss", () => {
+    const target: AttemptDeliveryTarget = {};
+    const recorder = bindAttemptDeliveryRecorder({}, () => target);
+    for (let index = 0; index < 4; index += 1) recorder.noteAdapterEvent();
+    // Nothing calls the per-frame recorder on a non-streaming turn: the whole answer arrives as
+    // one body. Left at zero, every buffered request would raise the adapter-to-client loss
+    // signal these counters exist for.
+    recorder.noteBufferedDelivery({
+      output: [
+        { type: "message", content: [{ type: "output_text", text: "hello" }] },
+        { type: "function_call", name: "lookup", arguments: "{}" },
+      ],
+    });
+    expect(target.deliverySummary).toEqual({
+      adapterEvents: 4,
+      relayedEvents: 4,
+      semanticBytes: 7,
+      sideEffectEvents: 1,
+      terminalEvents: 1,
+    });
+  });
+
+  test("a buffered body contributes counts and never its text", () => {
+    const target: AttemptDeliveryTarget = {};
+    const recorder = bindAttemptDeliveryRecorder({}, () => target);
+    recorder.noteAdapterEvent();
+    recorder.noteBufferedDelivery({
+      output: [{ type: "message", content: [{ type: "output_text", text: "a private answer" }] }],
+    });
+    expect(JSON.stringify(target.deliverySummary)).not.toContain("private");
+    expect(target.deliverySummary!.semanticBytes).toBe(16);
+  });
+});
diff --git a/tests/usage/usage-cost.test.ts b/tests/usage/usage-cost.test.ts
index dffe93f2ab2..5381aff5f7a 100644
--- a/tests/usage/usage-cost.test.ts
+++ b/tests/usage/usage-cost.test.ts
@@ -328,8 +328,8 @@ describe("resolveMatchedPrice", () => {
     expect(resolveMatchedPrice("openrouter", "anthropic-claude-3.5-sonnet")).toBeNull();
   });
 
-  test("16. shipped overlay membership: 126 keys, including canonical Fable 5.1, Opus 5, OpenCode Go and compatibility prices", () => {
-    expect(EXPECTED_PRICE_OVERLAYS.length).toBe(126);
+  test("16. shipped overlay membership: 128 keys, including canonical Fable 5.1, Opus 5, OpenCode Go and compatibility prices", () => {
+    expect(EXPECTED_PRICE_OVERLAYS.length).toBe(128);
     expect(EXPECTED_PRICE_OVERLAYS.some(row => row.status === "unverified")).toBe(false);
     const keys = new Set(EXPECTED_PRICE_OVERLAYS.map(row => `${row.provider}/${row.modelId}`));
     for (const expected of [
diff --git a/tests/usage/usage-failure-fingerprint.test.ts b/tests/usage/usage-failure-fingerprint.test.ts
new file mode 100644
index 00000000000..ce081ce7034
--- /dev/null
+++ b/tests/usage/usage-failure-fingerprint.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, test } from "bun:test";
+import {
+  FAILURE_FINGERPRINT_VERSION,
+  FAILURE_STATUS_CLASSES,
+  canonicalFailureFingerprintTuple,
+  computeFailureFingerprint,
+  failureStatusClass,
+  type FailureFingerprintFacts,
+} from "../../src/usage/failure-fingerprint";
+import { REQUEST_FAILURE_CAUSES } from "../../src/lib/request-failure-model";
+import { REQUEST_CLOSE_REASONS, REQUEST_TERMINAL_STATUSES } from "../../src/usage/request-outcome";
+
+/**
+ * A fingerprint that can carry content is not privacy-safe, and one that collides is not a
+ * grouping key. Both properties are asserted structurally rather than by example, so a slot
+ * added later has to be given a position instead of quietly joining an existing one.
+ */
+const BASE: FailureFingerprintFacts = {
+  cause: "upstream-fault",
+  statusClass: "5xx",
+  providerClass: null,
+  inboundProtocol: null,
+  terminalStatus: null,
+  closeReason: null,
+  transportPhase: null,
+  terminalSource: null,
+};
+
+/** Every slot, with a value that differs from BASE, read from the roster that declares it. */
+const VARIATIONS: ReadonlyArray<[keyof FailureFingerprintFacts, unknown]> = [
+  ["cause", REQUEST_FAILURE_CAUSES.find(cause => cause !== BASE.cause)!],
+  ["statusClass", FAILURE_STATUS_CLASSES.find(value => value !== BASE.statusClass)!],
+  ["providerClass", "openai"],
+  ["inboundProtocol", "responses"],
+  ["terminalStatus", REQUEST_TERMINAL_STATUSES[0]!],
+  ["closeReason", REQUEST_CLOSE_REASONS[0]!],
+  ["transportPhase", "mid_stream"],
+  ["terminalSource", "upstream"],
+];
+
+describe("failure fingerprint", () => {
+  test("it is deterministic and carries its version in the value", () => {
+    const first = computeFailureFingerprint(BASE);
+    expect(computeFailureFingerprint({ ...BASE })).toBe(first);
+    // The version is imported, never written out: a bump must not be contradicted here.
+    expect(first.startsWith(`v${FAILURE_FINGERPRINT_VERSION}:`)).toBe(true);
+  });
+
+  test("every tuple position changes the fingerprint", () => {
+    const base = computeFailureFingerprint(BASE);
+    const unchanged: string[] = [];
+    for (const [key, value] of VARIATIONS) {
+      const varied = computeFailureFingerprint({ ...BASE, [key]: value } as FailureFingerprintFacts);
+      if (varied === base) unchanged.push(String(key));
+    }
+    expect(unchanged).toEqual([]);
+  });
+
+  test("the tuple has one fixed position per declared fact plus the version", () => {
+    const tuple = canonicalFailureFingerprintTuple(BASE);
+    expect(tuple.length).toBe(Object.keys(BASE).length + 1);
+    expect(tuple[0]).toBe(FAILURE_FINGERPRINT_VERSION);
+    // Absent facts are explicit nulls. Dropping them would let [a, null, b] and [a, b] collide.
+    expect(tuple.slice(3).every(slot => slot === null)).toBe(true);
+  });
+
+  test("a missing fact is structurally distinct from a present one that looks like it", () => {
+    const absent = computeFailureFingerprint(BASE);
+    const present = computeFailureFingerprint({ ...BASE, providerClass: "null" });
+    expect(present).not.toBe(absent);
+  });
+
+  test("a field outside the declared facts cannot reach the identity", () => {
+    const withExtras = {
+      ...BASE,
+      provider: "cursor-alice@example.com",
+      model: "secret-model",
+      upstreamError: "prompt fragment",
+      requestId: "req_1",
+      timestamp: 1,
+    } as FailureFingerprintFacts;
+    expect(computeFailureFingerprint(withExtras)).toBe(computeFailureFingerprint(BASE));
+    expect(JSON.stringify(canonicalFailureFingerprintTuple(withExtras))).not.toContain("example.com");
+  });
+
+  test("the status class covers every hundred and refuses anything else", () => {
+    expect(failureStatusClass(101)).toBe("1xx");
+    expect(failureStatusClass(204)).toBe("2xx");
+    expect(failureStatusClass(302)).toBe("3xx");
+    expect(failureStatusClass(429)).toBe("4xx");
+    expect(failureStatusClass(503)).toBe("5xx");
+    for (const value of [undefined, null, 0, 99, 600, 1.5, Number.NaN, "500"]) {
+      expect(failureStatusClass(value)).toBe("unknown");
+    }
+  });
+
+  test("every cause the recorder can store produces a distinct fingerprint", () => {
+    const seen = new Map<string, string>();
+    for (const cause of REQUEST_FAILURE_CAUSES) {
+      const fingerprint = computeFailureFingerprint({ ...BASE, cause });
+      expect(seen.has(fingerprint)).toBe(false);
+      seen.set(fingerprint, cause);
+    }
+    expect(seen.size).toBe(REQUEST_FAILURE_CAUSES.length);
+  });
+});
diff --git a/tests/usage/usage-failure-projection.test.ts b/tests/usage/usage-failure-projection.test.ts
new file mode 100644
index 00000000000..479ab3962c0
--- /dev/null
+++ b/tests/usage/usage-failure-projection.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createFailureProjectionAccumulator,
+  failureProviderClass,
+} from "../../src/usage/failure-projection";
+import { FAILURE_FINGERPRINT_VERSION } from "../../src/usage/failure-fingerprint";
+import { REQUEST_FAILURE_CAUSES } from "../../src/lib/request-failure-model";
+import type { PersistedUsageEntry } from "../../src/usage/log";
+
+function row(overrides: Partial<PersistedUsageEntry>): PersistedUsageEntry {
+  return {
+    requestId: "req",
+    timestamp: 1_000,
+    provider: "openai",
+    model: "gpt-x",
+    status: 502,
+    durationMs: 1,
+    usageStatus: "unreported",
+    failureCause: "upstream-fault",
+    ...overrides,
+  };
+}
+
+describe("failure projection", () => {
+  test("it groups failures that share every closed fact and separates the rest", () => {
+    const accumulator = createFailureProjectionAccumulator();
+    accumulator.add(row({ timestamp: 30 }));
+    accumulator.add(row({ timestamp: 10, requestId: "req2", model: "another-model" }));
+    accumulator.add(row({ timestamp: 20, requestId: "req3", failureCause: "rate-limit", status: 429 }));
+    const snapshot = accumulator.snapshot();
+
+    expect(snapshot.groups.length).toBe(2);
+    const fault = snapshot.groups.find(group => group.cause === "upstream-fault")!;
+    // Two rows that differ only in fields the fingerprint cannot read are one group.
+    expect(fault.count).toBe(2);
+    expect(fault.firstSeen).toBe(10);
+    expect(fault.lastSeen).toBe(30);
+    expect(snapshot.fingerprintVersion).toBe(FAILURE_FINGERPRINT_VERSION);
+  });
+
+  test("first and last seen are a minimum and a maximum, not a scan order", () => {
+    const accumulator = createFailureProjectionAccumulator();
+    for (const timestamp of [50, 10, 90, 30]) accumulator.add(row({ timestamp }));
+    const [group] = accumulator.snapshot().groups;
+    expect(group!.firstSeen).toBe(10);
+    expect(group!.lastSeen).toBe(90);
+    expect(group!.count).toBe(4);
+  });
+
+  test("a snapshot holds a count and two timestamps, never an occurrence list", () => {
+    const accumulator = createFailureProjectionAccumulator();
+    for (const timestamp of [1, 2, 3]) accumulator.add(row({ timestamp }));
+    const [group] = accumulator.snapshot().groups;
+    expect(Object.keys(group!).toSorted()).toEqual([
+      "cause", "closeReason", "count", "fingerprint", "firstSeen", "inboundProtocol",
+      "lastSeen", "providerClass", "statusClass", "terminalSource", "terminalStatus", "transportPhase",
+    ]);
+  });
+
+  test("a request that delivered its answer is not a failure", () => {
+    const accumulator = createFailureProjectionAccumulator();
+    accumulator.add(row({ status: 200, terminalStatus: "completed", failureCause: undefined }));
+    accumulator.add(row({ status: 200, terminalStatus: "incomplete", failureCause: undefined }));
+    const snapshot = accumulator.snapshot();
+    expect(snapshot.groups).toEqual([]);
+    expect(snapshot.unattributedFailures).toBe(0);
+  });
+
+  test("a failed row written before the cause existed is counted, not bucketed", () => {
+    const accumulator = createFailureProjectionAccumulator();
+    accumulator.add(row({ failureCause: undefined }));
+    const snapshot = accumulator.snapshot();
+    expect(snapshot.groups).toEqual([]);
+    expect(snapshot.unattributedFailures).toBe(1);
+  });
+
+  test("a row that cannot be dated does not invent a timestamp", () => {
+    const accumulator = createFailureProjectionAccumulator();
+    accumulator.add(row({ timestamp: Number.NaN }));
+    const snapshot = accumulator.snapshot();
+    expect(snapshot.groups).toEqual([]);
+    expect(snapshot.invalidTimestampFailures).toBe(1);
+  });
+
+  test("an upstream-supplied terminal status cannot reach a grouping key", () => {
+    const accumulator = createFailureProjectionAccumulator();
+    accumulator.add(row({ terminalStatus: "prompt text from upstream" as never }));
+    const [group] = accumulator.snapshot().groups;
+    expect(group!.terminalStatus).toBeNull();
+    expect(JSON.stringify(accumulator.snapshot())).not.toContain("prompt text");
+  });
+
+  test("a provider the user named themselves does not enter the key", () => {
+    expect(failureProviderClass("openai")).toBe("openai");
+    expect(failureProviderClass("my-private-endpoint")).toBeNull();
+    const accumulator = createFailureProjectionAccumulator();
+    accumulator.add(row({ provider: "alice-personal-key" }));
+    expect(JSON.stringify(accumulator.snapshot())).not.toContain("alice");
+  });
+
+  test("a clone folds new rows without touching the accumulator it came from", () => {
+    const original = createFailureProjectionAccumulator();
+    original.add(row({ timestamp: 10 }));
+    const candidate = original.clone();
+    candidate.add(row({ timestamp: 20 }));
+    expect(original.snapshot().groups[0]!.count).toBe(1);
+    expect(candidate.snapshot().groups[0]!.count).toBe(2);
+    expect(original.snapshot().groups[0]!.lastSeen).toBe(10);
+  });
+
+  test("ordering is by recency then fingerprint, so two runs agree", () => {
+    const build = () => {
+      const accumulator = createFailureProjectionAccumulator();
+      for (const [index, cause] of REQUEST_FAILURE_CAUSES.entries()) {
+        accumulator.add(row({ timestamp: 1_000 - (index % 3), failureCause: cause }));
+      }
+      return accumulator.snapshot().groups.map(group => group.fingerprint);
+    };
+    expect(build()).toEqual(build());
+    const accumulator = createFailureProjectionAccumulator();
+    accumulator.add(row({ timestamp: 10, failureCause: "rate-limit" }));
+    accumulator.add(row({ timestamp: 90, failureCause: "upstream-fault" }));
+    expect(accumulator.snapshot().groups[0]!.cause).toBe("upstream-fault");
+  });
+});
diff --git a/tests/usage/usage-ledger-retention.test.ts b/tests/usage/usage-ledger-retention.test.ts
new file mode 100644
index 00000000000..35363e13853
--- /dev/null
+++ b/tests/usage/usage-ledger-retention.test.ts
@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { appendFileSync, mkdirSync, mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { enforceUsageLedgerSizeLimit } from "../../src/usage/ledger-retention";
+import {
+  MIN_USAGE_LEDGER_MAX_BYTES,
+  USAGE_LEDGER_RETENTION_TARGET_RATIO,
+} from "../../src/usage/retention-contract";
+import { usageLogPath } from "../../src/usage/log";
+
+let home: string;
+let previousHome: string | undefined;
+
+/** Rows of a known size, each carrying a field no normalizer in this build knows about. */
+function writeRows(count: number, padding: number): string[] {
+  const path = usageLogPath();
+  mkdirSync(dirname(path), { recursive: true });
+  const lines = Array.from({ length: count }, (_, index) => JSON.stringify({
+    requestId: `req-${index}`,
+    aFieldThisBuildDoesNotKnow: "x".repeat(padding),
+  }));
+  writeFileSync(path, lines.map(line => `${line}\n`).join(""), { encoding: "utf-8", mode: 0o600 });
+  return lines;
+}
+
+beforeEach(() => {
+  previousHome = process.env.OPENCODEX_HOME;
+  home = mkdtempSync(join(tmpdir(), "ocx-ledger-retention-"));
+  process.env.OPENCODEX_HOME = home;
+});
+
+afterEach(() => {
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  removeTreeWithRetry(home);
+});
+
+describe("usage ledger retention", () => {
+  test("no limit, a limit below the floor, and a ledger under the limit leave the file alone", () => {
+    writeRows(20, 64);
+    const before = readFileSync(usageLogPath(), "utf-8");
+    expect(enforceUsageLedgerSizeLimit(undefined).kind).toBe("disabled");
+    expect(enforceUsageLedgerSizeLimit(MIN_USAGE_LEDGER_MAX_BYTES - 1).kind).toBe("disabled");
+    expect(enforceUsageLedgerSizeLimit(MIN_USAGE_LEDGER_MAX_BYTES).kind).toBe("unchanged");
+    expect(readFileSync(usageLogPath(), "utf-8")).toBe(before);
+  });
+
+  test("it keeps the newest whole rows, byte for byte, including fields it does not understand", () => {
+    const lines = writeRows(200, 16 * 1024);
+    const originalBytes = statSync(usageLogPath()).size;
+    expect(enforceUsageLedgerSizeLimit(MIN_USAGE_LEDGER_MAX_BYTES).kind).toBe("replaced");
+
+    const after = readFileSync(usageLogPath(), "utf-8");
+    const retained = after.split("\n").filter(line => line !== "");
+    expect(retained.length).toBeGreaterThan(0);
+    expect(retained.length).toBeLessThan(lines.length);
+    // Identical to the tail they came from: rows are copied, never parsed and rewritten, which
+    // is what keeps a field this build has never heard of intact through a compaction.
+    expect(retained).toEqual(lines.slice(lines.length - retained.length));
+    expect(after).toContain("aFieldThisBuildDoesNotKnow");
+    expect(after.endsWith("\n")).toBe(true);
+    const size = statSync(usageLogPath()).size;
+    expect(size).toBeLessThan(originalBytes);
+    expect(size).toBeLessThanOrEqual(
+      Math.floor(MIN_USAGE_LEDGER_MAX_BYTES * USAGE_LEDGER_RETENTION_TARGET_RATIO),
+    );
+  });
+
+  test("an unterminated final row is carried as-is and never promoted", () => {
+    writeRows(200, 16 * 1024);
+    const torn = JSON.stringify({ requestId: "torn" }).slice(0, 12);
+    appendFileSync(usageLogPath(), torn);
+    expect(enforceUsageLedgerSizeLimit(MIN_USAGE_LEDGER_MAX_BYTES).kind).toBe("replaced");
+    const lines = readFileSync(usageLogPath(), "utf-8").split("\n");
+    // No LF was invented to make it committed: the scanner's definition is unchanged here.
+    expect(lines.at(-1)).toBe(torn);
+    for (const line of lines.slice(0, -1)) {
+      if (line !== "") expect(() => JSON.parse(line) as unknown).not.toThrow();
+    }
+  });
+
+  test("one row larger than the whole target defers instead of emptying the ledger", () => {
+    writeRows(1, MIN_USAGE_LEDGER_MAX_BYTES * 2);
+    const before = readFileSync(usageLogPath(), "utf-8");
+    const result = enforceUsageLedgerSizeLimit(MIN_USAGE_LEDGER_MAX_BYTES);
+    expect(result.kind).toBe("deferred");
+    expect(result).toMatchObject({ reason: "no-boundary" });
+    expect(readFileSync(usageLogPath(), "utf-8")).toBe(before);
+  });
+
+  test("a row appended while the retained span is copied aborts the replacement", () => {
+    const lines = writeRows(200, 16 * 1024);
+    const raced = JSON.stringify({ requestId: "appended-during-copy" });
+    const result = enforceUsageLedgerSizeLimit(MIN_USAGE_LEDGER_MAX_BYTES, {
+      onSpanCopied: () => appendFileSync(usageLogPath(), `${raced}\n`),
+    });
+
+    // This is the defect the revision contract exists to close. #5063 captured a size, copied a
+    // suffix and renamed over whatever was there, so this row was silently lost.
+    expect(result.kind).toBe("deferred");
+    expect(result).toMatchObject({ reason: "revision-changed" });
+    const after = readFileSync(usageLogPath(), "utf-8");
+    expect(after).toContain("appended-during-copy");
+    // Nothing was trimmed either: the original file is exactly as it was, plus the new row.
+    expect(after.split("\n").filter(line => line !== "").length).toBe(lines.length + 1);
+  });
+
+  test("the published file keeps owner-only permissions", () => {
+    if (process.platform === "win32") return;
+    writeRows(200, 16 * 1024);
+    expect(enforceUsageLedgerSizeLimit(MIN_USAGE_LEDGER_MAX_BYTES).kind).toBe("replaced");
+    expect(statSync(usageLogPath()).mode & 0o777).toBe(0o600);
+  });
+});
diff --git a/tests/usage/usage-timeline.test.ts b/tests/usage/usage-timeline.test.ts
new file mode 100644
index 00000000000..ee395007e1e
--- /dev/null
+++ b/tests/usage/usage-timeline.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import type { PersistedUsageEntry } from "../../src/usage/log";
+import { createTimelineAccumulator, parseTimelineQuery } from "../../src/usage/timeline";
+
+const now = 1_700_000_000_000;
+function entry(overrides: Partial<PersistedUsageEntry> = {}): PersistedUsageEntry {
+  return {
+    requestId: "request",
+    timestamp: now - 30 * 60_000,
+    provider: "openai",
+    model: "gpt-5",
+    status: 200,
+    durationMs: 1,
+    usageStatus: "reported",
+    ...overrides,
+  };
+}
+function attempt(totalTokens: number, ordinal: number): NonNullable<PersistedUsageEntry["attempts"]>[number] {
+  return {
+    ordinal,
+    provider: "openai",
+    model: "gpt-5",
+    adapter: "test",
+    status: 200,
+    durationMs: 1,
+    sendCount: 1,
+    recoveryKinds: [],
+    usageStatus: "reported",
+    totalTokens,
+  };
+}
+
+describe("usage timeline", () => {
+  test("parses defaults and rejects invalid values", () => {
+    expect(parseTimelineQuery(new URLSearchParams(), now)).toMatchObject({
+      hours: 24, bucketMinutes: 60, metric: "total", aggregation: "sum", grouping: "model", models: null,
+    });
+    expect(parseTimelineQuery(new URLSearchParams("hours=7"), now)).toEqual({ error: expect.any(String) });
+    expect(parseTimelineQuery(new URLSearchParams("bucketMinutes=0"), now)).toEqual({ error: expect.any(String) });
+    expect(parseTimelineQuery(new URLSearchParams("metric=nope"), now)).toEqual({ error: expect.any(String) });
+    expect(parseTimelineQuery(new URLSearchParams("models=openai%2Fgpt-5%2Cbad"), now)).toEqual({ error: expect.any(String) });
+  });
+
+  test("buckets timestamps and attributes attempts without parent double counting", () => {
+    const query = parseTimelineQuery(new URLSearchParams("hours=6&bucketMinutes=60"), now);
+    if ("error" in query) throw new Error(query.error);
+    const acc = createTimelineAccumulator(query);
+    acc.add(entry({
+      requestId: "retry",
+      totalTokens: 999,
+      attempts: [
+        attempt(10, 0),
+        attempt(20, 1),
+      ],
+    }));
+    const result = acc.finish();
+    expect(result.series[0]?.total).toBe(30);
+    expect(result.buckets).toBe(6);
+  });
+
+  test("supports request average and max", () => {
+    const make = (aggregation: "sum" | "average" | "max") => {
+      const query = parseTimelineQuery(new URLSearchParams(`hours=6&aggregation=${aggregation}`), now);
+      if ("error" in query) throw new Error(query.error);
+      const acc = createTimelineAccumulator(query);
+      acc.add(entry({ requestId: "a", totalTokens: 10 }));
+      acc.add(entry({ requestId: "b", totalTokens: 30 }));
+      return acc.finish().series[0]?.total;
+    };
+    expect(make("sum")).toBe(40);
+    expect(make("average")).toBe(20);
+    expect(make("max")).toBe(30);
+  });
+
+  test("filters plotted models but keeps available models and supports accounts", () => {
+    const query = parseTimelineQuery(new URLSearchParams("models=openai%2Fone&grouping=modelAccount"), now);
+    if ("error" in query) throw new Error(query.error);
+    const acc = createTimelineAccumulator(query);
+    acc.add(entry({ model: "one", accountLogLabel: "main", totalTokens: 4 }));
+    acc.add(entry({ model: "two", totalTokens: 8 }));
+    const result = acc.finish();
+    expect(result.availableModels).toEqual(["openai/one", "openai/two"]);
+    expect(result.series[0]?.id).toBe("openai/one · main");
+  });
+
+  test("counts missing measurements and folds excess series", () => {
+    const query = parseTimelineQuery(new URLSearchParams("hours=6&metric=input"), now);
+    if ("error" in query) throw new Error(query.error);
+    const acc = createTimelineAccumulator(query);
+    acc.add(entry({ usage: undefined, totalTokens: 1 }));
+    for (let index = 0; index < 25; index += 1) {
+      acc.add(entry({ model: `model-${index}`, usage: { inputTokens: index } }));
+    }
+    const result = acc.finish();
+    expect(result.missingMeasurements).toBe(1);
+    expect(result.series).toHaveLength(24);
+    expect(result.series.at(-1)?.id).toBe("other");
+  });
+
+  test("folds other rows with request-level max and average", () => {
+    const make = (aggregation: "average" | "max") => {
+      const query = parseTimelineQuery(new URLSearchParams(`hours=6&aggregation=${aggregation}`), now);
+      if ("error" in query) throw new Error(query.error);
+      const acc = createTimelineAccumulator(query);
+      for (let index = 0; index < 25; index += 1) {
+        acc.add(entry({
+          requestId: `request-${index}`,
+          model: `model-${index}`,
+          totalTokens: index < 23 ? 100 + index : index - 22,
+        }));
+      }
+      return acc.finish().series.at(-1);
+    };
+    expect(make("max")?.points.at(-1)).toBe(2);
+    expect(make("average")?.points.at(-1)).toBe(1.5);
+  });
+});
diff --git a/tests/windows/windows-secret-acl.test.ts b/tests/windows/windows-secret-acl.test.ts
index 29d1b7bc3f9..a5a2f379c54 100644
--- a/tests/windows/windows-secret-acl.test.ts
+++ b/tests/windows/windows-secret-acl.test.ts
@@ -636,11 +636,11 @@ describe("atomic secret temp writer portability", () => {
   test("sync and async secret temp writers use Bun-portable exclusive creation", async () => {
     // Bun on Windows misinterpreted the equivalent numeric O_* combination as
     // ENOENT, so every pid/config/oauth temp write failed during ocx start
-    // and on management-API config saves. Keep both writers on the portable
-    // exclusive-write spelling ("wx" keeps O_EXCL; 0o600 keeps the private
-    // mode) so the O_CREAT bit can never be dropped again.
+    // and on management-API config saves. EVERY temp writer keeps the portable
+    // exclusive spelling ("wx" keeps O_EXCL; 0o600 keeps the private mode); a
+    // count would go stale the next time a writer is added, so this is a set.
     const src = readFileSync(repoPath("src", "config", "atomic-write.ts"), "utf8");
-    expect(src.match(/openSync\(path, "wx", 0o600\)/g)).toHaveLength(2);
+    expect(new Set(src.match(/openSync\(path,[^)]*\)/g) ?? [])).toEqual(new Set(['openSync(path, "wx", 0o600)']));
   });
 });
 
diff --git a/tests/windows/windows-tray.test.ts b/tests/windows/windows-tray.test.ts
index a0c8ce7e58b..5b15a2ae4d4 100644
--- a/tests/windows/windows-tray.test.ts
+++ b/tests/windows/windows-tray.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import {
   copyFileSync,
   existsSync,
+  mkdirSync,
   mkdtempSync,
   readFileSync,
   renameSync,
@@ -21,6 +22,7 @@ import {
   readWindowsTrayRunValueWithAsyncRunner,
   readWindowsTrayRunValueWithRunner,
   replaceWindowsTrayOwnedFile,
+  windowsPowerShellPath,
   windowsTrayProcessArgs,
   windowsTrayRunValue,
   windowsTrayStatePathsOwned,
@@ -409,18 +411,155 @@ describe("Windows tray packaging and command safety", () => {
     // finally block kills the active probe, waits briefly, then completes it.
     expect(source).toContain("terminating active startup-health probe on tray shutdown");
     expect(source).toContain("startupProbeProcess.WaitForExit(3000)");
-    // Probe lifecycle maintenance runs even while the proxy is offline, so a hung
-    // diagnostic is cleaned up outside the online-only UI branch; new probes still
-    // start only while online.
-    expect(source).toContain("$script:online -and ($cameOnline -or $refreshDue)");
+    // Placement proof that runs on every platform: the behavioral test below is
+    // win32-only and the Windows CI leg runs on dispatch rather than on PRs,
+    // so merge-time coverage needs a lightweight check here too. The timeout
+    // maintenance must sit BEFORE the online-only UI branch: moving it inside
+    // flips the order and deleting it removes the anchor, and a plain
+    // substring could not tell inside from outside. The branch anchor is a
+    // line-anchored regex (not a substring) because the `$script:proxyPid`
+    // assignment a few lines above contains the same `if ($script:online) {`
+    // text inline.
+    const timeoutAnchorIdx = source.search(
+      /^\s*} elseif \(\$probeTimedOut\) \{$/m,
+    );
+    const onlineBranchIdx = source.search(/^\s*if \(\$script:online\) \{$/m);
+    expect(timeoutAnchorIdx).toBeGreaterThanOrEqual(0);
+    expect(onlineBranchIdx).toBeGreaterThanOrEqual(0);
+    expect(timeoutAnchorIdx).toBeLessThan(onlineBranchIdx);
+    // Hung-child termination itself is proven behaviorally by "terminates a hung
+    // startup-health probe without stacking a replacement" below.
     // The malformed-payload guard requires a real boolean, matching the shared
     // server-side parser instead of accepting any non-null rebootSafe value.
     expect(source).toContain("($parsed.rebootSafe -is [bool])");
     // If the async pipe setup fails after the child started, the child must be
-    // terminated, not merely disposed and lost.
-    expect(source).toContain("would leave the Bun child running");
+    // terminated, not merely disposed and lost. That catch block logs a
+    // distinct string, which breaks if the branch is deleted.
+    expect(source).toContain("startup-health probe launch cleanup failed");
   });
 
+  // Behavioral proof for the probe lifecycle: the driver loads the REAL probe
+  // functions out of windows-tray.ps1 (via the PowerShell AST, so comment and
+  // whitespace edits cannot fake it), stages a REAL hung child through the
+  // real Start-StartupHealthProbe, backdates its start past the real 30s
+  // timeout (elapsed time is an input to the maintenance branch, not the logic
+  // under test), then invokes the real Update-TrayState ticks and reports
+  // observable process facts. Offline proves the maintenance branch runs
+  // outside the online-only UI gate; Online proves the refresh throttle stacks
+  // no replacement. Either scenario fails if the Kill() is deleted (the child
+  // survives) or if maintenance moves inside the online branch (the offline
+  // child survives).
+  test("terminates a hung startup-health probe without stacking a replacement", async () => {
+    if (process.platform !== "win32") return;
+    const psExe = windowsPowerShellPath();
+    const driver = helperPath("windows-tray-probe-lifecycle-driver.ps1");
+    const trayScript = repoPath("src", "tray", "windows-tray.ps1");
+    for (const scenario of ["Offline", "Online"] as const) {
+      const directory = mkdtempSync(join(tmpdir(), "ocx-tray-probe-"));
+      const codexHome = join(directory, "codex");
+      const openCodexHome = join(directory, "ohome");
+      mkdirSync(codexHome, { recursive: true });
+      mkdirSync(openCodexHome, { recursive: true });
+      // The fake CLI name stays simple ASCII on purpose: the child engine here
+      // is powershell.exe (not bun), and its -Command parsing mangles paths
+      // with spaces or `&` even when quoted.
+      const hangChild = join(directory, "hangchild.ps1");
+      writeFileSync(hangChild, [
+        "$pidFile = $env:OCX_PROBE_TEST_PID_FILE",
+        "if ($pidFile) { Add-Content -LiteralPath $pidFile -Value $PID }",
+        "Start-Sleep -Seconds 120",
+      ].join("\r\n"));
+      const pidFile = join(directory, "pids.txt");
+      const resultPath = join(directory, "verdict.json");
+      let server: ReturnType<typeof Bun.serve> | undefined;
+      try {
+        if (scenario === "Online") {
+          server = Bun.serve({
+            hostname: "127.0.0.1",
+            port: 0,
+            fetch: request => {
+              if (new URL(request.url).pathname === "/healthz") {
+                return Response.json({ status: "ok", service: "opencodex", port: server!.port, pid: 424242 });
+              }
+              return new Response("not found", { status: 404 });
+            },
+          });
+          writeFileSync(
+            join(openCodexHome, "runtime-port.json"),
+            JSON.stringify({ port: server.port, hostname: "127.0.0.1" }),
+          );
+        } else {
+          // Port 1 refuses immediately, so the offline premise holds even on a
+          // dev machine already running the proxy on 10100.
+          writeFileSync(
+            join(openCodexHome, "runtime-port.json"),
+            JSON.stringify({ port: 1, hostname: "127.0.0.1" }),
+          );
+        }
+        const child = Bun.spawn([psExe,
+          "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+          "-File", driver,
+          "-TrayScriptPath", trayScript,
+          "-ChildEnginePath", psExe,
+          "-HangChildPath", hangChild,
+          "-CodexHome", codexHome,
+          "-OpenCodexHome", openCodexHome,
+          "-ResultPath", resultPath,
+          "-Scenario", scenario,
+        ], {
+          stdout: "pipe",
+          stderr: "pipe",
+          env: { ...process.env, OCX_PROBE_TEST_PID_FILE: pidFile },
+        });
+        const stdoutPromise = new Response(child.stdout).text();
+        const stderrPromise = new Response(child.stderr).text();
+        const finished = await Promise.race([
+          Promise.all([stdoutPromise, stderrPromise, child.exited])
+            .then(([stdout, stderr, exitCode]) => ({ stdout, stderr, exitCode })),
+          Bun.sleep(30_000).then(() => null),
+        ]);
+        if (!finished) {
+          try { child.kill(); } catch { /* already exited */ }
+          await Bun.sleep(500);
+          expect(false, `${scenario}: probe driver hung for 30s (a blocked tick would wait out the 120s sleeper)`).toBe(true);
+          return;
+        }
+        const { stdout, stderr, exitCode } = finished;
+        expect(exitCode, `${scenario}: driver exit=${exitCode} stdout=${stdout.slice(0, 500)} stderr=${stderr.slice(0, 500)}`).toBe(0);
+        expect(existsSync(resultPath), `${scenario}: driver exited 0 without writing ${resultPath}`).toBe(true);
+        const verdict = JSON.parse(readFileSync(resultPath, "utf8")) as {
+          scenario: string;
+          onlineObserved: boolean;
+          maintenanceMs: number;
+          totalMs: number;
+          childPid: number;
+          childTerminated: boolean;
+          probeCleared: boolean;
+          launches: number;
+        };
+        expect(verdict.scenario).toBe(scenario);
+        expect(verdict.onlineObserved, `${scenario}: online=${verdict.onlineObserved}; the premise of this scenario did not hold`).toBe(scenario === "Online");
+        expect(verdict.childTerminated, `${scenario}: hung probe child ${verdict.childPid} survived the timeout`).toBe(true);
+        expect(verdict.probeCleared, `${scenario}: probe reference was not released after the kill`).toBe(true);
+        expect(verdict.launches, `${scenario}: expected exactly 1 probe launch, saw ${verdict.launches}`).toBe(1);
+        expect(verdict.totalMs, `${scenario}: two ticks took ${verdict.totalMs}ms; a UI-thread block would hang until the 120s sleeper exits`).toBeLessThan(20_000);
+      } finally {
+        try {
+          if (existsSync(pidFile)) {
+            for (const line of readFileSync(pidFile, "utf8").split(/\r?\n/)) {
+              const pid = Number(line.trim());
+              if (Number.isSafeInteger(pid) && pid > 0) {
+                try { process.kill(pid); } catch { /* already reaped */ }
+              }
+            }
+          }
+        } catch { /* cleanup best-effort */ }
+        if (server) await server.stop(true);
+        removeTreeWithRetry(directory);
+      }
+    }
+  }, { timeout: SPAWN_BUDGET_MS });
+
   // This test really does launch PowerShell, which really does launch a Bun child, and
   // then rebinds the port to prove the child did not inherit the listen socket. Those
   // processes ARE the assertion — there is no version of this proof that fakes them.